chore: Add deprecation notices, improve types

Co-authored-by: Alois Klink <alois@aloisklink.com>

docs/config/setup/modules/mermaidAPI.md

@@ -31,7 +31,7 @@ Renames and re-exports [mermaidAPI](mermaidAPI.md#mermaidapi)
 
 ### mermaidAPI
 
-• `Const` **mermaidAPI**: `Readonly`<{ `defaultConfig`: `MermaidConfig` = configApi.defaultConfig; `getConfig`: () => `MermaidConfig` = configApi.getConfig; `getDiagramFromText`: (`text`: `string`, `metadata`: { `title?`: `string` }) => `Promise`<`Diagram`> ; `getSiteConfig`: () => `MermaidConfig` = configApi.getSiteConfig; `globalReset`: () => `void` ; `initialize`: (`options`: `MermaidConfig`) => `void` ; `parse`: (`text`: `string`, `parseOptions?`: [`ParseOptions`](../interfaces/mermaidAPI.ParseOptions.md)) => `Promise`<`boolean`> ; `render`: (`id`: `string`, `text`: `string`, `svgContainingElement?`: `Element`) => `Promise`<[`RenderResult`](../interfaces/mermaidAPI.RenderResult.md)> ; `reset`: () => `void` ; `setConfig`: (`conf`: `MermaidConfig`) => `MermaidConfig` = configApi.setConfig; `updateSiteConfig`: (`conf`: `MermaidConfig`) => `MermaidConfig` = configApi.updateSiteConfig }>
+• `Const` **mermaidAPI**: `Readonly`<{ `defaultConfig`: `MermaidConfig` = configApi.defaultConfig; `getConfig`: () => `MermaidConfig` = configApi.getConfig; `getDiagramFromText`: (`text`: `string`, `metadata`: `Pick`<`DiagramMetadata`, `"title"`>) => `Promise`<`Diagram`> ; `getSiteConfig`: () => `MermaidConfig` = configApi.getSiteConfig; `globalReset`: () => `void` ; `initialize`: (`options`: `MermaidConfig`) => `void` ; `parse`: (`text`: `string`, `parseOptions?`: [`ParseOptions`](../interfaces/mermaidAPI.ParseOptions.md)) => `Promise`<`boolean`> ; `render`: (`id`: `string`, `text`: `string`, `svgContainingElement?`: `Element`) => `Promise`<[`RenderResult`](../interfaces/mermaidAPI.RenderResult.md)> ; `reset`: () => `void` ; `setConfig`: (`conf`: `MermaidConfig`) => `MermaidConfig` = configApi.setConfig; `updateSiteConfig`: (`conf`: `MermaidConfig`) => `MermaidConfig` = configApi.updateSiteConfig }>
 
 ## mermaidAPI configuration defaults
 

packages/mermaid/src/Diagram.ts

@@ -4,7 +4,7 @@ import { getDiagram, registerDiagram } from './diagram-api/diagramAPI.js';
 import { detectType, getDiagramLoader } from './diagram-api/detectType.js';
 import { UnknownDiagramError } from './errors.js';
 import type { DetailedError } from './utils.js';
-import type { DiagramDefinition } from './diagram-api/types.js';
+import type { DiagramDefinition, DiagramMetadata } from './diagram-api/types.js';
 
 export type ParseErrorFunction = (err: string | DetailedError | unknown, hash?: any) => void;
 
@@ -20,7 +20,7 @@ export class Diagram {
   private init?: DiagramDefinition['init'];
 
   private detectError?: UnknownDiagramError;
-  constructor(public text: string, public metadata: { title?: string } = {}) {
+  constructor(public text: string, public metadata: Pick<DiagramMetadata, 'title'> = {}) {
     this.text += '\n';
     const cnf = configApi.getConfig();
     try {
@@ -72,13 +72,14 @@ export class Diagram {
  * **Warning:** This function may be changed in the future.
  * @alpha
  * @param text - The mermaid diagram definition.
+ * @param metadata - Diagram metadata, defined in YAML.
  * @returns A the Promise of a Diagram object.
  * @throws {@link UnknownDiagramError} if the diagram type can not be found.
  * @privateRemarks This is exported as part of the public mermaidAPI.
  */
 export const getDiagramFromText = async (
   text: string,
-  metadata: { title?: string } = {}
+  metadata: Pick<DiagramMetadata, 'title'> = {}
 ): Promise<Diagram> => {
   const type = detectType(text, configApi.getConfig());
   try {

packages/mermaid/src/diagram-api/diagramAPI.ts

@@ -57,7 +57,8 @@ export const registerDiagram = (
     setupGraphViewbox,
     getCommonDb(),
     () => {
-      // parseDirective is removed. This is a no-op for legacy support.
+      // parseDirective is removed in https://github.com/mermaid-js/mermaid/pull/4759.
+      // This is a no-op for legacy support.
     }
   );
 };

packages/mermaid/src/diagram-api/types.ts

@@ -3,6 +3,11 @@ import type { Diagram } from '../Diagram.js';
 import type { BaseDiagramConfig, MermaidConfig } from '../config.type.js';
 import type * as d3 from 'd3';
 
+export interface DiagramMetadata {
+  title?: string;
+  config?: MermaidConfig;
+}
+
 export interface InjectUtils {
   _log: any;
   _setLogLevel: any;
@@ -10,6 +15,7 @@ export interface InjectUtils {
   _sanitizeText: any;
   _setupGraphViewbox: any;
   _commonDb: any;
+  /** @deprecated as directives will be pre-processed since https://github.com/mermaid-js/mermaid/pull/4759 */
   _parseDirective: any;
 }
 
@@ -46,6 +52,7 @@ export interface DiagramDefinition {
     _sanitizeText: InjectUtils['_sanitizeText'],
     _setupGraphViewbox: InjectUtils['_setupGraphViewbox'],
     _commonDb: InjectUtils['_commonDb'],
+    /** @deprecated as directives will be pre-processed since https://github.com/mermaid-js/mermaid/pull/4759 */
     _parseDirective: InjectUtils['_parseDirective']
   ) => void;
 }

packages/mermaid/src/mermaidAPI.ts

@@ -99,7 +99,7 @@ export interface RenderResult {
 function processAndSetConfigs(text: string) {
   const processed = preprocessDiagram(text);
   configApi.reset();
-  configApi.addDirective(processed.config);
+  configApi.addDirective(processed.config ?? {});
   return processed;
 }
 

packages/mermaid/src/preprocess.ts

@@ -1,5 +1,6 @@
 import { cleanupComments } from './diagram-api/comments.js';
 import { extractFrontMatter } from './diagram-api/frontmatter.js';
+import type { DiagramMetadata } from './diagram-api/types.js';
 import utils, { cleanAndMerge, removeDirectives } from './utils.js';
 
 const cleanupText = (code: string) => {
@@ -44,7 +45,13 @@ const processDirectives = (code: string) => {
   };
 };
 
-export const preprocessDiagram = (code: string) => {
+/**
+ * Preprocess the given code by cleaning it up, extracting front matter and directives,
+ * cleaning and merging configuration, and removing comments.
+ * @param code - The code to preprocess.
+ * @returns The object containing the preprocessed code, title, and configuration.
+ */
+export function preprocessDiagram(code: string): DiagramMetadata & { code: string } {
   const cleanedCode = cleanupText(code);
   const frontMatterResult = processFrontmatter(cleanedCode);
   const directiveResult = processDirectives(frontMatterResult.text);
@@ -55,4 +62,4 @@ export const preprocessDiagram = (code: string) => {
     title: frontMatterResult.title,
     config,
   };
-};
+}