@jsfkit/types 2.0.0-rc1 → 2.0.0

package/dist/index.d.ts

@@ -2789,17 +2789,27 @@ type PivotFieldAxis = 'row' | 'col' | 'page';
  */
 type PivotAreaAxis = PivotFieldAxis | 'values';
 
+/**
+ * A field index in a pivot table context. Either a non-negative index into the
+ * pivot table's {@link PivotField} array (or the cache's field array when
+ * `cacheIndex` is true), or one of the following sentinel values:
+ *
+ * - **`-2`** — the "Values" virtual field, representing the data area when a
+ *   pivot table has multiple data fields.
+ * - **`-1`** — no field (references nothing).
+ *
+ * @group PivotTables
+ */
+type PivotFieldIndex = integer;
+
 /**
  * A reference within a pivot area, identifying specific field items that define the area's scope.
  *
  * @group PivotTables
  */
 type PivotAreaReference = {
-    /**
-     * Index of the field this reference applies to.
-     * The special value `4294967294` (0xFFFFFFFE) refers to the data (values) field.
-     */
-    field?: integer;
+    /** The field this reference applies to. See {@link PivotFieldIndex} for valid values. */
+    field?: PivotFieldIndex;
     /**
      * Whether this reference participates in the selection. When false, the reference
      * constrains the area without being selected itself.
@@ -2916,8 +2926,8 @@ type PivotArea = {
      * @default 'normal'
      */
     type?: PivotAreaType;
-    /** The field index this area applies to. */
-    field?: integer;
+    /** The field this area applies to. See {@link PivotFieldIndex} for valid values. */
+    field?: PivotFieldIndex;
     /**
      * Whether the area applies only to data cells (excluding labels).
      *
@@ -3077,6 +3087,8 @@ type PivotCacheRangePr = {
  * A shared item value in a pivot cache field. Each item represents a unique value found in the
  * source data for that field.
  *
+ * A cache may contain items which longer appear in the source data, marked with `u: true`.
+ *
  * @group PivotTables
  */
 type PivotCacheSharedItem = PivotCacheSharedItemStr | PivotCacheSharedItemNum | PivotCacheSharedItemBool | PivotCacheSharedItemDate | PivotCacheSharedItemErr | PivotCacheSharedItemNil;
@@ -3084,30 +3096,36 @@ type PivotCacheSharedItem = PivotCacheSharedItemStr | PivotCacheSharedItemNum |
 type PivotCacheSharedItemStr = {
     t: 's';
     v: string;
+    u?: boolean;
 };
 /** A numeric shared item. @group PivotTables */
 type PivotCacheSharedItemNum = {
     t: 'n';
     v: number;
+    u?: boolean;
 };
 /** A boolean shared item. @group PivotTables */
 type PivotCacheSharedItemBool = {
     t: 'b';
     v: boolean;
+    u?: boolean;
 };
 /** A date shared item (ISO 8601 string). @group PivotTables */
 type PivotCacheSharedItemDate = {
     t: 'd';
     v: string;
+    u?: boolean;
 };
 /** An error shared item (e.g. `"#REF!"`). @group PivotTables */
 type PivotCacheSharedItemErr = {
     t: 'e';
     v: string;
+    u?: boolean;
 };
 /** An empty/missing shared item. @group PivotTables */
 type PivotCacheSharedItemNil = {
     t: 'z';
+    u?: boolean;
 };
 
 /**
@@ -3299,6 +3317,13 @@ type PivotCacheBase = {
      * `"{93AACE53-8F3A-A04A-893A-A439866B3165}"` assigned by Excel 2014+ for revision tracking.
      */
     uid?: string;
+    /**
+     * Whether the cache needs to be refreshed. When true, the pivot table's cached data
+     * is out of date with respect to its source.
+     *
+     * @default false
+     */
+    invalid?: boolean;
 };
 
 /**
@@ -3493,7 +3518,7 @@ type PivotDataField = {
      * The index of the base item used for "show data as" calculations. Only meaningful when
      * {@link showDataAs} is set to a relative calculation mode.
      *
-     * @default 1048832
+     * @default 1048832 (0x100100, sentinel meaning "use the previous item")
      */
     baseItem?: integer;
     /** The number format code for this data field's values (e.g. `"General"`, `"#,##0"`). */
@@ -3724,6 +3749,14 @@ type PivotField = {
      * @default 10
      */
     itemPageCount?: integer;
+    /**
+     * Pivot area defining the sort key when `sortType` is `'ascending'` or
+     * `'descending'`. Specifies which data field's values to sort by (via a
+     * reference with `field: -2`), and may include additional references to
+     * constrain the scope. Absent when sorting is alphabetical (by the field's
+     * own labels).
+     */
+    autoSortScope?: PivotArea;
     /** Whether sorting is deferred to the data source. */
     dataSourceSort?: boolean;
     /**
@@ -3831,7 +3864,7 @@ type PivotFilter = {
     /** Auto-filter criteria that implement this pivot filter. */
     autoFilter?: {
         /** The reference range for the auto-filter. */
-        ref?: string;
+        ref?: CellRange;
         /** Filter columns with their criteria. */
         filterColumns?: PivotAutoFilterColumn[];
     };
@@ -4068,17 +4101,15 @@ type PivotTable = {
      */
     fields: PivotField[];
     /**
-     * Indices into {@link fields} identifying which fields appear on the row axis, in display order.
-     * Negative indices are special placeholders (e.g. `-2` represents the "Values" virtual field,
-     * used when there are multiple data fields) and do not index into {@link fields}.
+     * Fields on the row axis, in display order. Each entry is a {@link PivotFieldIndex}: either
+     * an index into {@link fields}, or `-2` for the "Values" virtual field.
      */
-    rowFieldIndices?: integer[];
+    rowFieldIndices?: PivotFieldIndex[];
     /**
-     * Indices into {@link fields} identifying which fields appear on the column axis, in display
-     * order. Negative indices are special placeholders (e.g. `-2` represents the "Values" virtual
-     * field) and do not index into {@link fields}.
+     * Fields on the column axis, in display order. Each entry is a {@link PivotFieldIndex}: either
+     * an index into {@link fields}, or `-2` for the "Values" virtual field.
      */
-    colFieldIndices?: integer[];
+    colFieldIndices?: PivotFieldIndex[];
     /** The data fields, defining the aggregated values displayed in the pivot table's data area. */
     dataFields?: PivotDataField[];
     /** The page (filter) fields, allowing the pivot table to be filtered by specific field values. */
@@ -4657,4 +4688,4 @@ type Workbook = {
     };
 };
 
-export type { AdjustCoordinate, AdjustPoint, AdjustValueHandlePolar, AdjustValueHandleXY, ArcToCommand, AutoColor, BlackWhiteMode, BlipFill, BorderStyle, CalcProps, Cell, CellId, CellOffset, CellRange, CellValueType, CloseCommand, Color, ColorTransform, Comment, ConnectionPoint, CubicBezierToCommand, DashStop, DataTable, DefinedName, DmlAngle, Drawing, EmuValue, Extent, External, ExternalDefinedName, ExternalWorksheet, Fill, FillPatternStyle, FlipAxis, FontStyleIndex, GeomGuideName, GradientColorStop, GradientLinearFill, GradientPathFill, Graphic, GraphicAnchor, GraphicAnchorAbsolute, GraphicAnchorOneCell, GraphicAnchorTwoCell, GraphicBitmap, GraphicChart, GraphicConnectionShape, GraphicGroup, GraphicShape, GridSize, GroupFill, GuidePoint, HAlign, HslColor, HyperlinkTextRun, IndexedColor, InsetRect, Line, LineAlignment, LineCapType, LineCompoundType, LineEnd, LineEndSize, LineEndType, LineJoinType, LineStyle, LineToCommand, MentionTextRun, MoveToCommand, NoFill, Note, Paragraph, Path, PathCommand, PathFillMode, PathFillType, PatternFill, PatternStyle, Percentage, Person, PivotArea, PivotAreaAxis, PivotAreaReference, PivotAreaType, PivotAutoFilterColumn, PivotCache, PivotCacheBase, PivotCacheConsolidation, PivotCacheConsolidationRangeSet, PivotCacheConsolidationSource, PivotCacheExternal, PivotCacheField, PivotCacheFieldGroup, PivotCacheRangePr, PivotCacheRecord, PivotCacheRecordValue, PivotCacheScenario, PivotCacheSharedItem, PivotCacheSharedItemBool, PivotCacheSharedItemDate, PivotCacheSharedItemErr, PivotCacheSharedItemNil, PivotCacheSharedItemNum, PivotCacheSharedItemStr, PivotCacheSharedItemsMeta, PivotCacheWorksheet, PivotCacheWorksheetSource, PivotCacheWorksheetSourceName, PivotCacheWorksheetSourceRange, PivotCalculatedField, PivotCustomFilterCriterion, PivotCustomFilterOperator, PivotDataField, PivotDataFieldAggregation, PivotField, PivotFieldAxis, PivotFieldItem, PivotFilter, PivotFilterType, PivotGroupBy, PivotItemType, PivotPageField, PivotRowColItem, PivotShowDataAs, PivotSubtotalFunction, PivotTable, PivotTableLocation, PivotTableStyle, PivotTableStyleName, PixelValue, Point, PositiveCoordinate, PresetColor, QuadraticBezierToCommand, RectAlignment, RelativeRect, ScRgbColor, SchemeColor, Shape, ShapeRect, ShapeStyle, SolidFill, SrgbColor, Style, SystemColor, Table, TableColumn, TableColumnDataType, TableStyle, TableStyleName, TextAnchoring, TextBody, TextHorzOverflow, TextRun, TextVertOverflow, TextVerticalType, TextWrapping, Theme, ThemeColorScheme, ThemeCustomColor, ThemeFontCollection, ThemeFontScheme, ThemeSupplementalFont, ThemeTextFont, ThreadedComment, Tile, Underline, VAlign, Workbook, WorkbookView, Worksheet, WorksheetDefaults, WorksheetLayoutScales, WorksheetView, Xfrm, XfrmGroup, integer };
+export type { AdjustCoordinate, AdjustPoint, AdjustValueHandlePolar, AdjustValueHandleXY, ArcToCommand, AutoColor, BlackWhiteMode, BlipFill, BorderStyle, CalcProps, Cell, CellId, CellOffset, CellRange, CellValueType, CloseCommand, Color, ColorTransform, Comment, ConnectionPoint, CubicBezierToCommand, DashStop, DataTable, DefinedName, DmlAngle, Drawing, EmuValue, Extent, External, ExternalDefinedName, ExternalWorksheet, Fill, FillPatternStyle, FlipAxis, FontStyleIndex, GeomGuideName, GradientColorStop, GradientLinearFill, GradientPathFill, Graphic, GraphicAnchor, GraphicAnchorAbsolute, GraphicAnchorOneCell, GraphicAnchorTwoCell, GraphicBitmap, GraphicChart, GraphicConnectionShape, GraphicGroup, GraphicShape, GridSize, GroupFill, GuidePoint, HAlign, HslColor, HyperlinkTextRun, IndexedColor, InsetRect, Line, LineAlignment, LineCapType, LineCompoundType, LineEnd, LineEndSize, LineEndType, LineJoinType, LineStyle, LineToCommand, MentionTextRun, MoveToCommand, NoFill, Note, Paragraph, Path, PathCommand, PathFillMode, PathFillType, PatternFill, PatternStyle, Percentage, Person, PivotArea, PivotAreaAxis, PivotAreaReference, PivotAreaType, PivotAutoFilterColumn, PivotCache, PivotCacheBase, PivotCacheConsolidation, PivotCacheConsolidationRangeSet, PivotCacheConsolidationSource, PivotCacheExternal, PivotCacheField, PivotCacheFieldGroup, PivotCacheRangePr, PivotCacheRecord, PivotCacheRecordValue, PivotCacheScenario, PivotCacheSharedItem, PivotCacheSharedItemBool, PivotCacheSharedItemDate, PivotCacheSharedItemErr, PivotCacheSharedItemNil, PivotCacheSharedItemNum, PivotCacheSharedItemStr, PivotCacheSharedItemsMeta, PivotCacheWorksheet, PivotCacheWorksheetSource, PivotCacheWorksheetSourceName, PivotCacheWorksheetSourceRange, PivotCalculatedField, PivotCustomFilterCriterion, PivotCustomFilterOperator, PivotDataField, PivotDataFieldAggregation, PivotField, PivotFieldAxis, PivotFieldIndex, PivotFieldItem, PivotFilter, PivotFilterType, PivotGroupBy, PivotItemType, PivotPageField, PivotRowColItem, PivotShowDataAs, PivotSubtotalFunction, PivotTable, PivotTableLocation, PivotTableStyle, PivotTableStyleName, PixelValue, Point, PositiveCoordinate, PresetColor, QuadraticBezierToCommand, RectAlignment, RelativeRect, ScRgbColor, SchemeColor, Shape, ShapeRect, ShapeStyle, SolidFill, SrgbColor, Style, SystemColor, Table, TableColumn, TableColumnDataType, TableStyle, TableStyleName, TextAnchoring, TextBody, TextHorzOverflow, TextRun, TextVertOverflow, TextVerticalType, TextWrapping, Theme, ThemeColorScheme, ThemeCustomColor, ThemeFontCollection, ThemeFontScheme, ThemeSupplementalFont, ThemeTextFont, ThreadedComment, Tile, Underline, VAlign, Workbook, WorkbookView, Worksheet, WorksheetDefaults, WorksheetLayoutScales, WorksheetView, Xfrm, XfrmGroup, integer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsfkit/types",
-  "version": "2.0.0-rc1",
+  "version": "2.0.0",
   "description": "TypeScript types for JSF: a JSON spreadsheet representation",
   "license": "MIT",
   "type": "module",