@jsfkit/types 1.1.0 → 1.3.0

package/dist/index.d.ts

@@ -1,9 +1,22 @@
 /**
  * Defines the type of a value contained within a cell.
+ *
+ * | Value | Type    | Notes                                                                    |
+ * |-------|---------|--------------------------------------------------------------------------|
+ * | `b`   | Boolean |                                                                          |
+ * | `e`   | Error   | Formula error (cell value is the error code as a string)                 |
+ * | `n`   | Number  | Either integer or float                                                  |
+ * | `d`   | Date    | The {@link Cell.s | cell style} formats the integer cell value as a date |
+ * | `s`   | Text    |                                                                          |
+ * | `z`   | Empty   | Cell is empty                                                            |
  */
 type CellValueType = 'b' | 'e' | 'n' | 'd' | 's' | 'z';
 
-/** A cell comment. */
+/**
+ * A cell comment.
+ *
+ * @deprecated Use {@link Note | notes} and {@link ThreadedComment | threaded comments} instead.
+ */
 type Comment = {
     /** Author of the comment. */
     a: string;
@@ -13,6 +26,42 @@ type Comment = {
     t: string;
 };
 
+/**
+ * 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,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 | CellIds} separated by a colon (`:`) character.
+ *
+ * @pattern ^([A-Z]{1,3}[0-9]{1,7}):([A-Z]{1,3}[0-9]{1,7})$
+ */
+type CellRange = string;
+
+/**
+ * Data table configuration, present on the master cell of a data table range.
+ * Represents an Excel What-If Analysis data table.
+ */
+type DataTable = {
+    /** Range of cells the data table manages (e.g., "D3:D5") */
+    ref: CellRange;
+    /** Primary input cell reference to substitute */
+    r1: CellId;
+    /** Secondary input cell reference, for 2D data tables */
+    r2?: CellId;
+    /** Whether one-dimensional data table is a row (true) or a column (false/absent) */
+    dtr?: boolean;
+    /** Whether this is a two-dimensional data table */
+    dt2D?: boolean;
+};
+
 /**
  * A whole number without a fractional value.
  */
@@ -52,6 +101,8 @@ type Cell = {
     s?: integer;
     /**
      * Comments associated with the cell.
+     *
+     * @deprecated Use a worksheet's {@link Worksheet.notes | notes} and {@link Worksheet.comments | threaded comments} instead.
      */
     c?: Comment[];
     /**
@@ -60,27 +111,10 @@ type Cell = {
      * property).
      */
     t?: CellValueType;
+    /** Data table configuration. Present on the master cell of a data table range. */
+    dt?: DataTable;
 };
 
-/**
- * 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
@@ -129,6 +163,11 @@ type ExternalWorksheet = {
      * inputs to formulas in other sheets.
      */
     cells: Record<CellId, Cell>;
+    /**
+     * Indicates that the sheet data could not be refreshed/fetched from the external workbook.
+     * In XLSX, this corresponds to the refreshError="1" attribute on sheetData.
+     */
+    refreshError?: boolean;
 };
 
 /**
@@ -146,6 +185,11 @@ type External = {
     sheets: ExternalWorksheet[];
     /** Relevant defined names from an external workbook. */
     names: DefinedName[];
+    /**
+     * Indicates that the path to the external workbook file is unknown or missing.
+     * In XLSX, this corresponds to the xlPathMissing relationship type.
+     */
+    pathMissing?: boolean;
 };
 
 /**
@@ -177,6 +221,21 @@ type GridSize = {
     s?: integer;
 };
 
+/**
+ * An annotation associated with a cell.
+ *
+ * There is a maximum of one note per cell, and there is no way to reply to a note. For cell
+ * annotations with replies, see {@link ThreadedComment} and {@link Worksheet.comments}.
+ */
+type Note = {
+    /** Cell to which the note is attached (e.g. A1, E24). */
+    ref: CellId;
+    /** Name of the person who originally made this note. */
+    author: string;
+    /** Body text of the note. */
+    text: string;
+};
+
 /**
  * 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.
@@ -519,6 +578,125 @@ type Table = {
     style?: TableStyle;
 };
 
+/**
+ * Base type for text runs that annotate ranges within threaded comment text.
+ *
+ * A text run identifies a contiguous range of characters in the comment text, specified by
+ * zero-indexed start and end positions. Text runs allow metadata to be attached to specific
+ * portions of text, enabling features such as hyperlinks, mentions, and formatting.
+ *
+ * ## How text runs work
+ *
+ * Each text run specifies a range within the comment text using `start` (inclusive) and `end`
+ * (exclusive) character positions. For example, in the text "Hello @foo", a mention text run
+ * for "@foo" would have `start: 6` and `end: 10`.
+ *
+ * Multiple text runs can exist within a single comment, allowing different types of annotations
+ * to coexist (a mention and a hyperlink in the same text, for example).
+ *
+ * @see {@link MentionTextRun} for mentions of people
+ * @see {@link HyperlinkTextRun} for hyperlinks
+ */
+type TextRun = {
+    /** Starting character position of the run in the text (zero-indexed). */
+    start: integer;
+    /** Ending character position of the run in the text (zero-indexed, exclusive). */
+    end: integer;
+};
+
+/**
+ * A {@link TextRun | text run} representing a hyperlink within a threaded comment's text.
+ */
+type HyperlinkTextRun = TextRun & {
+    /** Discriminator to identify this as a hyperlink text run. */
+    type: 'hyperlink';
+    /** The URL that the hyperlink points to. */
+    url: string;
+};
+
+/**
+ * A {@link TextRun | text run} representing a mention of a person within a threaded comment's text.
+ */
+type MentionTextRun = TextRun & {
+    /** Discriminator to identify this as a mention text run. */
+    type: 'mention';
+    /**
+     * Unique identifier of the person being mentioned. Use this to find the person's details in a
+     * {@link Workbook.people | workbook's list of people}.
+     *
+     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
+     * no strict requirement.
+     */
+    personId: string;
+};
+
+/**
+ * An author of a threaded comment, or a person mentioned in a threaded comment.
+ */
+type Person = {
+    /**
+     * A unique id for the person.
+     *
+     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
+     * no strict requirement.
+     */
+    id: string;
+    /** The person's name as it should be shown to other users. */
+    displayName: string;
+    /**
+     * Optional provider-issued user identifier that varies in format depending on the provider. See
+     * {@link Person.providerId} for details on possible values.
+     */
+    userId?: string;
+    /**
+     * Specifies where the person's information came from. Excel supports the following values:
+     *
+     * - `None`: no specific provider; {@link Person.userId} is expected to be the person's name.
+     * - `AD`: Active Directory; {@link Person.userId} will be Active Directory id.
+     * - `Windows Live`: Microsoft account; {@link Person.userId} will be a 64-bit signed decimal.
+     * - `PeoplePicker`: SharePoint People Picker; {@link Person.userId} will be an email address.
+     */
+    providerId?: string;
+};
+
+/**
+ * A threaded comment that is attached to an individual cell.
+ */
+type ThreadedComment = {
+    /**
+     * Unique identifier for the comment.
+     *
+     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
+     * no strict requirement.
+     */
+    id: string;
+    /**
+     * Unique identifier of the parent comment, if this is a reply in a thread.
+     *
+     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
+     * no strict requirement.
+     */
+    parentId?: string;
+    /** A1-style reference to the cell this comment is attached to. */
+    ref: CellId;
+    /** Date and time the comment was written, as an ISO formatted string. */
+    datetime?: string;
+    /**
+     * Unique identifier of the person who authored this comment. Use this to find the person's
+     * details in a {@link Workbook.people | workbook's list of people}.
+     *
+     * Excel always uses a UUID in the format `{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}`, but JSF makes
+     * no strict requirement.
+     */
+    personId: string;
+    /** The comment text content. */
+    text: string;
+    /** Whether the comment has been marked as resolved. */
+    resolved?: boolean;
+    /** {@link TextRun | Text runs} that annotate ranges within the comment text. */
+    runs?: (MentionTextRun | HyperlinkTextRun)[];
+};
+
 /**
  * Directions on how formulas should be recalculated in the workbook.
  */
@@ -638,6 +816,8 @@ type Worksheet = {
     name: string;
     /** The cells belonging to the worksheet that have some data attached. */
     cells: Record<CellId, Cell>;
+    comments?: ThreadedComment[];
+    notes?: Note[];
     /** Widths and styles of the columns in the worksheet. */
     columns?: GridSize[];
     /** Heights and styles of the rows in the worksheet. */
@@ -711,6 +891,13 @@ type Workbook = {
     formulas?: string[];
     /** The different display configurations saved for the workbook. */
     views?: WorkbookView[];
+    /**
+     * Individuals who have written a threaded comment in this workbook, or who have been mentioned in
+     * one.
+     *
+     * @see {@link ThreadedComment}
+     */
+    people?: Person[];
 };
 
-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 };
+export type { BorderStyle, CalcProps, Cell, CellId, CellRange, CellValueType, Color, Comment, DataTable, DefinedName, External, ExternalWorksheet, GridSize, HAlign, HyperlinkTextRun, MentionTextRun, Note, PatternStyle, Person, PixelValue, Style, Table, TableColumn, TableColumnDataType, TableStyle, TableStyleName, TextRun, ThreadedComment, Underline, VAlign, Workbook, WorkbookView, Worksheet, WorksheetDefaults, WorksheetLayoutScales, WorksheetView };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsfkit/types",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "TypeScript types for JSF: a JSON spreadsheet representation",
   "license": "MIT",
   "type": "module",
@@ -41,13 +41,13 @@
     "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",
+    "@borgar/eslint-config": "^4.0.1",
     "@eslint/js": "^9.38.0",
     "eslint": "^9.38.0",
-    "globals": "^16.4.0",
-    "tsup": "^8.5.0",
-    "typedoc": "^0.28.14",
+    "globals": "^17.3.0",
+    "tsup": "^8.5.1",
+    "typedoc": "^0.28.17",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.46.1"
+    "typescript-eslint": "^8.56.0"
   }
 }