@jsfkit/types 1.1.0 → 1.2.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;
@@ -52,6 +65,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[];
     /**
@@ -129,6 +144,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 +166,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 +202,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 +559,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 +797,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 +872,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, 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.2.0",
   "description": "TypeScript types for JSF: a JSON spreadsheet representation",
   "license": "MIT",
   "type": "module",