@sheetxl/models
Version:
Models - A Headless javascript spreadsheet library.
669 lines (668 loc) • 21.1 kB
TypeScript
import { Bounds, CellCoords, CellRangeCoords, SetOptions } from "@sheetxl/common";
import { SerializableProperties } from "../primitives";
import { AutoFillOptions } from "../utils/AutoFill";
import { RunCoords } from "../run/RunUtils";
import { HeaderOrientation } from "./ICellHeader";
import { ICellModel } from "./ICellModel";
import { ICellStyle, CellStyleUpdate, ICellStyleUpdater } from "./ICellStyle";
import { HyperlinkValues } from "./IHyperlink";
/**
* The type of cell within a sheet. These mostly follow the OOXML types.
*/
export declare const enum CellType {
/**
* A number.
* Note - Dates are expressed as formatted numbers.
*/
Number = "n",
/**
* A string.
*/
String = "s",
/**
* True or false.
*/
Boolean = "b",
/**
* A complex data type that is represented as a json.
*/
RichData = "r",
/**
* A value that is referenced in a single reference table. Excel does this for strings but we
* allow this for any any object type (useful for strings and RichData)
*/
Reference = "p",// Excel has string and inline strings. We currently do the opposite.
/**
* When The cell does not contain a value but still contains a style reference.
*/
Stub = "z",
/**
* Contains an error.
*/
Error = "e"
}
/**
* A complex object type. This allows for more complex data types to be stored in a cell.
*/
export interface IRichData {
readonly type: string;
toJSON(): any;
fromJSON(): any;
}
/**
* A list of Types that can be used for cell values.
*/
export type ICellValue = string | number | boolean | Date | Error | IRichData | null;
export interface ICellValueUpdater {
(original: ICellValue | null): ICellValue;
}
/**
* Used for updating cells.
* If a value is null then this will be treated as a remove.
*/
export interface CellUpdate {
/**
* If a Date is passed to it will be converted internally into number with a date format (unless the style format is also set)
*/
value?: ICellValue | ICellValueUpdater;
/**
* Update the style.
*/
style?: ICellStyle | CellStyleUpdate | ICellStyleUpdater | null;
/**
* If true then the value is interpreted as an error.
*/
error?: string;
/**
* Allow to to set a hyperlink to this value.
* @remarks
*/
hyperlink?: string | SerializableProperties<HyperlinkValues>;
formula?: string;
}
export type CellSimpleUpdateValue = CellUpdate | ICellModel | null;
export type CellUpdateValue = CellSimpleUpdateValue | ICellValue;
/**
* Expands the CellUpdateValue to support arrays or arrays of arrays (2d arrays)
*/
export type RangeUpdateValue = CellSimpleUpdateValue | ICellValue | CellSimpleUpdateValue[] | ICellValue[] | CellSimpleUpdateValue[][] | ICellValue[][];
/**
* Callback used for SetCells and CSV importing. When a cell value that is text is discovered this allows
* for custom parsing
*/
export type ICellValueParser = (text: string, parsed: ICellModel, coords: CellCoords, original?: CellUpdateValue) => CellUpdateValue | void;
export interface CellUpdateFromStringOptions {
/**
* Ignore the quote prefix. Used for CSV import
*/
ignoreQuotePrefix?: boolean;
/**
* If true then number parsed as a dates will use the 1904.
* @defaultValue 'the workbook setting'.
*/
date1904?: boolean;
/**
* Allow for custom callback when doing updates. Used by CSV import and any
* other bindings.
*/
parser?: ICellValueParser;
}
/**
* This is either:
* 1. A CellCoords
* 2. A string that can be parsed into a CellCoords (e.g. 'A1')
*/
export type CellCoordsAddress = CellCoords | string;
/**
* This is either:
* 1. A CellRange
* 2. A string that can be parsed into a CellRange (e.g. 'A1:B2')
* 3. A named range
*/
export type CellRangeCoordsAddress = Partial<CellRangeCoords> | string;
/**
* Used for setting a collection of cells.
* ## update
* When updating a cell the existing value are merged.
*
* To 'revert a value' back to it's original state' set the value to null. For example to remove all styles set the style to null.
* Setting a value to null doesn't mean that it will be null but rather means that it will revert to the 'defaulted' value.
* For example setting numberFormat to null will revert it to the default or 'General' for the default Normal style.
* To clear/revert all values set the update to null.
*
* @remarks
* * Some copy operations replace a cell value. This is done by updating with null then updating a second time.
* * passing a value as undefined is treated the same as not being passed at all.
*
*/
export interface CellAddressValuePair {
/**
* Allows for either a Cell or a Range
*/
address: CellCoordsAddress | CellRangeCoordsAddress;
/**
* Used to indicate the update type.
* This can be a either a CellUpdate or a CellModel or a simple value
* * A null means to completely clear the cell.
* * An ICellModel is a copy
* * CellUpdate provides detailed updates
* @see {@link CellUpdate}
*/
update: CellUpdateValue;
}
export interface CoordsValuePair<T> {
/**
* The Coords of the value
*/
coords: CellCoords;
/**
* The value at the address
*/
value: T;
}
/**
* Access the context of the cell is sometime slower.
*/
export interface CellVisitorContext {
/**
* Returns the entire Cell object.
* @remarks
* This is generally slower than using just t he value
*/
getCell(): ICellModel;
/**
* Utility method to return the coords as a string
*/
getAddress(coords?: CellCoords): string;
}
export type CellVisitor<T = any> = (value: ICellValue, coords: CellCoords, context: CellVisitorContext) => {
break: T;
} | void;
export interface CellVisitorOptions {
/**
* The containing range for the scan.
* @remarks
*
* If not specified will scan the the smallest area containing data all of the data.
*/
bounds?: CellRangeCoordsAddress;
/**
* When scanning skip cells that are hidden via headers
* @defaultValue false
* @remarks
* optionally a header orientation for skipping case be passed in.
* An example of this is for sorting where the sort direction (row) skips hidden rows but the column direction does not.
*/
includeHiddenHeaders?: boolean | HeaderOrientation;
/**
* Include styled cells into scan.
* @defaultValue false
*/
includeStyles?: boolean | HeaderOrientation;
/**
* If true will only visit non-empty cells.
* This is a potentially huge performance improvement if set to false.
*
* @remarks
*
* If includeEmpty is true this will always return rectangular results.
* If bounds are provided it will provide empty spaces before and after.
* If passing a large bound care must be taken.
*
* @defaultValue false
*/
includeEmpty?: boolean;
/**
* Scan direction is row
* @defaultValue true
*/
isRowScan?: boolean;
/**
* Will attempt to start visiting at this location.
* @remarks
* If this is not within the bounds then the visit will be skipped.
* @defaultValue the topLeft of the bounds (or bottomRight if isReverse)
*/
from?: CellCoordsAddress;
/**
* Iterate in reverse order.
* @defaultValue false
*/
isReverse?: boolean;
}
export interface SetCellOptions extends SetOptions {
/**
* If this is set to true string values will try to be coerce into numbers, dates, and booleans.
*
* @remarks
* If a function is passed this will still attempt to coerce the value but will also called the function
* and take it's return value if not void
*/
parseTextAsValue?: boolean | CellUpdateFromStringOptions;
/**
* Determines if the cells that are set should autoFit.
* @defaultValue true (meaning autoFit in both directions)
*/
autoFit?: boolean | AutoFitOptions | HeaderOrientation;
/**
* If true then the selection will not be included in an undo operation.
* @defaultValue false
*/
noSelectOnUndo?: boolean;
}
export interface AutoFitOptions {
/**
* Clear any custom sizes
* @defaultValue true
*/
clearCustom?: boolean;
/**
* Only autofit values if larger then current size
* @defaultValue false
*/
expandOnly?: boolean;
/**
* Best fit using all of the content.
* @remarks
* The full content include all of the text for strings and all of the decimals for numbers.
* When false the numbers will include as few decimals as allowed overflow into the next cell.
* @defaultValue false
*/
fullContent?: boolean;
/**
* When scanning to expand the oppRunBounds are used first.
* If expandOnly is false then these will be treated as a hint. If all of the values returned within this bounds are larger
* then the current size we will stop measuring.
*/
oppRunBounds?: RunCoords;
}
export declare enum SortOn {
Value = "value",
FillColor = "fillColor",// Excel calls this CellColor
FontColor = "fontColor",
Icon = "icon"
}
export interface CellValueComparator {
type: CellType | string;
/**
* Used for sorting callback. Equal values and null values are presorted and
* do not need to be handled in the comparator implementation
* @remarks
* the options are from the defaultOptions and the dataOptions provided for the
* given CellType.
*
* @param options
*/
comparator: (a: ICellValue, b: ICellValue, options?: Intl.Collator | any) => number;
defaultOptions?: Intl.Collator | any;
}
export declare enum RangeOrientation {
Columns = "columns",// vertical
Rows = "rows"
}
export interface SortCriteria {
/**
* 0-based offset for the header based on orientation
*
* @defaultValue The first index of the selected range
*/
offset?: number;
/**
* Ascending is smallest to largest
* @defaultValue true
*/
ascending?: boolean;
/**
* Additional options for sorting
*
* @remarks
* * Excel has a matchCase flag but we use Intl.CollatorOptions
* * Excel has Normal | 'TextAsNumber' but we use Intl.CollatorOptions
*/
dataOptions?: Record<CellType, Intl.CollatorOptions> | any;
}
export interface SortField extends SortCriteria {
}
/**
* Options for sorting a range.
*/
export interface RangeSortOptions extends SortCriteria {
/**
* @defaultValue RangeOrientation.Rows
*/
orientation?: RangeOrientation;
/**
*
* @defaultValue true
*/
hasHeader?: boolean;
/**
* Allows you to override individual sorts for each additional level.
* All sort criteria default to the sort criteria specified on the sort option.
*/
fields?: SortField[];
/**
* Used for undo/redo/collaboration/version
*/
description?: string;
/**
* Determine if sort should honor hidden headers.
* @defaultValue false
* @remarks
* The sort function does not but the UI does.
*/
includeHiddenHeaders?: boolean;
/**
* Determine the behavior of sorting merged cells.
* By default merged cells will sort with their
* merges intact but sorting will be limited
* to sorting with all merges of the same size.
* @defaultValue true
*/
preserveMerges?: boolean;
}
/**
* Options to skip coping some of the values.
* Setting true to all of these will result in nothing being copied.
* Setting true to all but value will be a logic copyContentsOnly.
*/
export interface CopyCellsAdjustments {
/**
* @defaultValue false
*/
skipStyle?: boolean;
/**
* @defaultValue false
*/
skipValue?: boolean;
/**
* @defaultValue false
*/
skipNumberFormat?: boolean;
/**
* @defaultValue false
*/
skipFormula?: boolean;
/**
* @defaultValue false
*/
skipComments?: boolean;
}
export interface CopyOptions extends SetOptions {
/**
* If true then during copy the old values will be remove. (if possible)
* @defaultValue false
*/
isCut?: boolean;
}
/**
* Options for copying cells.
*/
export interface CopyCellsOptions extends SetCellOptions, CopyOptions {
/**
* When pasting from a smaller range to a larger range copy will repeat or 'wallpaper' the
* source values.
*
* Note - If there is only a single cell selected and adjustSelection is true then this will still expand to fit
*/
fitDestination?: boolean;
/**
* @defaultValue false
*/
transpose?: boolean;
/**
* Note - This needs to be sorted with autoFill
* @defaultValue true
*/
skipBlanks?: boolean;
/**
* If a cell is merged retain this. Note - Excel sets this to false when copy content only
* @defaultValue false
*/
skipMerges?: boolean;
/**
* This will skip trying to copy cells that were styled by headers.
* Note - If a cell has content it will still be copied.
* Note - This a performance hint as setting adjustCell.skipStyle will have the same result
* but required unnecessary processing of headers
* @defaultValue false
*/
skipHeaderStyles?: boolean;
/**
* The default is to only keep the source header size if it is customized or the
* size of the selection fits the destination
* @default
*/
copySourceHeaderSize?: boolean;
/**
* This allows either the CopyCellsAdjustments or a callback that returns the same arguments types
* as CellPairs. Note
*/
adjustCells?: CopyCellsAdjustments | ((value: ICellValue, context: CellVisitorContext, from: CellCoords, to: CellCoords) => CellUpdate | ICellModel | null);
/**
* @defaultValue true
*/
adjustSelection?: boolean;
}
/**
* For protecting resources. This provides a hasValue value (encrypted password).
* @see {@link https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.presentation.modificationverifier?view=openxml-2.8.1}
*/
export interface ModificationVerifier {
hashValue: string;
/**
* @defaultValue SHA-512
*/
algorithmName?: string;
saltValue?: string;
/**
* The number of hash iterations performed when protecting or un-protecting
* @defaultValue 1000
*/
spinCount?: number;
}
/**
* When merging allows for the type of merge to be specified.
*/
export declare enum MergeType {
All = "all",
Columns = "columns",
Rows = "rows"
}
/**
* Directive to indicate how to clear.
*/
export declare enum ClearType {
All = "all",
Formats = "formats",
Contents = "contents"
}
/**
* Provide the starting point and amount of an Autofill.
* Note - The direction is determined as a separate argument.
*/
export interface AutoFillRange {
template: CellRangeCoords;
/**
* @param direction
* @param amount must be greater than 0. If the value is zero then it will use the top/left value of the template and fill in that direction
*/
amount: number;
}
/**
* Additional options for AutoFill.
*/
export interface RangeAutoFillOptions extends AutoFillOptions, SetOptions {
/**
* If this is set to true then values are not committed but autoFill function will still return a preview function
* @defaultValue false
*/
previewOnly?: boolean;
/**
* @defaultValue true
*/
adjustSelection?: boolean;
/**
* If set to true this will use the cell values and just iterator over the cells.
*/
copyCells?: boolean;
}
/**
* Interface for interacting with a bounded ranges of cells.
*/
export interface ICellRange {
/**
* The bounds for the range.
*/
bounds(): CellRangeCoords;
/**
* Advanced and performant way to iteratively values.
* This allows for visiting only values that are not empty.
* @remarks
* * Visitors can return a 'break' value to stop the visit.
* * skipEmpty will ensure that only non-empty cells are visited.
* * getContext().getCell() requires additional work over getCoord or reading value.
*/
forEach(visitor: CellVisitor, options?: CellVisitorOptions): void;
/**
* A 2d list of values as convenience. This calls forEach and builds a 2d array.
* @remarks
* This guarantees that the a 2D value with a least 1 value will always be returned. The value
* may be null.
*
* @includeHidden @defaultValue true
* By default values dates are returns as JSDates
* @datesAsJSDate @defaultValue true
*/
values(options?: {
includeHidden?: boolean;
datesAsJSDate?: boolean;
}): ICellValue[][];
/**
* A 2d list of ICellModels as convenience. This calls forEach and builds a 2d array .
* @includeHidden @defaultValue true
*/
cells(options?: {
includeHidden?: boolean;
}): ICellModel[][];
/**
* Convenience that returns the first cell
* */
cell(options?: {
includeHidden?: boolean;
}): ICellModel;
/**
* Convenience that returns the first cell
*/
value(options?: {
includeHidden?: boolean;
datesAsJSDate?: boolean;
}): ICellValue;
/**
* If the range is valid. A range can be invalid if removed, has incorrect, or even an incorrect format.
*/
isValid(): boolean;
/**
* Returns the address as a string
*/
toString(): string;
}
/**
* JSON loosely similar to OOXML Cell.
*/
export interface CellJSON {
v?: string | number | boolean | null;
/**
* If not specified then will be inferred from the value
*/
t?: CellType;
/**
* Unparsed formula value
*/
f?: string;
/**
* Comments
*/
c?: string[];
/**
* Hyperlink
*/
l?: string | SerializableProperties<HyperlinkValues>;
/**
* Style id
*/
s?: number;
}
/**
* Overflow cells are cells that have text that 'spills' to the left or the right.
*
* Specifying overflow cells allows cell to spill and directs the grid to do multiple things:
* 1. Allows for 'out of view' cells to be located so that their overflow content can be rendered if required.
* 2. Track interruptions to spills to limit painting. An overflow cell will not paint 'past' a cell that that returns true
* from the isContentfulCell parameter.
* 3. Skip drawings gridlines where overflow occurs.
*
* These are not typical z-order because if a cell is 'contentFul' to the left or the right it
* will stop the overflow. (not just cover it, meaning that if the overflow continues past
* the cell 'interrupting' the overflow then it does not continue to render).
*
* Overflowed cells are always rendered above other cells. (In the event that two overflowed
* cells intersect the render over will determine which one is above)
*
* An important consideration is that this is not just a property of a cell because
* when rendering a viewport we need to know about overflows that 'spill' into the viewport and ensure they
* are also rendered.
*
* isContentfulCell argument is required because a cell may render something that the overflow
* is allowed to 'render on top of'. For example fill backgrounds, borders, comments, or other overflow values.
*/
export interface OverflowedCell {
/**
* The cell value that is overflowing.
*/
cell: ICellModel;
/**
* The cell coord that is overflowing.
*/
coords: CellCoords;
/**
* The number of cells that this overflows to the left.
* This is optional but is ignored if not greater than 0.
* Note - This is not pixels but is the number of cells to overflow.
*/
leftOverflowIndex: number;
/**
* The number of cells that this overflows to the right.
* This is optional but is ignored if not greater than 0.
* Note - This is not pixels but is the number of cells to overflow.
*/
rightOverflowIndex: number;
/**
* The number of pixels that this overflows to the left.
* This is optional but is ignored if not greater than 0.
*/
leftOverflowOffset: number;
/**
* The number of pixels that this overflows to the right.
* This is optional but is ignored if not greater than 0.
*/
rightOverflowOffset: number;
/**
* This number of cells that an overflow is spanning. This is
* typically 1 but can be greater than 1 if a continuous fill is used.
*/
colSpan: number;
/**
* This is the bounds of the cells excluding the overflows relative to the cell.
*/
colBounds: Bounds;
/**
* The location of the anchor relative to the cell.
*/
anchorBounds: Bounds;
}
export interface OverflowCellsLookup {
(range: CellRangeCoords): OverflowedCell[];
}
export declare const FormulaErrorsMap: Set<String>;
//# sourceMappingURL=CellTypes.d.ts.map