| 6dd74de | | | 1 | > **Warning** |
| 6dd74de | | | 2 | > |
| 6dd74de | | | 3 | > ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. |
| 6dd74de | | | 4 | > |
| 6dd74de | | | 5 | > ## Please edit the corresponding file in [/packages/mermaid/src/docs/adding-new-shape.md](../packages/mermaid/src/docs/adding-new-shape.md). |
| 6dd74de | | | 6 | |
| 6dd74de | | | 7 | # Custom SVG Shapes Library |
| 6dd74de | | | 8 | |
| 6dd74de | | | 9 | This library provides a collection of custom SVG shapes, utilities, and helpers for generating diagram components. The shapes are designed to be used within an SVG container and include a variety of common and complex shapes. |
| 6dd74de | | | 10 | |
| 6dd74de | | | 11 | ## Overview |
| 6dd74de | | | 12 | |
| 6dd74de | | | 13 | ## Shape Helpers and Utilities |
| 6dd74de | | | 14 | |
| 6dd74de | | | 15 | Before starting with shape creation, it's essential to familiarize yourself with the utilities provided in the `utils.ts` file from `packages/mermaid/src/rendering-util/rendering-elements/shapes/util.js`. These utilities are designed to assist with various aspects of SVG shape manipulation and ensure consistent and accurate rendering. |
| 6dd74de | | | 16 | |
| 6dd74de | | | 17 | ## Available Utilities |
| 6dd74de | | | 18 | |
| 6dd74de | | | 19 | ### 1. `labelHelper` |
| 6dd74de | | | 20 | |
| 6dd74de | | | 21 | - **Purpose**: This function creates and inserts labels inside SVG shapes. |
| 6dd74de | | | 22 | - **Features**: |
| 6dd74de | | | 23 | - Handles both HTML labels and plain text. |
| 6dd74de | | | 24 | - Calculates the bounding box dimensions of the label. |
| 6dd74de | | | 25 | - Ensures proper positioning of labels within shapes. |
| 6dd74de | | | 26 | |
| 6dd74de | | | 27 | ### 2. `updateNodeBounds` |
| 6dd74de | | | 28 | |
| 6dd74de | | | 29 | - **Purpose**: Updates the bounding box dimensions (width and height) of a node. |
| 6dd74de | | | 30 | - **Usage**: |
| 6dd74de | | | 31 | - Adjusts the size of the node to fit the content or shape. |
| 6dd74de | | | 32 | - Useful for ensuring that shapes resize appropriately based on their content. |
| 6dd74de | | | 33 | |
| 6dd74de | | | 34 | ### 3. `insertPolygonShape` |
| 6dd74de | | | 35 | |
| 6dd74de | | | 36 | - **Purpose**: Inserts a polygon shape into an SVG container. |
| 6dd74de | | | 37 | - **Features**: |
| 6dd74de | | | 38 | - Handles the creation and insertion of complex polygonal shapes. |
| 6dd74de | | | 39 | - Configures the shape's appearance and positioning within the SVG container. |
| 6dd74de | | | 40 | |
| 6dd74de | | | 41 | ### 4. `getNodeClasses` |
| 6dd74de | | | 42 | |
| 6dd74de | | | 43 | - **Purpose**: Returns the appropriate CSS classes for a node based on its configuration. |
| 6dd74de | | | 44 | - **Usage**: |
| 6dd74de | | | 45 | - Dynamically applies CSS classes to nodes for styling purposes. |
| 6dd74de | | | 46 | - Ensures that nodes adhere to the desired design and theme. |
| 6dd74de | | | 47 | |
| 6dd74de | | | 48 | ### 5. `createPathFromPoints` |
| 6dd74de | | | 49 | |
| 6dd74de | | | 50 | - **Purpose**: Generates an SVG path string from an array of points. |
| 6dd74de | | | 51 | - **Usage**: |
| 6dd74de | | | 52 | - Converts a list of points into a smooth path. |
| 6dd74de | | | 53 | - Useful for creating custom shapes or paths within the SVG. |
| 6dd74de | | | 54 | |
| 6dd74de | | | 55 | ### 6. `generateFullSineWavePoints` |
| 6dd74de | | | 56 | |
| 6dd74de | | | 57 | - **Purpose**: Generates points for a sine wave, useful for creating wavy-edged shapes. |
| 6dd74de | | | 58 | - **Usage**: |
| 6dd74de | | | 59 | - Facilitates the creation of shapes with wavy or sine-wave edges. |
| 6dd74de | | | 60 | - Can be used to add decorative or dynamic edges to shapes. |
| 6dd74de | | | 61 | |
| 6dd74de | | | 62 | ## Getting Started |
| 6dd74de | | | 63 | |
| 6dd74de | | | 64 | To utilize these utilities, simply import them from the `utils.ts` file into your shape creation script. These helpers will streamline the process of building and customizing SVG shapes, ensuring consistent results across your projects. |
| 6dd74de | | | 65 | |
| 6dd74de | | | 66 | ```typescript |
| 6dd74de | | | 67 | import { |
| 6dd74de | | | 68 | labelHelper, |
| 6dd74de | | | 69 | updateNodeBounds, |
| 6dd74de | | | 70 | insertPolygonShape, |
| 6dd74de | | | 71 | getNodeClasses, |
| 6dd74de | | | 72 | createPathFromPoints, |
| 6dd74de | | | 73 | generateFullSineWavePoints, |
| 6dd74de | | | 74 | } from './utils.ts'; |
| 6dd74de | | | 75 | ``` |
| 6dd74de | | | 76 | |
| 6dd74de | | | 77 | ## Example Usage |
| 6dd74de | | | 78 | |
| 6dd74de | | | 79 | Here’s a basic example of how you might use some of these utilities: |
| 6dd74de | | | 80 | |
| 6dd74de | | | 81 | ```typescript |
| 6dd74de | | | 82 | import { labelHelper, insertPolygonShape } from './utils.ts'; |
| 6dd74de | | | 83 | |
| 6dd74de | | | 84 | const svgContainer = document.getElementById('svgContainer'); |
| 6dd74de | | | 85 | |
| 6dd74de | | | 86 | // Insert a polygon shape |
| 6dd74de | | | 87 | insertPolygonShape(svgContainer /* shape-specific parameters */); |
| 6dd74de | | | 88 | |
| 6dd74de | | | 89 | // Create and insert a label inside the shape |
| 6dd74de | | | 90 | labelHelper(svgContainer /* label-specific parameters */); |
| 6dd74de | | | 91 | ``` |
| 6dd74de | | | 92 | |
| 6dd74de | | | 93 | ## Adding New Shapes |
| 6dd74de | | | 94 | |
| 6dd74de | | | 95 | ### 1. Create the Shape Function |
| 6dd74de | | | 96 | |
| 6dd74de | | | 97 | To add a new shape: |
| 6dd74de | | | 98 | |
| 6dd74de | | | 99 | - **Create the shape function**: Create a new file of name of the shape and export a function in the `shapes` directory that generates your shape. The file and function should follow the pattern used in existing shapes and return an SVG element. |
| 6dd74de | | | 100 | |
| 6dd74de | | | 101 | - **Example**: |
| 6dd74de | | | 102 | |
| 6dd74de | | | 103 | ```typescript |
| 6dd74de | | | 104 | import { Node, RenderOptions } from '../../types.ts'; |
| 6dd74de | | | 105 | |
| 6dd74de | | | 106 | export const myNewShape = async ( |
| 6dd74de | | | 107 | parent: SVGAElement, |
| 6dd74de | | | 108 | node: Node, |
| 6dd74de | | | 109 | renderOptions: RenderOptions |
| 6dd74de | | | 110 | ) => { |
| 6dd74de | | | 111 | // Create your shape here |
| 6dd74de | | | 112 | const shape = parent.insert('g').attr('class', 'my-new-shape'); |
| 6dd74de | | | 113 | // Add other elements or styles as needed |
| 6dd74de | | | 114 | return shape; |
| 6dd74de | | | 115 | }; |
| 6dd74de | | | 116 | ``` |
| 6dd74de | | | 117 | |
| 6dd74de | | | 118 | ### 2. Register the Shape |
| 6dd74de | | | 119 | |
| 6dd74de | | | 120 | - **Register the shape**: Add your shape to the `shapes` object in the [main shapes module](../rendering-util/rendering-elements/shapes.ts). This allows your shape to be recognized and used within the system. |
| 6dd74de | | | 121 | |
| 6dd74de | | | 122 | - **Example**: |
| 6dd74de | | | 123 | |
| 6dd74de | | | 124 | ```typescript |
| 6dd74de | | | 125 | import { myNewShape } from './shapes/myNewShape'; |
| 6dd74de | | | 126 | |
| 6dd74de | | | 127 | const shapes = { |
| 6dd74de | | | 128 | ..., |
| 6dd74de | | | 129 | { |
| 6dd74de | | | 130 | semanticName: 'My Shape', |
| 6dd74de | | | 131 | name: 'Shape Name', |
| 6dd74de | | | 132 | shortName: '<short-name>', |
| 6dd74de | | | 133 | description: '<Description for the shape>', |
| 6dd74de | | | 134 | aliases: ['<alias-one>', '<al-on>', '<alias-two>', '<al-two>'], |
| 6dd74de | | | 135 | handler: myNewShape, |
| 6dd74de | | | 136 | }, |
| 6dd74de | | | 137 | }; |
| 6dd74de | | | 138 | ``` |
| 6dd74de | | | 139 | |
| 6dd74de | | | 140 | # Shape Intersection Algorithms |
| 6dd74de | | | 141 | |
| 6dd74de | | | 142 | This contains algorithms and utilities for calculating intersection points for various shapes in SVG. Arrow intersection points are crucial for accurately determining where arrows connect with shapes. Ensuring precise intersection points enhances the clarity and accuracy of flowcharts and diagrams. |
| 6dd74de | | | 143 | |
| 6dd74de | | | 144 | ## Shape Intersection Functions |
| 6dd74de | | | 145 | |
| 6dd74de | | | 146 | ### 1. `Ellipse` |
| 6dd74de | | | 147 | |
| 6dd74de | | | 148 | Calculates the intersection points for an ellipse. |
| 6dd74de | | | 149 | |
| 6dd74de | | | 150 | **Usage**: |
| 6dd74de | | | 151 | |
| 6dd74de | | | 152 | ```javascript |
| 6dd74de | | | 153 | import intersectEllipse from './intersect-ellipse.js'; |
| 6dd74de | | | 154 | |
| 6dd74de | | | 155 | const intersection = intersectEllipse(node, rx, ry, point); |
| 6dd74de | | | 156 | ``` |
| 6dd74de | | | 157 | |
| 6dd74de | | | 158 | - **Parameters**: |
| 6dd74de | | | 159 | - `node`: The SVG node element. |
| 6dd74de | | | 160 | - `rx`: The x-radius of the ellipse. |
| 6dd74de | | | 161 | - `ry`: The y-radius of the ellipse. |
| 6dd74de | | | 162 | - `point`: The point from which the intersection is calculated. |
| 6dd74de | | | 163 | |
| 6dd74de | | | 164 | ### 2. `intersectRect` |
| 6dd74de | | | 165 | |
| 6dd74de | | | 166 | Calculates the intersection points for a rectangle. |
| 6dd74de | | | 167 | |
| 6dd74de | | | 168 | **Usage**: |
| 6dd74de | | | 169 | |
| 6dd74de | | | 170 | ```javascript |
| 6dd74de | | | 171 | import intersectRect from './intersect-rect.js'; |
| 6dd74de | | | 172 | |
| 6dd74de | | | 173 | const intersection = intersectRect(node, point); |
| 6dd74de | | | 174 | ``` |
| 6dd74de | | | 175 | |
| 6dd74de | | | 176 | - **Parameters**: |
| 6dd74de | | | 177 | - `node`: The SVG node element. |
| 6dd74de | | | 178 | - `point`: The point from which the intersection is calculated. |
| 6dd74de | | | 179 | |
| 6dd74de | | | 180 | ### 3. `intersectPolygon` |
| 6dd74de | | | 181 | |
| 6dd74de | | | 182 | Calculates the intersection points for a polygon. |
| 6dd74de | | | 183 | |
| 6dd74de | | | 184 | **Usage**: |
| 6dd74de | | | 185 | |
| 6dd74de | | | 186 | ```javascript |
| 6dd74de | | | 187 | import intersectPolygon from './intersect-polygon.js'; |
| 6dd74de | | | 188 | |
| 6dd74de | | | 189 | const intersection = intersectPolygon(node, polyPoints, point); |
| 6dd74de | | | 190 | ``` |
| 6dd74de | | | 191 | |
| 6dd74de | | | 192 | - **Parameters**: |
| 6dd74de | | | 193 | - `node`: The SVG node element. |
| 6dd74de | | | 194 | - `polyPoints`: Array of points defining the polygon. |
| 6dd74de | | | 195 | - `point`: The point from which the intersection is calculated. |
| 6dd74de | | | 196 | |
| 6dd74de | | | 197 | ## Cypress Tests |
| 6dd74de | | | 198 | |
| 6dd74de | | | 199 | To ensure the robustness of the flowchart shapes, there are implementation of comprehensive Cypress test cases in `newShapes.spec.ts` file. These tests cover various aspects such as: |
| 6dd74de | | | 200 | |
| 6dd74de | | | 201 | - **Shapes**: Testing new shapes like `bowTieRect`, `waveRectangle`, `trapezoidalPentagon`, etc. |
| 6dd74de | | | 202 | - **Looks**: Verifying shapes under different visual styles (`classic` and `handDrawn`). |
| 6dd74de | | | 203 | - **Directions**: Ensuring correct rendering in all flow directions of arrows : |
| 6dd74de | | | 204 | - `TB` `(Top -> Bottom)` |
| 6dd74de | | | 205 | - `BT` `(Bottom -> Top)` |
| 6dd74de | | | 206 | - `LR` `(Left -> Right)` |
| 6dd74de | | | 207 | - `RL` `(Right -> Left)` |
| 6dd74de | | | 208 | - **Labels**: Testing shapes with different labels, including: |
| 6dd74de | | | 209 | - No labels |
| 6dd74de | | | 210 | - Short labels |
| 6dd74de | | | 211 | - Very long labels |
| 6dd74de | | | 212 | - Markdown with `htmlLabels:true` and `htmlLabels:false` |
| 6dd74de | | | 213 | - **Styles**: Applying custom styles to shapes and verifying correct rendering. |
| 6dd74de | | | 214 | - **Class Definitions**: Using `classDef` to apply custom classes and testing their impact. |
| 6dd74de | | | 215 | |
| 6dd74de | | | 216 | ### Running the Tests |
| 6dd74de | | | 217 | |
| 6dd74de | | | 218 | To run the Cypress tests, follow these steps: |
| 6dd74de | | | 219 | |
| 6dd74de | | | 220 | 1. Ensure you have all dependencies installed by running: |
| 6dd74de | | | 221 | |
| 6dd74de | | | 222 | ```bash |
| 6dd74de | | | 223 | pnpm install |
| 6dd74de | | | 224 | ``` |
| 6dd74de | | | 225 | |
| 6dd74de | | | 226 | 2. Start the Cypress test runner: |
| 6dd74de | | | 227 | |
| 6dd74de | | | 228 | ```bash |
| 6dd74de | | | 229 | cypress open --env updateSnapshots=true |
| 6dd74de | | | 230 | |
| 6dd74de | | | 231 | ``` |
| 6dd74de | | | 232 | |
| 6dd74de | | | 233 | 3. Select the test suite from the Cypress interface to run all the flowchart shape tests. |