@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/goal-seek.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Goal Seek: find the input value that makes a formula cell hit a target.
+ *
+ * "What interest rate makes the monthly payment 1500?" You know the answer
+ * you want and one cell you are willing to change; the solver finds it.
+ *
+ * The method is secant with a bisection fallback, not Newton. Newton needs a
+ * derivative, and the function here is "recalculate a spreadsheet", which has
+ * no analytic one. Secant approximates the slope from two evaluations, which
+ * is the same information a numerical derivative would cost anyway.
+ *
+ * Bisection is the fallback because secant is fast but not safe: it can step
+ * to infinity on a flat stretch or oscillate on a kink. When a bracket is
+ * known - two inputs whose results straddle the target - bisection cannot
+ * fail, only be slow. Trying secant first and falling back keeps the common
+ * case quick and the awkward case terminating.
+ */
+export type GoalSeekOptions = {
+    /** Stop once the result is this close to the target. */
+    tolerance?: number;
+    /** Give up after this many recalculations. */
+    maxIterations?: number;
+    /** Where to start looking. Defaults to the input cell's current value. */
+    initialGuess?: number;
+    /** Keep the answer inside these bounds. A rate solver wants [0, 1]. */
+    min?: number;
+    max?: number;
+};
+export type GoalSeekResult = {
+    /** Whether the target was reached within tolerance. */
+    converged: boolean;
+    /** The input value found. Present even when it did not converge, so a
+     *  caller can show the closest attempt rather than nothing. */
+    value: number;
+    /** What the formula produced at that input. */
+    result: number;
+    iterations: number;
+    /** Why it stopped, when it did not converge. */
+    reason?: 'maxIterations' | 'notNumeric' | 'flat' | 'outOfBounds';
+};
+/**
+ * Solve `evaluate(input) = target` for `input`.
+ *
+ * `evaluate` sets the input cell, recalculates, and returns the formula
+ * cell's value. It is called many times, so it should be the workbook's own
+ * recalculation rather than anything that touches the DOM.
+ *
+ * The caller owns the input cell: this never writes. It reports the value it
+ * found and lets the caller decide whether to keep it, which is what makes
+ * Excel's "Goal Seek found a solution / OK or Cancel" dialog possible.
+ */
+export declare function goalSeek(evaluate: (input: number) => unknown, target: number, start: number, options?: GoalSeekOptions): GoalSeekResult;
+/** What `goalSeekCell` needs of a workbook. */
+export type GoalSeekSheet = {
+    getRaw(sheet: string, row: number, col: number): string;
+    setRaw(sheet: string, row: number, col: number, text: string): void;
+    getValue(sheet: string, row: number, col: number): unknown;
+};
+export type CellAddress = {
+    sheet: string;
+    row: number;
+    col: number;
+};
+/**
+ * Goal Seek over a workbook: change `input` until `formula` reads `target`.
+ *
+ * The input cell is RESTORED before returning, whatever the outcome. The
+ * solver writes to it dozens of times while searching, and leaving the last
+ * probe behind would be worse than not running: Excel shows you the answer
+ * and asks before keeping it, which it cannot do if the sheet has already
+ * moved. Apply `result.value` yourself once the user says yes.
+ */
+export declare function goalSeekCell(book: GoalSeekSheet, formula: CellAddress, input: CellAddress, target: number, options?: GoalSeekOptions): GoalSeekResult;

package/dist/sheet/goal-seek.js

@@ -0,0 +1,153 @@
+/**
+ * Goal Seek: find the input value that makes a formula cell hit a target.
+ *
+ * "What interest rate makes the monthly payment 1500?" You know the answer
+ * you want and one cell you are willing to change; the solver finds it.
+ *
+ * The method is secant with a bisection fallback, not Newton. Newton needs a
+ * derivative, and the function here is "recalculate a spreadsheet", which has
+ * no analytic one. Secant approximates the slope from two evaluations, which
+ * is the same information a numerical derivative would cost anyway.
+ *
+ * Bisection is the fallback because secant is fast but not safe: it can step
+ * to infinity on a flat stretch or oscillate on a kink. When a bracket is
+ * known - two inputs whose results straddle the target - bisection cannot
+ * fail, only be slow. Trying secant first and falling back keeps the common
+ * case quick and the awkward case terminating.
+ */
+const DEFAULTS = {
+    tolerance: 1e-7,
+    maxIterations: 100,
+};
+/**
+ * Solve `evaluate(input) = target` for `input`.
+ *
+ * `evaluate` sets the input cell, recalculates, and returns the formula
+ * cell's value. It is called many times, so it should be the workbook's own
+ * recalculation rather than anything that touches the DOM.
+ *
+ * The caller owns the input cell: this never writes. It reports the value it
+ * found and lets the caller decide whether to keep it, which is what makes
+ * Excel's "Goal Seek found a solution / OK or Cancel" dialog possible.
+ */
+export function goalSeek(evaluate, target, start, options = {}) {
+    const tolerance = options.tolerance ?? DEFAULTS.tolerance;
+    const maxIterations = options.maxIterations ?? DEFAULTS.maxIterations;
+    const min = options.min ?? Number.NEGATIVE_INFINITY;
+    const max = options.max ?? Number.POSITIVE_INFINITY;
+    let iterations = 0;
+    const clamp = (x) => Math.min(Math.max(x, min), max);
+    /** The signed distance from the target. Zero is the answer. */
+    const f = (x) => {
+        iterations += 1;
+        const raw = evaluate(x);
+        const n = typeof raw === 'number' ? raw : Number(raw);
+        return Number.isFinite(n) ? n - target : null;
+    };
+    let x0 = clamp(options.initialGuess ?? start);
+    let f0 = f(x0);
+    if (f0 === null) {
+        return { converged: false, value: x0, result: NaN, iterations, reason: 'notNumeric' };
+    }
+    if (Math.abs(f0) <= tolerance) {
+        return { converged: true, value: x0, result: f0 + target, iterations };
+    }
+    // A second point, offset enough to see a slope. Scaling with the guess
+    // matters: a fixed step of 1 is enormous next to an interest rate of 0.05
+    // and invisible next to a loan of 300000.
+    let x1 = clamp(x0 !== 0 ? x0 * 1.1 : 1);
+    if (x1 === x0)
+        x1 = clamp(x0 + 1);
+    let f1 = f(x1);
+    if (f1 === null) {
+        return { converged: false, value: x0, result: f0 + target, iterations, reason: 'notNumeric' };
+    }
+    /** Best seen so far, so a failure still reports the closest attempt. */
+    let best = Math.abs(f0) <= Math.abs(f1) ? { x: x0, fx: f0 } : { x: x1, fx: f1 };
+    const bracket = { lo: null, hi: null };
+    const noteBracket = (a, b) => {
+        if (a.fx === 0 || b.fx === 0)
+            return;
+        if ((a.fx < 0) !== (b.fx < 0)) {
+            bracket.lo = a.fx < 0 ? a : b;
+            bracket.hi = a.fx < 0 ? b : a;
+        }
+    };
+    noteBracket({ x: x0, fx: f0 }, { x: x1, fx: f1 });
+    while (iterations < maxIterations) {
+        if (Math.abs(f1) <= tolerance) {
+            return { converged: true, value: x1, result: f1 + target, iterations };
+        }
+        let next;
+        const slope = f1 - f0;
+        if (slope === 0) {
+            // Flat between the two points. Secant divides by this, so bisect if a
+            // bracket exists and give up if not - a genuinely flat function has no
+            // solution to find.
+            const { lo, hi } = bracket;
+            if (!lo || !hi) {
+                return { converged: false, value: best.x, result: best.fx + target, iterations, reason: 'flat' };
+            }
+            next = (lo.x + hi.x) / 2;
+        }
+        else {
+            next = x1 - f1 * ((x1 - x0) / slope);
+            // Secant can step anywhere, including outside a bracket we already
+            // trust. Bisect instead when it does.
+            const { lo, hi } = bracket;
+            const outside = !Number.isFinite(next) ||
+                (lo !== null && hi !== null && (next < Math.min(lo.x, hi.x) || next > Math.max(lo.x, hi.x)));
+            if (outside)
+                next = lo && hi ? (lo.x + hi.x) / 2 : clamp(next);
+        }
+        next = clamp(next);
+        if (next === x1) {
+            // Clamped against a bound and cannot move.
+            return {
+                converged: false, value: best.x, result: best.fx + target, iterations,
+                reason: Number.isFinite(min) || Number.isFinite(max) ? 'outOfBounds' : 'flat',
+            };
+        }
+        const fNext = f(next);
+        if (fNext === null) {
+            return { converged: false, value: best.x, result: best.fx + target, iterations, reason: 'notNumeric' };
+        }
+        if (Math.abs(fNext) < Math.abs(best.fx))
+            best = { x: next, fx: fNext };
+        noteBracket({ x: x1, fx: f1 }, { x: next, fx: fNext });
+        x0 = x1;
+        f0 = f1;
+        x1 = next;
+        f1 = fNext;
+    }
+    if (Math.abs(f1) <= tolerance) {
+        return { converged: true, value: x1, result: f1 + target, iterations };
+    }
+    return {
+        converged: false, value: best.x, result: best.fx + target,
+        iterations, reason: 'maxIterations',
+    };
+}
+/**
+ * Goal Seek over a workbook: change `input` until `formula` reads `target`.
+ *
+ * The input cell is RESTORED before returning, whatever the outcome. The
+ * solver writes to it dozens of times while searching, and leaving the last
+ * probe behind would be worse than not running: Excel shows you the answer
+ * and asks before keeping it, which it cannot do if the sheet has already
+ * moved. Apply `result.value` yourself once the user says yes.
+ */
+export function goalSeekCell(book, formula, input, target, options = {}) {
+    const original = book.getRaw(input.sheet, input.row, input.col);
+    const startText = original.trim();
+    const start = Number(startText);
+    try {
+        return goalSeek((x) => {
+            book.setRaw(input.sheet, input.row, input.col, String(x));
+            return book.getValue(formula.sheet, formula.row, formula.col);
+        }, target, Number.isFinite(start) ? start : 0, options);
+    }
+    finally {
+        book.setRaw(input.sheet, input.row, input.col, original);
+    }
+}

package/dist/sheet/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `@svgrid/enterprise/sheet` - the Excel keyboard layer on its own subpath.
+ *
+ * Importing the package barrel pulls every module it reaches into the chunk
+ * (the package sets no `sideEffects` flag), which for an app that only wants
+ * the shortcuts would mean shipping export, pivot, the scheduler and the board
+ * as well. This subpath is the shortcuts and nothing else. It matters more once
+ * the formula engine lands beside them in phase 2.
+ */
+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, 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, 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, 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, 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';
+export { splitFrozenRows, frozenColumnIds, applyFreeze, freezeAtActiveCell, freezeTopRow, freezeFirstColumn, unfreeze, type FreezeState, type FreezeSplit, } from './freeze.js';
+export { buildClipboardPayload, parseClipboard, parseClipboardText, parseClipboardHtml, readClipboardOrigin, anchorForeignFormulas, resolvePasteCell, planPaste, msoNumberFormat, numFmtFromMso, isR1C1, r1c1ToA1, type PasteSpecialOptions, type PasteWhat, type PasteOperation, type ClipboardCell, type ClipboardGrid, type PasteResolution, } from './paste-special.js';
+export { setFindReplaceHandler, setPasteSpecialHandler } from './shortcuts.js';
+export { default as SvFormulaBar } from '../SvFormulaBar.svelte';
+export { default as SvSheet } from '../SvSheet.svelte';
+export { default as SvSheetRibbon } from '../SvSheetRibbon.svelte';
+export { RIBBON_TABS, ribbonItems, withDecimals, applyBorders, type RibbonTab, type RibbonGroup, type RibbonItem, type RibbonOption, type RibbonItemKind, type RibbonActionId, type BorderPreset, } from './ribbon.js';
+export { RIBBON_ICONS, RIBBON_ICON_NAMES, type RibbonIconName, type IconPath } from './ribbon-icons.js';
+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, 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, 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, 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

@@ -0,0 +1,80 @@
+/**
+ * `@svgrid/enterprise/sheet` - the Excel keyboard layer on its own subpath.
+ *
+ * Importing the package barrel pulls every module it reaches into the chunk
+ * (the package sets no `sideEffects` flag), which for an app that only wants
+ * the shortcuts would mean shipping export, pivot, the scheduler and the board
+ * as well. This subpath is the shortcuts and nothing else. It matters more once
+ * the formula engine lands beside them in phase 2.
+ */
+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, 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, 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, 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, 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';
+export { splitFrozenRows, frozenColumnIds, applyFreeze, freezeAtActiveCell, freezeTopRow, freezeFirstColumn, unfreeze, } from './freeze.js';
+export { buildClipboardPayload, parseClipboard, parseClipboardText, parseClipboardHtml, readClipboardOrigin, anchorForeignFormulas, resolvePasteCell, planPaste, msoNumberFormat, numFmtFromMso, isR1C1, r1c1ToA1, } from './paste-special.js';
+export { setFindReplaceHandler, setPasteSpecialHandler } from './shortcuts.js';
+export { default as SvFormulaBar } from '../SvFormulaBar.svelte';
+export { default as SvSheet } from '../SvSheet.svelte';
+export { default as SvSheetRibbon } from '../SvSheetRibbon.svelte';
+export { RIBBON_TABS, ribbonItems, withDecimals, applyBorders, } from './ribbon.js';
+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, 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, evaluateSpill, formatValue } from './evaluate.js';
+export { ARRAY_FUNCTIONS } from './packs/array.js';
+export { FUNCTIONS, withCustomFunctions, } from './functions.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;
+}