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