@jsfkit/types/dist/index.d.ts

TypeScript types for JSF: a JSON spreadsheet representation

/**
 * Defines the type of a value contained within a cell.
 */
type CellValueType = 'b' | 'e' | 'n' | 'd' | 's' | 'z';

/** A cell comment. */
type Comment = {
    /** Author of the comment. */
    a: string;
    /** Date of the comment (as an ISO formatted string). */
    d: string;
    /** The text content of the comment. */
    t: string;
};

/**
 * A whole number without a fractional value.
 */
type integer = number;

/**
 * A spreadsheet cell.
 */
type Cell = {
    /**
     * The value of the cell. The result of a calculation if the cell has a formula, otherwise safe to
     * assume that it's user-entered.
     *
     * @default null
     */
    v?: string | null | number | boolean;
    /**
     * Cell formula expression. When the value is a string it will be a formula with A1-style
     * references. When the value is a number is an index to a formula in the workbook's `formulas`
     * array.
     *
     * @see {@link Workbook.formulas}
     */
    f?: string | integer;
    /** The range of enclosing array if the formula is an array formula. */
    F?: string;
    /**
     * Cell hyperlink. Must be a URL.
     */
    l?: string;
    /**
     * An index to a style in the workbook's `styles`.
     *
     * @see {@link Workbook.styles}
     * @default 0
     */
    s?: integer;
    /**
     * Comments associated with the cell.
     */
    c?: Comment[];
    /**
     * The type of the value contained in the cell. Cells with errors or dates must include this
     * property, but it's otherwise optional (the type can be inferred from the {@link Cell.v}
     * property).
     */
    t?: CellValueType;
};

/**
 * A cell coordinate in an uppercase A1-style reference format (e.g. `AG14`).
 *
 * The lower top-left bounds of the reference are A1-inclusive, and the upper bottom-right bound are
 * `XFD1048576` inclusive.
 *
 * @pattern ^[A-Z]{1,3}[0-9]{1,3}$
 */
type CellId = string;

/**
 * A cell coordinate range in an uppercase A1-style reference format (e.g. `H6:J36`).
 *
 * The range consists of two {@link CellId | CellIds} separated by a colon (`:`) character.
 *
 * @pattern ^([A-Z]{1,3}[0-9]{1,3}):([A-Z]{1,3}[0-9]{1,3})$
 */
type CellRange = string;

/**
 * A defined name (also called "named range") is a labelled reference to a cell, range, constant or
 * formula. Meaningful labels can make formula expressions more readable and more robust to
 * worksheet edits.
 *
 * ```json
 * { "name": "Rates",
 *   "scope": "Sheet1",
 *   "value": "Sheet1!B1:C1" }
 * ```
 */
type DefinedName = {
    /**
     * A case-sensitive name. Names must start with a letter or `_`, and may only be made up of
     * letters as well as `\`, `_`, `.`, or `?`. Names must be a valid A1 or R1C1 reference.
     */
    name: string;
    /**
     * A formula expression, a reference, or value. Whatever the value is will be evaluated by a
     * spreadsheet engine as if it were an expression.
     */
    value?: string;
    /**
     * An optional worksheet name that defines the scope for this name. When this field is absent,
     * the defined name should be considered to be scoped to the workbook.
     */
    scope?: string;
    /**
     * An optional comment explaining the defined name.
     */
    comment?: string;
};

/**
 * A simple container sheet for cell values within an external workbook.
 */
type ExternalWorksheet = {
    /**
     * Name of the worksheet.
     */
    name: string;
    /**
     * The cells belonging to the worksheet that have any data attached.
     *
     * Typically, these will have only values attached, as external worksheet cells serve purely as
     * inputs to formulas in other sheets.
     */
    cells: Record<CellId, Cell>;
};

/**
 * A cell from another workbook (i.e. another file) that is referenced in this workbook.
 */
type External = {
    /** Filename being referenced. */
    name: string;
    /**
     * Relevant worksheets from an external workbook.
     *
     * These will only be a subset of sheets needed to run calculations, so indexes from the original
     * workbooks will not be preserved.
     */
    sheets: ExternalWorksheet[];
    /** Relevant defined names from an external workbook. */
    names: DefinedName[];
};

/**
 * A numeric value measured in pixels.
 *
 * @min 0
 */
type PixelValue = number;

/**
 * A size of a UI-grid measure over a range of items.
 *
 * GridSize information is run-length encoded. The start and end attributes indicate the range of
 * items that the {@link GridSize.size} and {@link GridSize.s} attributes affect. The range is
 * expressed using integers, where 1 corresponds to column A or row 1.
 *
 * GridSize may have a style-index ({@link GridSize.s}) attribute like individual cells. The styling
 * information on the column should be used for all cells that are not present in the sheet's cell
 * collection.
 */
type GridSize = {
    /** A 1-based inclusive start index. */
    start: integer;
    /** A 1-based inclusive end index. */
    end: integer;
    /** The size of the grid item in pixels. */
    size: PixelValue;
    /** An index to a style in the workbook styles. */
    s?: integer;
};

/**
 * The style to use when drawing a cell border. If the worksheet's zoom factor is changed the width
 * of the border is expected to stay the same.
 */
type BorderStyle = 
/** No border is drawn.*/
'none' | 
/** Equivalent to SVG `stroke-dasharray="4 1 2 1"`, at a 1px width.*/
'dashDot' | 
/** Equivalent to SVG `stroke-dasharray="4 1 2 1 2 1"`, at a 1px width.*/
'dashDotDot' | 
/** Equivalent to SVG `stroke-dasharray=""3 1`, at a 1px width.*/
'dashed' | 
/** Equivalent to SVG `stroke-dasharray="1"`, at a 1px width.*/
'dotted' | 
/** Draw two 1px wide continuous parallel lines with a 1px gap between them.*/
'double' | 
/** Draw a 1px wide pixel continuous hairline.*/
'hair' | 
/** Draw a 2px wide pixel continuous line.*/
'medium' | 
/** Equivalent to SVG `stroke-dasharray="4 1 2 1"`, at a 2px width.*/
'mediumDashDot' | 
/** Equivalent to SVG `stroke-dasharray="4 1 2 1 2 1"`, at a 2px width.*/
'mediumDashDotDot' | 
/** Equivalent to SVG `stroke-dasharray=""3 1`, at a 2px width.*/
'mediumDashed' | 
/**
 * Draw two 1px parallel dashed lines where the lower/left line 1px "behind" the other, creating
 * a slant.
 */
'slantDashDot' | 
/** Draw a 3px wide pixel continuous line.*/
'thick' | 
/** Draw a 1px wide pixel continuous line.*/
'thin';

/**
 * A hex-encoded RGB or RGBA value that conforms to the CSS4 color specification (e.g. `"#3cb371"`).
 *
 * @see {@link https://www.w3.org/TR/css-color-4/#hex-notation | CSS hexadecimal notation spec}
 * @pattern ^#([a-fA-F0-9]{3,4}|([a-fA-F0-9][a-fA-F0-9]){3,4})$
 */
type Color = `#${string}`;

/**
 * Specifies the horizontal alignment of content (text) within a container (cell).
 */
type HAlign = 
/**
 * The horizontal alignment is general-aligned. Text data is left-aligned. Numbers, dates, and
 * times are right- aligned. Boolean types are centered.
 */
'general' | 
/** Aligns content at the left edge of the cell (even in RTL mode). */
'left' | 
/** The horizontal alignment is centered, meaning the text is centered across the cell. */
'center' | 
/** Aligns content at the right edge of the cell (even in RTL mode). */
'right' | 
/**
 * Indicates that the value of the cell should be filled across the entire width of the cell. If
 * blank cells to the right also have the fill alignment, they are also filled with the value,
 * using a convention similar to `centerContinuous`.
 */
'fill' | 
/**
 * For each line of text, aligns each line of the wrapped text in a cell to the right and left
 * (except the last line).
 */
'justify' | 
/** The horizontal alignment is centered across multiple cells. */
'centerContinuous' | 
/**
 * Indicates that each 'word' in each line of text inside the cell is evenly distributed across
 * the width of the cell, with flush right and left margins.
 */
'distributed';

/**
 * The style of fill pattern used for a cell background. If the worksheets zoom factor is changed
 * the pixel scale of the pattern is still expected to stay the same.
 */
type PatternStyle = 'none' | 'solid' | 'mediumGray' | 'darkGray' | 'lightGray' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis' | 'gray125' | 'gray0625';

/**
 * Which type of underline to use when rendering text.
 */
type Underline = 'none' | 'single' | 'singleAccounting' | 'double' | 'doubleAccounting';

/** Vertical alignment of a cell content. */
type VAlign = 'bottom' | 'top' | 'center' | 'justify' | 'distributed';

/**
 * Style rules that specify the visual presentation of a cell.
 */
type Style = {
    /**
     * The name of the font family used to render text, e.g. `"Arial"`.
     *
     * @default "Calibri"
     */
    fontFamily?: string;
    /**
     * The font size in pixels.
     *
     * @default 11
     */
    fontSize?: PixelValue;
    /**
     * The color used to render text.
     *
     * @default "#000"
     */
    color?: Color;
    /**
     * Indicates whether the text is bold.
     *
     * @default false
     */
    bold?: boolean;
    /**
     * Indicates whether the text is italic.
     *
     * @default false
     */
    italic?: boolean;
    /**
     * Text underline decoration type.
     *
     * @default "none"
     */
    underline?: Underline;
    /**
     * The cell's background color.
     *
     * @default "#FFFFFF"
     */
    fillColor?: Color;
    /**
     * The color of a cell's background fill.
     *
     * @default "#000000"
     */
    patternColor?: Color;
    /**
     * The style of a cell's background fill.
     *
     * @default "none"
     */
    patternStyle?: PatternStyle;
    /**
     * Top border style.
     *
     * @default "none"
     */
    borderTopStyle?: BorderStyle;
    /**
     * Top border color.
     */
    borderTopColor?: Color;
    /**
     * Left border style.
     *
     * @default "none"
     */
    borderLeftStyle?: BorderStyle;
    /**
     * Left border color.
     */
    borderLeftColor?: Color;
    /**
     * Bottom border style.
     *
     * @default "none"
     */
    borderBottomStyle?: BorderStyle;
    /**
     * Bottom border color.
     */
    borderBottomColor?: Color;
    /**
     * Right border style.
     *
     * @default "none"
     */
    borderRightStyle?: BorderStyle;
    /**
     * Right border color.
     */
    borderRightColor?: Color;
    /**
     * Horizontal alignment of the cells [text] content.
     *
     * @default "general"
     */
    horizontalAlignment?: HAlign;
    /**
     * Vertical alignment of the cells [text] content.
     *
     * @default "bottom"
     */
    verticalAlignment?: VAlign;
    /**
     * Indicates whether text should be wrapped when it exceeds the cell's width.
     *
     * @default false
     */
    wrapText?: boolean;
    /**
     * Indicates whether the font-size should be automatically reduced in order to make the contents
     * of the cell visible.
     */
    shrinkToFit?: boolean;
    /**
     * The degrees to which the cell text should be rotated. Values range from 0 to 180, and 255 to
     * indicate vertical text. The origin of the rotation is the first letter of the text.
     */
    textRotation?: boolean;
    /**
     * Formatting directions for rendering the cell's value to text.
     */
    numberFormat?: string;
};

/** Describes the type of values found in the cells of a table column. */
type TableColumnDataType = 'text' | 'number' | 'boolean' | 'datetime' | 'unknown';

/**
 * Describes a column within a table.
 */
type TableColumn = {
    /**
     * The column name. It must be unique among column names in the same table when compared in a
     * case-insensitive manner. Must be non-empty. May contain white-space characters but not
     * exclusively.
     */
    name: string;
    /**
     * Describes the type of values found in the cells of the column, when a column contains only one
     * data type.
     *
     * @default "unknown"
     */
    dataType?: TableColumnDataType;
    /**
     * If the column is a calculated column, then this field must include the formula used.
     */
    formula?: string;
};

/** Excel's built-in table style names. */
type TableStyleName = 'TableStyleDark1' | 'TableStyleDark2' | 'TableStyleDark3' | 'TableStyleDark4' | 'TableStyleDark5' | 'TableStyleDark6' | 'TableStyleDark7' | 'TableStyleDark8' | 'TableStyleDark9' | 'TableStyleDark10' | 'TableStyleDark11' | 'TableStyleLight1' | 'TableStyleLight2' | 'TableStyleLight3' | 'TableStyleLight4' | 'TableStyleLight5' | 'TableStyleLight6' | 'TableStyleLight7' | 'TableStyleLight8' | 'TableStyleLight9' | 'TableStyleLight10' | 'TableStyleLight11' | 'TableStyleLight12' | 'TableStyleLight13' | 'TableStyleLight14' | 'TableStyleLight15' | 'TableStyleLight16' | 'TableStyleLight17' | 'TableStyleLight18' | 'TableStyleLight19' | 'TableStyleLight20' | 'TableStyleLight21' | 'TableStyleMedium1' | 'TableStyleMedium2' | 'TableStyleMedium3' | 'TableStyleMedium4' | 'TableStyleMedium5' | 'TableStyleMedium6' | 'TableStyleMedium7' | 'TableStyleMedium8' | 'TableStyleMedium9' | 'TableStyleMedium10' | 'TableStyleMedium11' | 'TableStyleMedium12' | 'TableStyleMedium13' | 'TableStyleMedium14' | 'TableStyleMedium15' | 'TableStyleMedium16' | 'TableStyleMedium17' | 'TableStyleMedium18' | 'TableStyleMedium19' | 'TableStyleMedium20' | 'TableStyleMedium21' | 'TableStyleMedium22' | 'TableStyleMedium23' | 'TableStyleMedium24' | 'TableStyleMedium25' | 'TableStyleMedium26' | 'TableStyleMedium27' | 'TableStyleMedium28';

/**
 * Describes which style is used to display this table, and specifies which portions of the table
 * have which styles applied.
 */
type TableStyle = {
    /**
     * The name of the table style to use with this table.
     *
     * If the value is null or omitted the table should not be rendered with any special styling (note
     * that this only applies if the style object itself is present).
     * @default null
     */
    name?: TableStyleName | null;
    /**
     * Whether row stripe formatting should be applied.
     *
     * @default true
     */
    showRowStripes?: boolean;
    /**
     * Whether column stripe formatting should be applied.
     *
     * @default false
     */
    showColumnStripes?: boolean;
    /**
     * Whether the first (leftmost) column in the table should be highlighted.
     *
     * @default false
     */
    showFirstColumn?: boolean;
    /**
     * Whether the last (rightmost) column in the table should be highlighted.
     *
     * @default false
     */
    showLastColumn?: boolean;
};

/**
 * A tabular data structure.
 *
 * The metadata contained in a table can be used to resolve structured references and evaluate
 * calculated columns.
 *
 * @see {@link https://support.microsoft.com/office/f5ed2452-2337-4f71-bed3-c8ae6d2b276e}
 */
type Table = {
    /**
     * The name of the table. This name must adhere to the same restrictions as defined names in
     * Excel. In particular, it cannot contain spaces.
     */
    name: string;
    /**
     * The name of the sheet in which the table is located.
     */
    sheet: string;
    /**
     * A non-prefixed range reference to the area containing the table. The range shall include the
     * column headers.
     */
    ref: CellRange;
    /**
     * An array of column objects. They shall be ordered from left to right, so that the first column
     * corresponds to the leftmost column in the referenced range and the last column corresponds to
     * the rightmost column.
     */
    columns: TableColumn[];
    /**
     * A non-negative integer specifying the number of totals rows at the bottom of the table. Default
     * to 0 if absent.
     *
     * @default 0
     */
    totalsRowCount?: integer;
    /**
     * A non-negative integer specifying the number of header rows at the top of the table. Default to
     * 1 if absent.
     * @default 1
     */
    headerRowCount?: integer;
    /**
     * Presentation information for the table. When not present tables should be rendered using
     * `"TableStyleMedium2"` style with {@link TableStyle.showRowStripes} set to `true`.
     */
    style?: TableStyle;
};

/**
 * Directions on how formulas should be recalculated in the workbook.
 */
type CalcProps = {
    /**
     * Specifies whether an attempt should be made to calculate formulas that contain circular
     * references. Defaults to `false` in Excel.
     */
    iterate: boolean;
    /**
     * The maximum number of calculation iterations, when {@link CalcProps.iterate} is `true`.
     * Defaults to `100` in Excel.
     */
    iterateCount: integer;
    /**
     * When a calculation iteration results in an absolute change that is less than iterateDelta,
     * then no further iterations should be attempted. Defaults to `0.001` in Excel.
     */
    iterateDelta: number;
    /**
     * Which of the two date systems the workbook uses. 1900 is the default.
     *
     * @see {@link https://support.microsoft.com/office/e7fe7167-48a9-4b96-bb53-5612a800b487 | Date systems in Excel}
     */
    epoch?: 1900 | 1904;
};

/**
 * A collection of default properties that apply to cells, rows, or columns in the worksheet.
 */
type WorksheetDefaults = {
    /** Default width of the UI-grid column. */
    colWidth: PixelValue;
    /** Default height of the UI-grid height. */
    rowHeight: PixelValue;
};

/**
 * Visual scale (aka zoom level, aka magnification) applied when displaying a worksheet.
 *
 * Each of the three layouts has its own scale. A scale is represented as a percentage, with `100`
 * (100%) being the default 1:1 scale. When a layout has no explicit scale, use 100%.
 */
type WorksheetLayoutScales = {
    /**
     * Zoom level for normal view.
     *
     * @min 10
     * @max 400
     * @defaultValue 100
     * */
    normal?: integer;
    /**
     * Zoom level for page layout view.
     *
     * @min 10
     * @max 400
     * @defaultValue 100
     */
    pageLayout?: integer;
    /**
     * Zoom level for page break preview (aka sheet layout view).
     *
     * @min 10
     * @max 400
     * @defaultValue 100
     */
    pageBreakPreview?: integer;
};

/**
 * A worksheet view.
 *
 * A worksheet view is a display configuration for a particular worksheet. Worksheet view settings
 * can include:
 *
 * - Active cell
 * - Selected ranges
 * - View type (normal, page layout, or page break layout)
 * - Zoom level
 *
 * Currently JSF does not include all available settings for a worksheet.
 */
type WorksheetView = {
    /**
     * The id of the workbook view this worksheet view belongs to.
     *
     * This is a zero-based index of the workbook view, as stored in the {@link Workbook.views} array.
     *
     * Within a single worksheet, each view must reference a distinct workbook view (i.e. no two views
     * in the same worksheet can share the same `workbookView` id). However, views from different
     * worksheets may reference the same workbook view.
     */
    workbookView: integer;
    /** Cell that is selected by default when the sheet is visible. */
    activeCell?: CellId;
    /** Ranges of cells that are selected by default when the sheet is visible. */
    activeRanges?: CellRange[];
    /**
     * The layout used to display the worksheet.
     *
     * @defaultValue "normal"
     */
    activeLayout?: 'normal' | 'pageLayout' | 'pageBreakPreview';
    /**
     * Scale (aka zoom level, aka magnification) applied when displaying a worksheet. Each different
     * layout has its own scale.
     */
    layoutScales?: WorksheetLayoutScales;
};

/**
 * A rectangle of cells. A sheet within a spreadsheet.
 */
type Worksheet = {
    /** Name of the worksheet. */
    name: string;
    /** The cells belonging to the worksheet that have some data attached. */
    cells: Record<CellId, Cell>;
    /** Widths and styles of the columns in the worksheet. */
    columns?: GridSize[];
    /** Heights and styles of the rows in the worksheet. */
    rows?: GridSize[];
    /** Ranges that capture which cells have been merged. */
    merges?: string[];
    /** A collection of default properties that apply to cells, rows, or columns in the worksheet. */
    defaults?: WorksheetDefaults;
    /**
     * Whether or not the sheet should be shown to a user in a UI displaying the workbook.
     *
     * - 0 = sheet is visible
     * - 1 = sheet is hidden
     * - 2 = sheet is "very hidden"
     *
     * @see {@link https://exceloffthegrid.com/make-excel-sheets-very-hidden/}
     */
    hidden?: 0 | 1 | 2;
    /** Indicates whether a hairline-grid should be drawn when displaying the sheet. */
    showGridLines?: boolean;
    /** The different display configurations saved for the worksheet. */
    views?: WorksheetView[];
};

/**
 * A workbook view.
 *
 * A workbook view is the display settings that apply to the entire workbook. Workbook view settings
 * include:
 *
 * - Active sheet
 * - Window size and position
 * - Window state (whether the window is maximised, minimised, etc)
 * - Scroll bar visibility
 *
 * Currently JSF does not include all available settings for a workbook.
 */
type WorkbookView = {
    /**
     * Index to the active sheet in this workbook view. The default value is 0 (first sheet).
     *
     * @defaultValue 0
     */
    activeSheet?: integer;
};

/**
 * A workbook is a collection of worksheets, styles, defined names, and other metadata. It's what's
 * commonly known as a spreadsheet.
 */
type Workbook = {
    /** Name of the workbook. In the case of a .xlsx file it will be the filename. */
    name: string;
    /** An ordered array of the worksheets in the workbook. */
    sheets: Worksheet[];
    /** An array of the workbook's defined names. */
    names?: DefinedName[];
    /** Metadata on the workbook's tables. */
    tables?: Table[];
    /** Directions on how formulas should be recalculated in the workbook. */
    calculationProperties?: CalcProps;
    /** Styles for cells in the workbook. */
    styles?: Style[];
    /** External cells referenced by the workbook. An external cell is a cell in another workbook. */
    externals?: External[];
    /**
     * Deduplicated formulas used in the workbook. Stored in R1C1 notation. Two formulas are
     * considered to be the same when their respective representations in R1C1 notation, are
     * identical.
     */
    formulas?: string[];
    /** The different display configurations saved for the workbook. */
    views?: WorkbookView[];
};

export type { BorderStyle, CalcProps, Cell, CellId, CellRange, CellValueType, Color, Comment, DefinedName, External, ExternalWorksheet, GridSize, HAlign, PatternStyle, PixelValue, Style, Table, TableColumn, TableColumnDataType, TableStyle, TableStyleName, Underline, VAlign, Workbook, WorkbookView, Worksheet, WorksheetDefaults, WorksheetLayoutScales, WorksheetView };