@meonode/canvas 1.3.1 → 1.5.0

package/README.md

@@ -33,7 +33,7 @@ rendering to a canvas.
   </tr>
   <tr>
     <td width="50%"><img src="https://i.ibb.co.com/B24SZ0C9/charts.webp" alt="Image 5"/></td>
-    <td width="50%"><img src="https://i.ibb.co.com/q3sy9r2L/sample-grids.png" alt="Image 6"/></td>
+    <td width="50%"><img src="https://i.ibb.co.com/jkBJMRgT/sample-nested-grids.png" alt="Image 6"/></td>
   </tr>
 </table>
 
@@ -52,41 +52,41 @@ import {Root, Box, Text} from '@meonode/canvas';
 import {writeFile} from 'fs/promises';
 
 async function generateImage() {
-    const canvas = await Root({
-        width: 500,
-        height: 300,
-        fonts: [
-            {
-                family: 'Roboto',
-                paths: ['./fonts/Roboto-Regular.ttf', './fonts/Roboto-Bold.ttf'],
-            },
-        ],
+  const canvas = await Root({
+    width: 500,
+    height: 300,
+    fonts: [
+      {
+        family: 'Roboto',
+        paths: ['./fonts/Roboto-Regular.ttf', './fonts/Roboto-Bold.ttf'],
+      },
+    ],
+    children: [
+      Box({
+        width: '100%',
+        height: '100%',
+        backgroundColor: '#f0f0f0',
+        padding: 20,
         children: [
-            Box({
-                width: '100%',
-                height: '100%',
-                backgroundColor: '#f0f0f0',
-                padding: 20,
-                children: [
-                    Text('Hello, World!', {
-                        fontSize: 32,
-                        fontWeight: 'bold',
-                        fontFamily: 'Roboto',
-                        color: '#333',
-                    }),
-                    Text('This is a basic example of using @meonode/canvas.', {
-                        fontSize: 18,
-                        fontFamily: 'Roboto',
-                        color: '#666',
-                        margin: {Top: 10},
-                    }),
-                ],
-            }),
+          Text('Hello, World!', {
+            fontSize: 32,
+            fontWeight: 'bold',
+            fontFamily: 'Roboto',
+            color: '#333',
+          }),
+          Text('This is a basic example of using @meonode/canvas.', {
+            fontSize: 18,
+            fontFamily: 'Roboto',
+            color: '#666',
+            margin: {Top: 10},
+          }),
         ],
-    });
+      }),
+    ],
+  });
 
-    const buffer = await canvas.toBuffer('png');
-    await writeFile('output.png', buffer);
+  const buffer = await canvas.toBuffer('png');
+  await writeFile('output.png', buffer);
 }
 
 generateImage().catch(console.error);
@@ -102,109 +102,109 @@ import {Root, Column, Row, Text, Image, Style} from '@meonode/canvas';
 import {writeFile} from 'fs/promises';
 
 async function generateComplexImage() {
-    const canvas = await Root({
-        width: 800,
-        height: 600,
-        fonts: [
-            {
-                family: 'Roboto',
-                paths: ['./fonts/Roboto-Regular.ttf', './fonts/Roboto-Bold.ttf'],
-            },
-            {
-                family: 'Open Sans',
-                paths: ['./fonts/OpenSans-Regular.ttf'],
-            },
-        ],
+  const canvas = await Root({
+    width: 800,
+    height: 600,
+    fonts: [
+      {
+        family: 'Roboto',
+        paths: ['./fonts/Roboto-Regular.ttf', './fonts/Roboto-Bold.ttf'],
+      },
+      {
+        family: 'Open Sans',
+        paths: ['./fonts/OpenSans-Regular.ttf'],
+      },
+    ],
+    children: [
+      Column({
+        width: '100%',
+        height: '100%',
+        backgroundColor: '#f0f0f0',
+        padding: 20,
+        justifyContent: Style.Justify.SpaceBetween,
         children: [
-            Column({
+          // Header Section
+          Row({
+            width: '100%',
+            alignItems: Style.Align.Center,
+            marginBottom: 20,
+            children: [
+              Image({
+                src: 'https://via.placeholder.com/80x80/FF0000/FFFFFF?text=Logo',
+                width: 80,
+                height: 80,
+                borderRadius: 40,
+                marginRight: 20,
+                objectFit: 'cover',
+              }),
+              Text('Welcome to MeoNode Canvas!', {
+                fontSize: 40,
+                fontWeight: 'bold',
+                fontFamily: 'Roboto',
+                color: '#333',
+              }),
+            ],
+          }),
+
+          // Main Content Section
+          Column({
+            flexGrow: 1,
+            width: '100%',
+            backgroundColor: '#ffffff',
+            borderRadius: 10,
+            padding: 30,
+            boxShadow: {blur: 10, color: 'rgba(0,0,0,0.1)'},
+            children: [
+              Text('A New Way to Render Graphics', {
+                fontSize: 28,
+                fontWeight: 'bold',
+                fontFamily: 'Open Sans',
+                color: '#555',
+                marginBottom: 15,
+              }),
+              Text(
+                `This example demonstrates a more complex layout using various components.
+        We have a header with a logo and title, a main content area with text,
+        and a footer. Notice how flexbox properties are used to arrange elements.`,
+                {
+                  fontSize: 18,
+                  fontFamily: 'Open Sans',
+                  color: '#777',
+                  lineHeight: 24,
+                },
+              ),
+              Image({
+                src: 'https://via.placeholder.com/600x200/007bff/ffffff?text=Feature+Image',
                 width: '100%',
-                height: '100%',
-                backgroundColor: '#f0f0f0',
-                padding: 20,
-                justifyContent: Style.Justify.SpaceBetween,
-                children: [
-                    // Header Section
-                    Row({
-                        width: '100%',
-                        alignItems: Style.Align.Center,
-                        marginBottom: 20,
-                        children: [
-                            Image({
-                                src: 'https://via.placeholder.com/80x80/FF0000/FFFFFF?text=Logo',
-                                width: 80,
-                                height: 80,
-                                borderRadius: 40,
-                                marginRight: 20,
-                                objectFit: 'cover',
-                            }),
-                            Text('Welcome to MeoNode Canvas!', {
-                                fontSize: 40,
-                                fontWeight: 'bold',
-                                fontFamily: 'Roboto',
-                                color: '#333',
-                            }),
-                        ],
-                    }),
-
-                    // Main Content Section
-                    Column({
-                        flexGrow: 1,
-                        width: '100%',
-                        backgroundColor: '#ffffff',
-                        borderRadius: 10,
-                        padding: 30,
-                        boxShadow: {blur: 10, color: 'rgba(0,0,0,0.1)'},
-                        children: [
-                            Text('A New Way to Render Graphics', {
-                                fontSize: 28,
-                                fontWeight: 'bold',
-                                fontFamily: 'Open Sans',
-                                color: '#555',
-                                marginBottom: 15,
-                            }),
-                            Text(
-                                `This example demonstrates a more complex layout using various components.
-                We have a header with a logo and title, a main content area with text,
-                and a footer. Notice how flexbox properties are used to arrange elements.`,
-                                {
-                                    fontSize: 18,
-                                    fontFamily: 'Open Sans',
-                                    color: '#777',
-                                    lineHeight: 24,
-                                },
-                            ),
-                            Image({
-                                src: 'https://via.placeholder.com/600x200/007bff/ffffff?text=Feature+Image',
-                                width: '100%',
-                                height: 200,
-                                marginTop: 20,
-                                borderRadius: 8,
-                                objectFit: 'contain',
-                                objectPosition: {Top: '50%', Left: '50%'},
-                            }),
-                        ],
-                    }),
-
-                    // Footer Section
-                    Row({
-                        width: '100%',
-                        marginTop: 20,
-                        justifyContent: Style.Justify.Center,
-                        children: [
-                            Text('© 2025 MeoNode Canvas. All rights reserved.', {
-                                fontSize: 14,
-                                fontFamily: 'Open Sans',
-                                color: '#999',
-                            }),
-                        ],
-                    }),
-                ],
-            }),
+                height: 200,
+                marginTop: 20,
+                borderRadius: 8,
+                objectFit: 'contain',
+                objectPosition: {Top: '50%', Left: '50%'},
+              }),
+            ],
+          }),
+
+          // Footer Section
+          Row({
+            width: '100%',
+            marginTop: 20,
+            justifyContent: Style.Justify.Center,
+            children: [
+              Text('© 2025 MeoNode Canvas. All rights reserved.', {
+                fontSize: 14,
+                fontFamily: 'Open Sans',
+                color: '#999',
+              }),
+            ],
+          }),
         ],
-    });
+      }),
+    ],
+  });
 
-    const buffer = await canvas.toBuffer('png');
-    await writeFile('complex_output.png', buffer);
+  const buffer = await canvas.toBuffer('png');
+  await writeFile('complex_output.png', buffer);
 }
 
 generateComplexImage().catch(console.error);
@@ -221,39 +221,39 @@ import {Root, Chart} from '@meonode/canvas';
 import {writeFile} from 'fs/promises';
 
 async function generateBarChart() {
-    const canvas = await Root({
-        width: 600,
-        height: 400,
-        children: [
-            Chart({
-                type: 'bar',
-                width: '100%',
-                height: '100%',
-                data: {
-                    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
-                    datasets: [
-                        {
-                            label: 'Sales',
-                            data: [120, 150, 180, 90, 200],
-                            color: '#36A2EB',
-                        },
-                    ],
-                },
-                options: {
-                    gridOptions: {show: true, style: 'dashed'},
-                    axisColor: '#333',
-                    labelColor: '#333',
-                    showValues: true,
-                    valueFontSize: 12,
-                    showYAxis: true,
-                    yAxisColor: '#666',
-                },
-            }),
-        ],
-    });
+  const canvas = await Root({
+    width: 600,
+    height: 400,
+    children: [
+      Chart({
+        type: 'bar',
+        width: '100%',
+        height: '100%',
+        data: {
+          labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
+          datasets: [
+            {
+              label: 'Sales',
+              data: [120, 150, 180, 90, 200],
+              color: '#36A2EB',
+            },
+          ],
+        },
+        options: {
+          gridOptions: {show: true, style: 'dashed'},
+          axisColor: '#333',
+          labelColor: '#333',
+          showValues: true,
+          valueFontSize: 12,
+          showYAxis: true,
+          yAxisColor: '#666',
+        },
+      }),
+    ],
+  });
 
-    const buffer = await canvas.toBuffer('png');
-    await writeFile('bar_chart.png', buffer);
+  const buffer = await canvas.toBuffer('png');
+  await writeFile('bar_chart.png', buffer);
 }
 
 generateBarChart().catch(console.error);
@@ -266,37 +266,37 @@ import {Root, Chart, Row, Box, Text} from '@meonode/canvas';
 import {writeFile} from 'fs/promises';
 
 async function generateDoughnutChart() {
-    const canvas = await Root({
-        width: 600,
-        height: 400,
-        children: [
-            Chart({
-                type: 'doughnut',
-                width: '100%',
-                height: '100%',
-                data: [
-                    {label: 'Red', value: 300, color: '#FF6384'},
-                    {label: 'Blue', value: 50, color: '#36A2EB'},
-                    {label: 'Yellow', value: 100, color: '#FFCE56'},
-                ],
-                options: {
-                    innerRadius: 0.7,
-                    sliceBorderRadius: 5,
-                    renderLegendItem: ({item, color}) =>
-                        Row({
-                            alignItems: 'center',
-                            children: [
-                                Box({width: 12, height: 12, backgroundColor: color, borderRadius: 6}),
-                                Text(`${item.label}: ${item.value}`, {fontSize: 16, marginLeft: 8}),
-                            ],
-                        }),
-                },
-            }),
+  const canvas = await Root({
+    width: 600,
+    height: 400,
+    children: [
+      Chart({
+        type: 'doughnut',
+        width: '100%',
+        height: '100%',
+        data: [
+          {label: 'Red', value: 300, color: '#FF6384'},
+          {label: 'Blue', value: 50, color: '#36A2EB'},
+          {label: 'Yellow', value: 100, color: '#FFCE56'},
         ],
-    });
+        options: {
+          innerRadius: 0.7,
+          sliceBorderRadius: 5,
+          renderLegendItem: ({item, color}) =>
+            Row({
+              alignItems: 'center',
+              children: [
+                Box({width: 12, height: 12, backgroundColor: color, borderRadius: 6}),
+                Text(`${item.label}: ${item.value}`, {fontSize: 16, marginLeft: 8}),
+              ],
+            }),
+        },
+      }),
+    ],
+  });
 
-    const buffer = await canvas.toBuffer('png');
-    await writeFile('doughnut_chart.png', buffer);
+  const buffer = await canvas.toBuffer('png');
+  await writeFile('doughnut_chart.png', buffer);
 }
 
 generateDoughnutChart().catch(console.error);
@@ -315,25 +315,25 @@ import {Root, Grid, Box, Text} from '@meonode/canvas';
 import {writeFile} from 'fs/promises';
 
 async function generateBasicGrid() {
-    const canvas = await Root({
-        width: 400,
-        height: 300,
+  const canvas = await Root({
+    width: 400,
+    height: 300,
+    children: [
+      Grid({
+        columns: 3,
+        templateColumns: [100, 100, 100], // or ['100px', '100px', '100px']
+        gap: 10,
         children: [
-            Grid({
-                columns: 3,
-                templateColumns: [100, 100, 100], // or ['100px', '100px', '100px']
-                gap: 10,
-                children: [
-                    Box({backgroundColor: 'red', height: 50, children: [Text('1')]}),
-                    Box({backgroundColor: 'blue', height: 50, children: [Text('2')]}),
-                    Box({backgroundColor: 'green', height: 50, children: [Text('3')]}),
-                    Box({backgroundColor: 'yellow', height: 50, children: [Text('4')]}),
-                ],
-            }),
+          Box({backgroundColor: 'red', height: 50, children: [Text('1')]}),
+          Box({backgroundColor: 'blue', height: 50, children: [Text('2')]}),
+          Box({backgroundColor: 'green', height: 50, children: [Text('3')]}),
+          Box({backgroundColor: 'yellow', height: 50, children: [Text('4')]}),
         ],
-    });
+      }),
+    ],
+  });
 
-    await canvas.toFile('grid_basic.png');
+  await canvas.toFile('grid_basic.png');
 }
 
 generateBasicGrid();
@@ -345,14 +345,14 @@ Using fractional units (`fr`) allows columns to take up proportional space.
 
 ```typescript
 Grid({
-    // First column takes 1 part, second takes 2 parts, third takes 1 part
-    templateColumns: ['1fr', '2fr', '1fr'],
-    gap: 10,
-    children: [
-        Box({backgroundColor: 'red', height: 50, children: [Text('1fr')]}),
-        Box({backgroundColor: 'blue', height: 50, children: [Text('2fr')]}),
-        Box({backgroundColor: 'green', height: 50, children: [Text('1fr')]}),
-    ],
+  // First column takes 1 part, second takes 2 parts, third takes 1 part
+  templateColumns: ['1fr', '2fr', '1fr'],
+  gap: 10,
+  children: [
+    Box({backgroundColor: 'red', height: 50, children: [Text('1fr')]}),
+    Box({backgroundColor: 'blue', height: 50, children: [Text('2fr')]}),
+    Box({backgroundColor: 'green', height: 50, children: [Text('1fr')]}),
+  ],
 });
 ```
 
@@ -364,27 +364,27 @@ Use `GridItem` (or just passing `gridColumn`/`gridRow` props to any child) to sp
 import {Grid, GridItem, Box, Text} from '@meonode/canvas';
 
 Grid({
-    templateColumns: ['1fr', '1fr', '1fr'],
-    gap: 10,
-    children: [
-        // Spans all 3 columns
-        GridItem({
-            gridColumn: 'span 3',
-            height: 50,
-            backgroundColor: '#333',
-            children: [Text('Header', {color: 'white'})],
-        }),
-        // Standard items
-        Box({backgroundColor: '#eee', height: 100, children: [Text('Content')]}),
-        Box({backgroundColor: '#ccc', height: 100, children: [Text('Sidebar')]}),
-        // Spans 2 columns
-        GridItem({
-            gridColumn: 'span 2',
-            height: 50,
-            backgroundColor: '#555',
-            children: [Text('Footer', {color: 'white'})],
-        }),
-    ],
+  templateColumns: ['1fr', '1fr', '1fr'],
+  gap: 10,
+  children: [
+    // Spans all 3 columns
+    GridItem({
+      gridColumn: 'span 3',
+      height: 50,
+      backgroundColor: '#333',
+      children: [Text('Header', {color: 'white'})],
+    }),
+    // Standard items
+    Box({backgroundColor: '#eee', height: 100, children: [Text('Content')]}),
+    Box({backgroundColor: '#ccc', height: 100, children: [Text('Sidebar')]}),
+    // Spans 2 columns
+    GridItem({
+      gridColumn: 'span 2',
+      height: 50,
+      backgroundColor: '#555',
+      children: [Text('Footer', {color: 'white'})],
+    }),
+  ],
 });
 ```
 
@@ -399,19 +399,19 @@ For example, to set `flexDirection` to `row` or `positionType` to `absolute`, yo
 import {Box, Style} from '@meonode/canvas';
 
 Box({
-    flexDirection: Style.FlexDirection.Row,
-    justifyContent: Style.Justify.Center,
-    alignItems: Style.Align.Center,
-    children: [
-        Box({
-            width: 100,
-            height: 100,
-            backgroundColor: 'red',
-            positionType: Style.PositionType.Absolute,
-            position: {Top: 10, Left: 10},
-        }),
-        // ... other children
-    ],
+  flexDirection: Style.FlexDirection.Row,
+  justifyContent: Style.Justify.Center,
+  alignItems: Style.Align.Center,
+  children: [
+    Box({
+      width: 100,
+      height: 100,
+      backgroundColor: 'red',
+      positionType: Style.PositionType.Absolute,
+      position: {Top: 10, Left: 10},
+    }),
+    // ... other children
+  ],
 });
 ```
 
@@ -584,7 +584,36 @@ The `options` prop is a conditional type that changes based on the chart `type`.
 | `showYAxis`           | `boolean`                   | If `true`, displays the Y-axis labels on the left.                |
 | `yAxisColor`          | `string`                    | Color of the Y-axis labels.                                       |
 | `yAxisFontSize`       | `number`                    | Font size of the Y-axis labels.                                   |
-| `yAxisLabelFormatter` | `(value: number) => string` | Custom formatter for Y-axis labels.                               |
+| `yAxisLabelFormatter` | `(value: number) => string` | Custom formatter for Y-axis labels. Smart defaults adjust decimal precision based on value range. |
+| `xAxisLabelFormatter` | `(value: string, index: number) => string` | Custom formatter for X-axis labels. Useful for truncating or transforming labels. |
+
+###### Y-Axis Label Formatter
+
+The `yAxisLabelFormatter` enables custom Y-axis label formatting. By default, it uses smart formatting:
+- **Values < 1**: 4 decimals (e.g., `0.0025`)
+- **Values 1-100**: 2 decimals (e.g., `25.43`)
+- **Values 100-1000**: 1 decimal (e.g., `250.5`)
+- **Values 1000-1M**: 0 decimals (e.g., `50000`)
+- **Values ≥ 1M**: 1 decimal with "M" suffix (e.g., `1.5M`)
+
+Custom example:
+```typescript
+options: {
+  yAxisLabelFormatter: (value) => `$${value.toFixed(2)}`,
+}
+```
+
+###### X-Axis Label Formatter
+
+The `xAxisLabelFormatter` allows custom X-axis label transformations. It receives the label string and its index.
+
+Custom example:
+```typescript
+options: {
+  xAxisLabelFormatter: (label, index) => 
+    label.length > 5 ? label.substring(0, 5) + '...' : label,
+}
+```
 
 ##### Pie & Doughnut Chart Options (`pie`, `doughnut`)
 
@@ -616,4 +645,3 @@ started.
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-

package/dist/cjs/canvas/canvas.type.d.ts

@@ -755,6 +755,7 @@ interface CartesianChartSpecificOptions {
     yAxisFontSize?: number;
     yAxisColor?: string;
     yAxisLabelFormatter?: (value: number) => string;
+    xAxisLabelFormatter?: (value: string, index: number) => string;
 }
 interface PieChartSpecificOptions {
     /**