@jsfkit/types 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,35 +1,3 @@
-/**
- * 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.
  */
@@ -45,6 +13,11 @@ type Comment = {
     t: string;
 };
 
+/**
+ * A whole number without a fractional value.
+ */
+type integer = number;
+
 /**
  * A spreadsheet cell.
  */
@@ -60,6 +33,8 @@ type Cell = {
      * 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. */
@@ -71,6 +46,7 @@ type Cell = {
     /**
      * An index to a style in the workbook's `styles`.
      *
+     * @see {@link Workbook.styles}
      * @default 0
      */
     s?: integer;
@@ -80,7 +56,8 @@ type 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).
+     * property, but it's otherwise optional (the type can be inferred from the {@link Cell.v}
+     * property).
      */
     t?: CellValueType;
 };
@@ -98,7 +75,7 @@ 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.
+ * 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})$
  */
@@ -148,8 +125,8 @@ type ExternalWorksheet = {
     /**
      * 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.
+     * Typically, these will have only values attached, as external worksheet cells serve purely as
+     * inputs to formulas in other sheets.
      */
     cells: Record<CellId, Cell>;
 };
@@ -182,11 +159,12 @@ 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.
+ * 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 (`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.
+ * 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. */
@@ -202,51 +180,81 @@ type GridSize = {
 /**
  * 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';
+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 spec}
+ * @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).
- *
- * - `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';
+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
@@ -506,11 +514,38 @@ type Table = {
     headerRowCount?: integer;
     /**
      * Presentation information for the table. When not present tables should be rendered using
-     * `"TableStyleMedium2"` style with `showRowStripes` active.
+     * `"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.
  */
@@ -521,6 +556,80 @@ type WorksheetDefaults = {
     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.
  */
@@ -530,13 +639,13 @@ type Worksheet = {
     /** 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[];
+    columns?: GridSize[];
     /** Heights and styles of the rows in the worksheet. */
-    rows: GridSize[];
+    rows?: GridSize[];
     /** Ranges that capture which cells have been merged. */
-    merges: string[];
+    merges?: string[];
     /** A collection of default properties that apply to cells, rows, or columns in the worksheet. */
-    defaults: WorksheetDefaults;
+    defaults?: WorksheetDefaults;
     /**
      * Whether or not the sheet should be shown to a user in a UI displaying the workbook.
      *
@@ -549,6 +658,30 @@ type Worksheet = {
     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;
 };
 
 /**
@@ -561,13 +694,13 @@ type Workbook = {
     /** An ordered array of the worksheets in the workbook. */
     sheets: Worksheet[];
     /** An array of the workbook's defined names. */
-    names: DefinedName[];
+    names?: DefinedName[];
     /** Metadata on the workbook's tables. */
-    tables: Table[];
+    tables?: Table[];
     /** Directions on how formulas should be recalculated in the workbook. */
     calculationProperties?: CalcProps;
     /** Styles for cells in the workbook. */
-    styles: Style[];
+    styles?: Style[];
     /** External cells referenced by the workbook. An external cell is a cell in another workbook. */
     externals?: External[];
     /**
@@ -576,6 +709,8 @@ type Workbook = {
      * 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, Worksheet, WorksheetDefaults };
+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 };

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@jsfkit/types",
-  "version": "1.0.0",
-  "description": "A JSON representation for spreadsheets",
+  "version": "1.1.0",
+  "description": "TypeScript types for JSF: a JSON spreadsheet representation",
   "license": "MIT",
   "type": "module",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jsfkit/types.git"
   },
+  "homepage": "https://jsfkit.github.io/types/",
+  "bugs": "https://github.com/jsfkit/types/issues",
   "keywords": [
     "excel",
     "json",
@@ -24,11 +26,14 @@
       "import": "./dist/index.js"
     }
   },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "files": [
     "dist"
   ],
   "scripts": {
     "build": "tsup",
+    "build:docs": "typedoc",
     "check": "npm run lint && npm run typecheck",
     "lint": "eslint src",
     "format": "eslint src --fix",
@@ -41,6 +46,7 @@
     "eslint": "^9.38.0",
     "globals": "^16.4.0",
     "tsup": "^8.5.0",
+    "typedoc": "^0.28.14",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.46.1"
   }