@jsfkit/types 1.0.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT Licence
+
+Copyright (c) 2025 Borgar Þorsteinsson and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,3 @@
+# JSF Types
+
+The JSON Spreadsheet Format (JSF) is a file format for representing spreadsheets in JSON. This package contains the TypeScript types that describe the JSF format in full: workbooks, worksheets, cells, and everything in between.

package/dist/index.d.ts

@@ -0,0 +1,581 @@
+/**
+ * A whole number without a fractional value.
+ */
+type integer = number;
+
+/**
+ * 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 `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}
+     */
+    epoch?: 1900 | 1904;
+};
+
+/**
+ * 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 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.
+     */
+    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`.
+     *
+     * @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 `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}s 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 and calculation directives attached as they will not
+     * be rendered by a spreadsheet application.
+     */
+    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 `size` and `s` attributes affect. The range is expressed using integers, where
+ * 1 corresponds to column A or row 1.
+ *
+ * GridSize may have a style-index (`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.
+ *
+ * - `none`: no border is drawn.
+ * - `dashDot`: equivalent to SVG `stroke-dasharray="4 1 2 1"`, at a 1px width.
+ * - `dashDotDot`: equivalent to SVG `stroke-dasharray="4 1 2 1 2 1"`, at a 1px width.
+ * - `dashed`: equivalent to SVG `stroke-dasharray=""3 1`, at a 1px width.
+ * - `dotted`: equivalent to SVG `stroke-dasharray="1"`, at a 1px width.
+ * - `double`: draw two 1px wide continuous parallel lines with a 1px gap between them.
+ * - `hair`: draw a 1px wide pixel continuous hairline.
+ * - `medium`: draw a 2px wide pixel continuous line.
+ * - `mediumDashDot`: equivalent to SVG `stroke-dasharray="4 1 2 1"`, at a 2px width.
+ * - `mediumDashDotDot`: equivalent to SVG `stroke-dasharray="4 1 2 1 2 1"`, at a 2px width.
+ * - `mediumDashed`: equivalent to SVG `stroke-dasharray=""3 1`, at a 2px width.
+ * - `slantDashDot`: draw two 1px parallel dashed lines where the lower/left line 1px "behind" the
+ *   other, creating a slant.
+ * - `thick`: draw a 3px wide pixel continuous line.
+ * - `thin`: draw a 1px wide pixel continuous line.
+ */
+type BorderStyle = 'none' | 'dashDot' | 'dashDotDot' | 'dashed' | 'dotted' | 'double' | 'hair' | 'medium' | 'mediumDashDot' | 'mediumDashDotDot' | 'mediumDashed' | 'slantDashDot' | 'thick' | '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 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).
+ *
+ * - `center`: the horizontal alignment is centered, meaning the text is centered across the cell.
+ * - `centerContinuous`: the horizontal alignment is centered across multiple cells.
+ * - `distributed`: 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.
+ * - `fill`: 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`.
+ * - `general`: the horizontal alignment is general-aligned. Text data is left-aligned. Numbers,
+ *   dates, and times are right- aligned. Boolean types are centered.
+ * - `justify`: for each line of text, aligns each line of the wrapped text in a cell to the right
+ *   and left (except the last line).
+ * - `left`: aligns content at the left edge of the cell (even in RTL mode).
+ * - `right`: aligns content at the right edge of the cell (even in RTL mode).
+ */
+type HAlign = 'general' | 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | '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 `showRowStripes` active.
+     */
+    style?: TableStyle;
+};
+
+/**
+ * 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;
+};
+
+/**
+ * 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;
+};
+
+/**
+ * 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[];
+};
+
+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, Worksheet, WorksheetDefaults };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@jsfkit/types",
+  "version": "1.0.0",
+  "description": "A JSON representation for spreadsheets",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jsfkit/types.git"
+  },
+  "keywords": [
+    "excel",
+    "json",
+    "xlsx",
+    "jsf",
+    "spreadsheet",
+    "workbook",
+    "types",
+    "typescript"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "check": "npm run lint && npm run typecheck",
+    "lint": "eslint src",
+    "format": "eslint src --fix",
+    "typecheck": "tsc",
+    "release": "PACKAGE_VERSION=$(jq -r .version package.json) && echo \"About to tag and push v$PACKAGE_VERSION. Continue? (y/n)\" && read -r REPLY && [ \"$REPLY\" = \"y\" ] && git tag --annotate v$PACKAGE_VERSION --message=v$PACKAGE_VERSION && git push origin v$PACKAGE_VERSION"
+  },
+  "devDependencies": {
+    "@borgar/eslint-config": "^4.0.0",
+    "@eslint/js": "^9.38.0",
+    "eslint": "^9.38.0",
+    "globals": "^16.4.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.1"
+  }
+}