feat(compiler): add docs option to the config

Apply colors from the `docs.markdown.targetComponent` to
the my-component node in the mermaid diagram.

fixes: #2876

CONTRIBUTING.md

@@ -51,7 +51,7 @@ Please see our [Contributor Code of Conduct](https://github.com/ionic-team/stenc
    1. There's no need to install a specific version of npm or Node right now, it shall be done automatically for you in
       the next step
 5. Run `npm ci`
-6. Run `npm install.jest` to install dependencies for Stencil's testing submodule
+6. Run `npm run install.jest` to install dependencies for Stencil's testing submodule
 
 
 ### Updates

src/compiler/docs/readme/constants.ts

@@ -0,0 +1 @@
+export const DEFAULT_TARGET_COMPONENT_STYLES = { background: '#f9f', textColor: '#333' };

src/compiler/docs/readme/docs-util.ts

@@ -130,6 +130,23 @@ const normalizeColumnWidth = (rows: RowData[]) => {
   }
 };
 
+/**
+ * Checks if a given string is a valid hexadecimal color representation.
+ *
+ * @param str - The string to be checked.
+ * @returns `true` if the string is a valid hex color (e.g., '#FF00AA', '#f0f'), `false` otherwise.
+ *
+ * @example
+ * isHexColor('#FF00AA'); // true
+ * isHexColor('#f0f');    // true
+ * isHexColor('#abcde');  // false (too many characters)
+ * isHexColor('FF00AA');  // false (missing #)
+ */
+export const isHexColor = (str: string): boolean => {
+  const hexColorRegex = /^#([0-9A-Fa-f]{3}){1,2}$/;
+  return hexColorRegex.test(str);
+}
+
 interface ColumnData {
   text: string;
   width: number;

src/compiler/docs/readme/markdown-dependencies.ts

@@ -1,10 +1,18 @@
-import { normalizePath, relative } from '@utils';
+import { normalizePath, relative} from '@utils';
 
 import type * as d from '../../../declarations';
+import { DEFAULT_TARGET_COMPONENT_STYLES } from './constants';
+import { isHexColor } from "./docs-util";
 
-export const depsToMarkdown = (cmp: d.JsonDocsComponent, cmps: d.JsonDocsComponent[]) => {
+export const depsToMarkdown = (
+  cmp: d.JsonDocsComponent,
+  cmps: d.JsonDocsComponent[],
+  targetComponentConfig: d.StencilDocsConfig['markdown']['targetComponent'] = DEFAULT_TARGET_COMPONENT_STYLES,
+) => {
   const content: string[] = [];
+
   const deps = Object.entries(cmp.dependencyGraph);
+
   if (deps.length === 0) {
     return content;
   }
@@ -20,6 +28,7 @@ export const depsToMarkdown = (cmp: d.JsonDocsComponent, cmps: d.JsonDocsCompone
     content.push(...usedBy);
     content.push(``);
   }
+
   if (cmp.dependencies.length > 0) {
     const dependsOn = cmp.dependencies.map((tag) => '- ' + getCmpLink(cmp, tag, cmps));
 
@@ -29,6 +38,21 @@ export const depsToMarkdown = (cmp: d.JsonDocsComponent, cmps: d.JsonDocsCompone
     content.push(``);
   }
 
+  const { background: defaultBackground, textColor: defaultTextColor } = DEFAULT_TARGET_COMPONENT_STYLES;
+
+  let {
+    background = defaultBackground,
+    textColor = defaultTextColor,
+  } = targetComponentConfig;
+
+  if (!isHexColor(background)) {
+    background = defaultBackground;
+  }
+
+  if (!isHexColor(textColor)) {
+    textColor = defaultTextColor;
+  }
+
   content.push(`### Graph`);
   content.push('```mermaid');
   content.push('graph TD;');
@@ -38,7 +62,7 @@ export const depsToMarkdown = (cmp: d.JsonDocsComponent, cmps: d.JsonDocsCompone
     });
   });
 
-  content.push(`  style ${cmp.tag} fill:#f9f,stroke:#333,stroke-width:4px`);
+  content.push(`  style ${cmp.tag} fill:${background},stroke:${textColor},stroke-width:4px`);
 
   content.push('```');
 

src/compiler/docs/readme/output-docs.ts

@@ -54,7 +54,7 @@ export const generateReadme = async (
               await getUserReadmeContent(compilerCtx, readmeOutputPath)
             : userContent;
 
-        const readmeContent = generateMarkdown(currentReadmeContent, docsData, cmps, readmeOutput);
+        const readmeContent = generateMarkdown(currentReadmeContent, docsData, cmps, readmeOutput, config?.docs?.markdown);
 
         const results = await compilerCtx.fs.writeFile(readmeOutputPath, readmeContent);
         if (results.changedContent) {
@@ -74,9 +74,13 @@ export const generateMarkdown = (
   cmp: d.JsonDocsComponent,
   cmps: d.JsonDocsComponent[],
   readmeOutput: d.OutputTargetDocsReadme,
+  markdownConfig?: d.StencilDocsConfig['markdown'],
 ) => {
   //If the readmeOutput.dependencies is true or undefined the dependencies will be generated.
-  const dependencies = readmeOutput.dependencies !== false ? depsToMarkdown(cmp, cmps) : [];
+  const dependencies = readmeOutput.dependencies !== false
+    ? depsToMarkdown(cmp, cmps, markdownConfig?.targetComponent)
+    : [];
+
   return [
     userContent || '',
     AUTO_GENERATE_COMMENT,

src/compiler/docs/test/docs-util.spec.ts

@@ -1,4 +1,4 @@
-import { MarkdownTable } from '../../docs/readme/docs-util';
+import { isHexColor, MarkdownTable } from '../../docs/readme/docs-util';
 
 describe('markdown-table', () => {
   it('header', () => {
@@ -46,3 +46,28 @@ describe('markdown-table', () => {
     expect(o).toEqual([]);
   });
 });
+
+describe('isHexColor', () => {
+  it('should return true for valid hex colors', () => {
+    expect(isHexColor('#FFF')).toBe(true);
+    expect(isHexColor('#FFFFFF')).toBe(true);
+    expect(isHexColor('#000000')).toBe(true);
+    expect(isHexColor('#f0f0f0')).toBe(true);
+    expect(isHexColor('#aBcDeF')).toBe(true);
+  });
+
+  it('should return false for invalid hex colors', () => {
+    expect(isHexColor('FFF')).toBe(false);
+    expect(isHexColor('#GGGGGG')).toBe(false);
+    expect(isHexColor('#FF')).toBe(false);
+    expect(isHexColor('#FFFFFFF')).toBe(false);
+    expect(isHexColor('#FF0000FF')).toBe(false);
+  });
+
+  it('should return false for non-string inputs', () => {
+    expect(isHexColor('123')).toBe(false);
+    expect(isHexColor('true')).toBe(false);
+    expect(isHexColor('{}')).toBe(false);
+    expect(isHexColor('[]')).toBe(false);
+  });
+})

src/declarations/stencil-public-compiler.ts

@@ -272,6 +272,8 @@ export interface StencilConfig {
    */
   env?: { [prop: string]: string | undefined };
 
+  docs?: StencilDocsConfig;
+
   globalScript?: string;
   srcIndexHtml?: string;
   watch?: boolean;
@@ -1683,6 +1685,38 @@ export interface CopyTask {
   keepDirStructure?: boolean;
 }
 
+/**
+ * Configuration for generating documentation from Stencil components.
+ */
+export interface StencilDocsConfig {
+
+  /**
+   * Options for processing and rendering Markdown documentation files.
+   */
+  markdown: {
+
+    /**
+     * Styling for how the target component will be represented within documentation (e.g., in component diagrams).
+     */
+    targetComponent: {
+      /**
+       * Background color used for nodes representing the component in diagrams (e.g., Mermaid graphs).
+       * Use standard color names or hex codes.
+       * @example '#f0f0f0' (light gray)
+       */
+      background: string;
+
+      /**
+       * Text color used within nodes representing the component in diagrams (e.g., Mermaid graphs).
+       * Use standard color names or hex codes.
+       * @example '#333' (dark gray)
+       */
+      textColor: string;
+    };
+  };
+}
+
+
 // TODO(STENCIL-882): Remove this interface [BREAKING_CHANGE]
 export interface BundlingConfig {
   /**