chore!: prefer interfaces over types for public type definitions

.eslintrc.cjs

@@ -107,8 +107,6 @@ module.exports = {
           },
         ],
         '@typescript-eslint/consistent-type-imports': ['error'],
-        // We choose to disable it and choose later if we want to enable it. See https://github.com/process-analytics/bpmn-visualization-js/pull/2821.
-        '@typescript-eslint/consistent-type-definitions': 'off',
         '@typescript-eslint/dot-notation': 'error',
 
         'require-await': 'off', // disable the base eslint rule as it can report incorrect errors when '@typescript-eslint/require-await' is enabled (see official documentation)

src/bpmn-visualization.ts

@@ -27,6 +27,8 @@ export * from './component/registry';
 export * from './component/version';
 export type { Navigation } from './component/navigation';
 export * from './model/bpmn/internal';
+export type { BpmnGraph } from './component/mxgraph/BpmnGraph';
+export type * from './component/types';
 
 // not part of the public API but needed for the custom theme examples
 export { StyleConfigurator } from './component/mxgraph/config/StyleConfigurator';

src/component/mxgraph/BpmnGraph.ts

@@ -95,8 +95,7 @@ export class BpmnGraph extends mxGraph {
    *
    * @param callbackFunction the update to be made in the transaction.
    *
-   * @experimental subject to change, may move to a subclass of {@link mxGraphModel}
-   * @alpha
+   * @experimental subject to change, may move to a subclass of `mxGraphModel`
    */
   batchUpdate(callbackFunction: () => void): void {
     this.model.beginUpdate();

src/component/mxgraph/shape/render/icon-painter.ts

@@ -97,15 +97,12 @@ export class IconPainter {
   /**
    * Utility paint icon methods to easily instantiate a {@link BpmnCanvas} from a {@link PaintParameter}.
    *
-   * @param canvas                  `mxAbstractCanvas2D` in charge of performing the paint operations.
-   * @param ratioFromParent         the actual size of the icon will be computed from the shape dimensions using this ratio.
-   * @param setIconOriginFunct      called function to set the origin of the icon. Generally, it calls a method of {@link BpmnCanvas}.
-   * @param shapeConfig             dimension and style of the shape where the icon is painted.
-   * @param iconStyleConfig         style of the icon.
-   * @param originalIconSize        original size of the icon used to compute the scaling/ratio in {@link BpmnCanvas}.
+   * @param paintParameter   aggregates the canvas, the shape/icon configuration and the rendering helpers used to paint the icon. See {@link PaintParameter}.
+   * @param originalIconSize original size of the icon used to compute the scaling/ratio in {@link BpmnCanvas}.
    * @protected
    */
-  protected newBpmnCanvas({ canvas, ratioFromParent, setIconOriginFunct, shapeConfig, iconStyleConfig }: PaintParameter, originalIconSize: Size): BpmnCanvas {
+  protected newBpmnCanvas(paintParameter: PaintParameter, originalIconSize: Size): BpmnCanvas {
+    const { canvas, ratioFromParent, setIconOriginFunct, shapeConfig, iconStyleConfig } = paintParameter;
     return new BpmnCanvas({
       canvas,
       shapeConfig,

src/component/options.ts

@@ -168,7 +168,7 @@ export enum ZoomType {
  * Configure the BPMN parser.
  * @category Initialization & Configuration
  */
-export type ParserOptions = {
+export interface ParserOptions {
   /**
    * Apply additional processing to the XML attributes in the BPMN source.
    *
@@ -182,23 +182,23 @@ export type ParserOptions = {
    *   }
    * }
    * ```
-   * @param val the value of the 'name' attribute to be processed.
+   * @param value the value of the 'name' attribute to be processed.
    */
   additionalXmlAttributeProcessor?: (value: string) => string;
   /**
    * If `true`, disable the console logs produced by the parser.
    * @default false
    */
   disableConsoleLog?: boolean;
-};
+}
 
 /**
  * Global configuration for the rendering of the BPMN elements.
  *
  * @category Initialization & Configuration
  * @since 0.35.0
  */
-export type RendererOptions = {
+export interface RendererOptions {
   /**
    * Custom {@link IconPainter} instance to use for rendering BPMN element icons.
    * This allows you to customize how icons are rendered on tasks, events, and other BPMN elements.
@@ -264,4 +264,4 @@ export type RendererOptions = {
    * @since 0.48.0
    */
   ignoreTaskLabelBounds?: boolean;
-};
+}

src/component/parser/xml/BpmnXmlParser.ts

@@ -19,10 +19,10 @@ import type { ParserOptions } from '../../options';
 
 import { XMLParser, type X2jOptions } from 'fast-xml-parser';
 
-type Replacement = {
+interface Replacement {
   regex: RegExp;
   val: string;
-};
+}
 const entitiesReplacements: Replacement[] = [
   { regex: /&(amp|#38|#x26);/g, val: '&' },
   { regex: /&(apos|#39|#x27);/g, val: "'" },

src/component/registry/types.ts

@@ -431,27 +431,27 @@ export type OverlayPosition = OverlayShapePosition | OverlayEdgePosition;
 /**
  * @category Overlays
  */
-export type OverlayStyle = {
+export interface OverlayStyle {
   font?: OverlayFont;
   fill?: OverlayFill;
   stroke?: OverlayStroke;
-};
+}
 
 /**
  * The font family is {@link StyleDefault.DEFAULT_FONT_FAMILY}.
  * @category Overlays
  */
-export type OverlayFont = {
+export interface OverlayFont {
   /** @default {@link StyleDefault.DEFAULT_OVERLAY_FONT_COLOR} */
   color?: string;
   /** @default {@link StyleDefault.DEFAULT_OVERLAY_FONT_SIZE} */
   size?: number;
-};
+}
 
 /**
  * @category Overlays
  */
-export type OverlayFill = {
+export interface OverlayFill {
   /** @default {@link StyleDefault.DEFAULT_OVERLAY_FILL_COLOR} */
   color?: string;
   /**
@@ -463,12 +463,12 @@ export type OverlayFill = {
    * @default {@link StyleDefault.DEFAULT_OVERLAY_FILL_OPACITY}
    */
   opacity?: number;
-};
+}
 
 /**
  * @category Overlays
  */
-export type OverlayStroke = {
+export interface OverlayStroke {
   /**
    * If you don't want to display a stroke, you can set the color to
    *   * `transparent`
@@ -482,16 +482,16 @@ export type OverlayStroke = {
    * @default {@link StyleDefault.DEFAULT_OVERLAY_STROKE_WIDTH}
    */
   width?: number;
-};
+}
 
 /**
  * @category Overlays
  */
-export type Overlay = {
+export interface Overlay {
   position: OverlayPosition;
   label?: string;
   style?: OverlayStyle;
-};
+}
 
 /**
  * @category Element Style
@@ -501,7 +501,7 @@ export type StyleUpdate = EdgeStyleUpdate | ShapeStyleUpdate;
 /**
  * @category Element Style
  */
-export type EdgeStyleUpdate = {
+export interface EdgeStyleUpdate {
   font?: Font;
   /**
    * The value must be between 0 and 100:
@@ -516,7 +516,7 @@ export type EdgeStyleUpdate = {
    */
   opacity?: Opacity;
   stroke?: Stroke;
-};
+}
 
 /**
  * @category Element Style
@@ -636,7 +636,7 @@ export type Fill = StyleWithOpacity & {
  *
  * @category Element Style
  */
-export type FillColorGradient = {
+export interface FillColorGradient {
   /**
    * It can be any HTML color name or HEX code, as well as special keywords such as:
    * - `inherit` to apply the fill color of the direct parent element.
@@ -661,7 +661,7 @@ export type FillColorGradient = {
    * @see {@link GradientDirection}
    */
   direction: GradientDirection;
-};
+}
 
 /**
  * @category Element Style
@@ -671,7 +671,7 @@ export type GradientDirection = 'left-to-right' | 'right-to-left' | 'bottom-to-t
 /**
  * @category Element Style
  */
-export type StyleWithOpacity = {
+export interface StyleWithOpacity {
   /**
    * The value must be between 0 and 100:
    * - If the set value is less than 0, the used value is 0.
@@ -682,7 +682,7 @@ export type StyleWithOpacity = {
    * - It can be used when the style is first updated and then needs to be reset to its initial value.
    */
   opacity?: Opacity;
-};
+}
 
 /**
  *  @category Element Style

src/model/bpmn/internal/types.ts

@@ -17,21 +17,21 @@ limitations under the License.
 /**
  * @internal
  */
-export type ShapeExtensions = {
+export interface ShapeExtensions {
   fillColor?: string;
   strokeColor?: string;
-};
+}
 
 /**
  * @internal
  */
-export type EdgeExtensions = {
+export interface EdgeExtensions {
   strokeColor?: string;
-};
+}
 
 /**
  * @internal
  */
-export type LabelExtensions = {
+export interface LabelExtensions {
   color?: string;
-};
+}

test/config/jest.image.ts

@@ -108,11 +108,11 @@ async function attachImagesForReport(images: LocationOfImagesForTestReport, matc
   }
 }
 
-type LocationOfImagesForTestReport = {
+interface LocationOfImagesForTestReport {
   diff: string;
   expected: string;
   received: string;
-};
+}
 
 function saveImages(options: MatchImageSnapshotOptions): LocationOfImagesForTestReport {
   const snapshotIdentifier = options.customSnapshotIdentifier as string;

test/integration/helpers/model-expect.ts

@@ -137,12 +137,12 @@ expect.extend({
   toBeTextAnnotation,
 });
 
-export type ExpectedCellWithGeometry = {
+export interface ExpectedCellWithGeometry {
   parentId?: string;
   geometry: mxGeometry;
-};
+}
 
-export type ExpectedFont = {
+export interface ExpectedFont {
   color?: string;
   family?: string;
   size?: number;
@@ -151,12 +151,12 @@ export type ExpectedFont = {
   isUnderline?: boolean;
   isStrikeThrough?: boolean;
   opacity?: Opacity;
-};
+}
 
 export type HorizontalAlign = 'center' | 'left' | 'right';
 export type VerticalAlign = 'bottom' | 'middle' | 'top';
 
-type ExpectedModelElement = {
+interface ExpectedModelElement {
   align?: HorizontalAlign;
   font?: ExpectedFont;
   label?: string;
@@ -167,19 +167,19 @@ type ExpectedModelElement = {
   opacity?: number;
   // custom bpmn-visualization
   extraCssClasses?: string[];
-};
+}
 
-export type ExpectedFill = {
+export interface ExpectedFill {
   color?: string;
   opacity?: Opacity;
-};
+}
 
 export type ExpectedDirection = 'west' | 'east' | 'north' | 'south';
 
-export type ExpectedGradient = {
+export interface ExpectedGradient {
   color: string;
   direction?: ExpectedDirection;
-};
+}
 
 export type ExpectedShapeModelElement = {
   kind?: ShapeBpmnElementKind;

test/typescript-support/src/index.ts

@@ -14,8 +14,18 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// eslint-disable-next-line import/no-unresolved -- The bpmn-visualization package may not have been built prior running eslint (it happens when running GitHub Actions)
+// eslint-disable-next-line import/no-unresolved -- The bpmn-visualization package may not have been built before running eslint (it happens when running GitHub Actions)
+import type { BpmnGraph } from 'bpmn-visualization';
+import type { mxStylesheet } from 'mxgraph';
+
+// eslint-disable-next-line import/no-unresolved -- The bpmn-visualization package may not have been built before running eslint (it happens when running GitHub Actions)
 import { BpmnVisualization } from 'bpmn-visualization';
 
 const bpmnVisualization = new BpmnVisualization({ container: 'bpmn-container' });
 bpmnVisualization.load(`fake BPMN content`);
+
+// Validate the access to the BpmnGraph type and some mxGraph derived methods and properties
+const graph: BpmnGraph = bpmnVisualization.graph;
+graph.view.revalidate();
+const stylesheet: mxStylesheet = graph.getStylesheet();
+stylesheet.putCellStyle('customStyle', { fillColor: '#FF0000' });