Breaking change syncing TypeScript declarations with their implementations

BREAKING_CHANGES.md

@@ -1,3 +1,10 @@
+## From 36.x to 37
+
+- **TypeScript declaration coverage and accuracy have been improved.** Runtime behavior is unchanged, but builds that compiled against the old declarations may fail. Modules that shipped no types resolved to `any`, and local `declare module '@kitware/vtk.js/...'` shims now collide with the real ones: delete the shims and fix what the types reject.
+- **Accessors**: `setXFrom` and hand-written setters that only `return;` are `void`, not `boolean`. Accessors that can read back `null` or `undefined` now say so, and fields absent from `DEFAULT_VALUES` are `T | undefined` rather than `Nullable<T>`.
+- **vtkPolygon**: `PolygonIntersectionState`'s members were each off by one against the runtime constant — `FAILURE` is `-1`, not `0` — so comparisons against `pointInPolygon`'s result were silently wrong. It is now an alias of `PolygonWithPointIntersectionState` and cannot be used in value position.
+
+
 ## From 35.x to 36
 
 - **`vtk-lite.js` deprecated.** The UMD build previously produced a slimmed-down companion bundle `dist/umd/vtk-lite.js` (curated ColorMaps subset; `PDBReader`, `MoleculeToRepresentation`, `MobileVR`, and `webvr-polyfill` stubbed out). The Vite build pipeline no longer produces a distinct lite bundle; `vtk-lite.js` now ships as a byte-identical alias of `vtk.js` so existing `<script src=…/vtk-lite.js>` and CDN consumers continue to load. Consumers should migrate to `vtk.js` directly — the alias will be removed in a future major. Note that anything that indexed into the `ColorMaps` array by position will now see the full preset set, not the lite subset.

Sources/Common/Core/CellArray/index.d.ts

@@ -23,7 +23,7 @@ export interface vtkCellArray extends vtkDataArray {
    * Get the sizes of the cells in this array.
    * @param {Boolean} [recompute] Recompute the cell sizes.
    */
-  getCellSizes(recompute?: boolean): any;
+  getCellSizes(recompute?: boolean): number[];
 
   /**
    * Set the data of this array.
@@ -35,7 +35,7 @@ export interface vtkCellArray extends vtkDataArray {
    * Returns the point indices at the given location as a subarray.
    * @param loc
    */
-  getCell(loc: any): void;
+  getCell(loc: number): TypedArray;
 
   /**
    * Insert a cell to this array in the next available slot.
@@ -82,13 +82,18 @@ export function newInstance(
  * @param cellArray
  * @returns {number[]} An array of cell sizes.
  */
-export function extractCellSizes(cellArray: any): number[];
+declare function extractCellSizes(cellArray: any): number[];
 
 /**
  * @static
  * @param cellArray
  */
-export function getNumberOfCells(cellArray: any): any;
+declare function getNumberOfCells(cellArray: any): any;
+
+export declare const STATIC: Readonly<{
+  extractCellSizes: typeof extractCellSizes;
+  getNumberOfCells: typeof getNumberOfCells;
+}>;
 
 /**
  * vtkCellArray stores dataset topologies as an explicit connectivity table

Sources/Common/Core/ClassHierarchy/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * An array of class names that ignores duplicates: pushing a name already in
+ * the hierarchy leaves the array unchanged and still reports its length.
+ */
+export interface ClassHierarchy extends Array<string> {
+  push(...names: string[]): number;
+}
+
+/**
+ * The subclass carries no static members of its own; it inherits Array's.
+ */
+declare const ClassHierarchy: {
+  new (...items: string[]): ClassHierarchy;
+};
+export default ClassHierarchy;

Sources/Common/Core/DataArray/Constants.d.ts

@@ -0,0 +1,42 @@
+export declare const DataTypeByteSize: {
+  Int8Array: number;
+  Uint8Array: number;
+  Uint8ClampedArray: number;
+  Int16Array: number;
+  Uint16Array: number;
+  Int32Array: number;
+  Uint32Array: number;
+  Float32Array: number;
+  Float64Array: number;
+};
+
+/**
+ * Constants capturing the various VTK data types.
+ */
+export declare const VtkDataTypes: {
+  readonly VOID: '';
+  readonly CHAR: 'Int8Array';
+  readonly SIGNED_CHAR: 'Int8Array';
+  readonly UNSIGNED_CHAR: 'Uint8Array';
+  /**
+   * Should be used for VTK.js internal purpose only
+   */
+  readonly UNSIGNED_CHAR_CLAMPED: 'Uint8ClampedArray';
+  readonly SHORT: 'Int16Array';
+  readonly UNSIGNED_SHORT: 'Uint16Array';
+  readonly INT: 'Int32Array';
+  readonly UNSIGNED_INT: 'Uint32Array';
+  readonly FLOAT: 'Float32Array';
+  readonly DOUBLE: 'Float64Array';
+};
+
+export type VtkDataTypes = (typeof VtkDataTypes)[keyof typeof VtkDataTypes];
+
+export declare const DefaultDataType: VtkDataTypes;
+
+declare const _default: {
+  DefaultDataType: typeof DefaultDataType;
+  DataTypeByteSize: typeof DataTypeByteSize;
+  VtkDataTypes: typeof VtkDataTypes;
+};
+export default _default;

Sources/Common/Core/DataArray/index.d.ts

@@ -1,3 +1,4 @@
+import { DataTypeByteSize, VtkDataTypes } from './Constants';
 import { vtkObject, vtkRange, GetStateOptions } from '../../../interfaces';
 import { float, int, Nullable, Range, TypedArray } from '../../../types';
 
@@ -55,6 +56,12 @@ export interface vtkDataArray extends vtkObject {
    */
   setComponent(tupleIdx: number, componentIndex: number, value: number): void;
 
+  /** Get a value by its flat component index. */
+  getValue(valueIdx: number): number;
+
+  /** Set a value by its flat component index. */
+  setValue(valueIdx: number, value: number): void;
+
   /**
    *
    */
@@ -98,7 +105,7 @@ export interface vtkDataArray extends vtkObject {
    * @param {boolean} [computeRanges] (default: true)
    * @returns {vtkRange[]}
    */
-  getRanges(computeRanges: boolean): vtkRange[];
+  getRanges(computeRanges?: boolean): vtkRange[];
 
   /**
    * Set the given tuple at the given index.
@@ -279,7 +286,7 @@ export interface vtkDataArray extends vtkObject {
    * without converting and copying to a plain Array.
    * @returns {object}
    */
-  getState(options?: GetStateOptions): object;
+  getState(options?: GetStateOptions): object | null;
 
   /**
    * Deep copy of another vtkDataArray into this one.
@@ -306,7 +313,7 @@ export interface vtkDataArray extends vtkObject {
     source2: vtkDataArray,
     source2Idx: int,
     t: float
-  ): void;
+  ): number;
 
   /**
    * Resize the array to the requested number of extra tuples
@@ -345,7 +352,7 @@ export interface vtkDataArray extends vtkObject {
    * @see insertNextTuple
    * @see insertNextTuples
    */
-  initialize(): void;
+  initialize(): vtkDataArray;
 
   // --- via macro --
 
@@ -381,7 +388,7 @@ export interface vtkDataArray extends vtkObject {
  * @param {Number} [component] (default: 0) indice to use inside tuple size
  * @param {Number} [numberOfComponents] (default: 1) size of the tuple
  */
-export function computeRange(
+declare function computeRange(
   values: ArrayLike<number>,
   component?: number,
   numberOfComponents?: number
@@ -394,7 +401,7 @@ export function computeRange(
  * @param {Number} offset offset index to select the desired component in the tuple
  * @param {Number} numberOfComponents size of tuple in a multi-channel array
  */
-export function fastComputeRange(
+declare function fastComputeRange(
   values: ArrayLike<number>,
   offset: number,
   numberOfComponents: number
@@ -405,7 +412,7 @@ export function fastComputeRange(
  * Create helper object that can be used to gather min, max, count, sum of
  * a set of values.
  */
-export function createRangeHelper(): vtkRangeHelper;
+declare function createRangeHelper(): vtkRangeHelper;
 
 /**
  * Return the name of a typed array
@@ -417,14 +424,22 @@ export function createRangeHelper(): vtkRangeHelper;
  *
  * @param typedArray to extract its type from
  */
-export function getDataType(typedArray: TypedArray): string;
+declare function getDataType(typedArray: TypedArray): string;
 
 /**
  * Return the max norm of a given vtkDataArray
  *
  * @param dataArray to process
  */
-export function getMaxNorm(dataArray: vtkDataArray): number;
+declare function getMaxNorm(dataArray: vtkDataArray): number;
+
+export declare const STATIC: Readonly<{
+  computeRange: typeof computeRange;
+  createRangeHelper: typeof createRangeHelper;
+  fastComputeRange: typeof fastComputeRange;
+  getDataType: typeof getDataType;
+  getMaxNorm: typeof getMaxNorm;
+}>;
 
 /**
  * Method use to decorate a given object (publicAPI+model) with vtkDataArray characteristics.
@@ -451,37 +466,6 @@ export function extend(
  */
 export function newInstance(initialValues?: object): vtkDataArray;
 
-/**
- * Constants capturing the number of bytes per element based on its data type.
- */
-export enum DataTypeByteSize {
-  Int8Array,
-  Uint8Array,
-  Uint8ClampedArray,
-  Int16Array,
-  Uint16Array,
-  Int32Array,
-  Uint32Array,
-  Float32Array,
-  Float64Array,
-}
-
-/**
- * Constants capturing the various VTK data types.
- */
-export enum VtkDataTypes {
-  VOID,
-  CHAR,
-  SIGNED_CHAR,
-  UNSIGNED_CHAR,
-  SHORT,
-  UNSIGNED_SHORT,
-  INT,
-  UNSIGNED_INT,
-  FLOAT,
-  DOUBLE,
-}
-
 /**
  * vtkDataArray is an abstract superclass for data array objects containing
  * numeric data.

Sources/Common/Core/Endian/index.d.ts

@@ -5,11 +5,18 @@ import { Nullable } from '../../../types';
  */
 export function getEndianness(): Nullable<string>;
 
-export const ENDIANNESS: string;
+export const ENDIANNESS: Nullable<string>;
 
 /**
  *
  * @param {ArrayBuffer} buffer
  * @param {Number} wordSize
  */
 export function swapBytes(buffer: ArrayBuffer, wordSize: number): void;
+
+declare const _default: {
+  ENDIANNESS: Nullable<string>;
+  getEndianness: typeof getEndianness;
+  swapBytes: typeof swapBytes;
+};
+export default _default;

Sources/Common/Core/HalfFloat/index.d.ts

@@ -7,16 +7,16 @@
  * @param {number} input
  * @return encoded half float number (16 bits)
  */
-export function toHalf(input: number): number;
+declare function toHalf(input: number): number;
 
 /**
  * Convert a half float representation to a number
  * @param {number} input
  * @return decoded half float number
  */
-export function fromHalf(input: number): number;
+declare function fromHalf(input: number): number;
 
-export declare const HalfFloat: {
+declare const HalfFloat: {
   toHalf: typeof toHalf;
   fromHalf: typeof fromHalf;
 };

Sources/Common/Core/ImageHelper/index.d.ts

@@ -14,7 +14,7 @@ interface ITransform {
  * @param {HTMLCanvasElement} canvas The HTML canvas to convert.
  * @param {Number[]} [boundingBox] A bounding box array.
  */
-export function canvasToImageData(
+declare function canvasToImageData(
   canvas: HTMLCanvasElement,
   boundingBox?: number[]
 ): vtkImageData;
@@ -24,7 +24,13 @@ export function canvasToImageData(
  * @param {HTMLImageElement} image The HTML image to convert.
  * @param {ITransform} [transform] The transform object to apply to the image.
  */
-export function imageToImageData(
+declare function imageToImageData(
   image: HTMLImageElement,
   transform?: ITransform
 ): vtkImageData;
+
+declare const _default: {
+  canvasToImageData: typeof canvasToImageData;
+  imageToImageData: typeof imageToImageData;
+};
+export default _default;