Skip to content

Commit 247ba7f

Browse files
ntachevaikoevskadimodi
authored
chore(sankey): polish sankey docs (#2279)
* chore(sankey): polish sankey docs * chore(sankey): link enum api * chore(sankey): add missing default values * Update components/sankey/elements/links.md Co-authored-by: Iva Stefanova Koevska-Atanasova <[email protected]> * Update components/sankey/elements/tooltip.md Co-authored-by: Iva Stefanova Koevska-Atanasova <[email protected]> * Update components/sankey/data-bind.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/data-bind.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/elements/labels.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/elements/labels.md Co-authored-by: Dimo Dimov <[email protected]> * Update components/sankey/elements/labels.md Co-authored-by: Dimo Dimov <[email protected]> * chore(sankey): shorten enum defaults --------- Co-authored-by: Iva Stefanova Koevska-Atanasova <[email protected]> Co-authored-by: Dimo Dimov <[email protected]>
1 parent 99453f7 commit 247ba7f

File tree

9 files changed

+300
-595
lines changed

9 files changed

+300
-595
lines changed

‎components/sankey/data-bind.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,10 @@ The `SankeyDataLink` object contains all the information for the link. It expose
2929

3030
| Property | Type and Default&nbsp;Value | Description |
3131
| --------- | ---- | ----------- |
32-
| `ColorType` | `SankeyLinksColorType` enum <br/> (`SankeyLinksColorType.Static`) | The color type of the link. Provides the following values <ul><li>`Static` the link color is set based on the `Color` property;</li><li>`Source` - the link color is set based on the source node color; </li><li>`Target` - the link color is set based on the target node color; </li></ul> |
33-
| `Color` | `string` | The color of the link. Applies when `ColorType="@SankeyLinksColorType.Static"`. |
32+
| `ColorType` | `SankeyLinksColorType` enum <br/> (`Static`) | The color type of the link. Provides the following values <ul><li>`Static` the link color is set based on the `Color` property;</li><li>`Source` - the link color is set based on the source node color; </li><li>`Target` - the link color is set based on the target node color; </li></ul> |
33+
| `Color` | `string` <br/> (`#666666`) | The color of the link. Applies when `ColorType="@SankeyLinksColorType.Static"`. |
3434
| `Highlight` | [`SankeyDataLinkHighlight`](/blazor-ui/api/Telerik.Blazor.Components.SankeyDataLinkHighlight) | The opacity of the active and inactive links when the user hovers a link. |
35-
| `Opacity` | `double?` | The opacity of the link. |
35+
| `Opacity` | `double?` <br/> (`0.4`) | The opacity of the link. |
3636
| `SourceId` | `object` | The source node ID of the link. The source node is the node from which the link originates. Required. |
3737
| `TargetId` | `object` | The target node ID of the link. The target node is the node to which the link points. Required. |
3838
| `Value` | `double?` | The value of the link. The value represents the weight of the link and determines the width of the link. Required. |
@@ -49,10 +49,10 @@ The `SankeyDataNode` object contains all the information for the node and its la
4949
| `Id` | `object` | The ID of the node. The ID is used to connect the nodes with the links. Required. |
5050
| `Label` | [`SankeyDataNodeLabel`](/blazor-ui/api/Telerik.Blazor.Components.SankeyDataNodeLabel) | Contains all the information for the node label - text, alignment, color, border and more. |
5151
| `Offset` | [`SankeyDataNodeOffset`](/blazor-ui/api/Telerik.Blazor.Components.SankeyDataNodeOffset)| The left and top offset of the node from the `<div class="k-sankey">` container. |
52-
| `Opacity` | `double?` | The opacity of the node. |
52+
| `Opacity` | `double?` <br/> (`1`) | The opacity of the node. |
5353
| `Padding` | `double?` | The minimum vertical space between two nodes. |
54-
| `Width` | `double?` | The width of the node. |
55-
| `Align` | `SankeyNodesAlign?` enum <br/> (`SankeyNodesAlign.Stretch`) | The alignment of the node. Supports the following values - `Stretch`, `Left`, and `Right`.|
54+
| `Width` | `double?` <br/> (`24`)| The width of the node. |
55+
| `Align` | [`SankeyNodesAlign?` enum](/blazor-ui/api/telerik.blazor.sankeynodesalign) <br/> (`Stretch`) | The alignment of the node.|
5656

5757
>tip The visual properties (`Color`, `Opacity` etc.) are not required. You can use these properties to [provide custom settings for the separate nodes through the data](#customize-elements-through-data). If you want to apply the same settings for all the nodes and labels in the Sankey use the component options for [nodes]({%slug sankey-nodes%}) and [labels]({%slug sankey-labels%}).
5858

‎components/sankey/elements/labels.md

Lines changed: 31 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,10 @@ To customize the labels, declare a `<SankeyLabels>` tag as a direct child of `<T
2121

2222
| Parameter | Type and Default&nbsp;Value | Description |
2323
| --------- | ---- | ----------- |
24-
| `Align` | `string` | The alignment of the labels. |
25-
| `Color` | `string` | The color of the labels. |
26-
| `Font` | `string` | The font of the labels. |
27-
| `Position` | `string` <br/> (`inside`) | The position of the labels. The supported values are: <ul><li>`inside` - the label is positioned after the node, except for the nodes at the end of the Sankey, that are placed before the node;</li><li>`before` - the label is positioned before the node; </li><li>`after` - the label is positioned after the node; </li></ul> |
24+
| `Align` | [`SankeyLabelsAlign` enum](/blazor-ui/api/telerik.blazor.sankeylabelsalign) <br/> (`Left`) | The alignment of the labels. |
25+
| `Color` | `string` <br/> (`rgb(66, 66, 66)`) | The color of the labels. |
26+
| `Font` | `string` <br/> (`14px Metric, Arial, Helvetica, sans-serif`)| The font of the labels. |
27+
| `Position` | [`SankeyLabelsPosition` enum](/blazor-ui/api/telerik.blazor.sankeylabelsposition) <br/> (`Inside`) | The position of the labels. |
2828
| `Visible` | `bool` <br/> (`true`) | Whether the labels are visible. |
2929

3030

@@ -39,8 +39,8 @@ By design, the labels do not have border. You may add border by declaring the `<
3939
| Parameter | Type and Default&nbsp;Value | Description |
4040
| --------- | ---- | ----------- |
4141
| `Color` | `string` | The color of the border. |
42-
| `DashType` | `DashType` enum <br/> (`DashType.Solid`) | The type of the border. |
43-
| `Width` | `double?` | The width of the border. |
42+
| `DashType` | [`DashType` enum](/blazor-ui/api/telerik.blazor.dashtype) <br/> (`Solid`) | The style of the border. |
43+
| `Width` | `double?` <br/> (`0`)| The width of the border. |
4444

4545
### Margin
4646

@@ -78,16 +78,15 @@ The `<SankeyLabelsStroke>` child tag provides the following properties:
7878
| Parameter | Type | Description |
7979
| --------- | ---- | ----------- |
8080
| `Color` | `string` | The color of the stroke. |
81-
| `LineJoin` | `string` | The [line join](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-linejoin) of the stroke. |
82-
| `Left` | `double?` | The width of the stroke. |
81+
| `Width` | `double?` <br/> (`0`) | The width of the stroke. |
8382

8483
## Example
8584

86-
Here is an example customization of the labels in the Sankey diagram.
85+
>caption Customizing the labels in the Sankey diagram
8786
8887
````CSHTML
8988
<TelerikSankey Data="@Data"
90-
Width="700px"
89+
DisableAutoLayout="true"
9190
Height="400px">
9291
<SankeyLabels Font="Monaco">
9392
<SankeyLabelsBorder Color="black" DashType="@DashType.LongDash" Width="1"></SankeyLabelsBorder>
@@ -97,40 +96,38 @@ Here is an example customization of the labels in the Sankey diagram.
9796
</TelerikSankey>
9897
9998
@code {
100-
private SankeyData Data { get; set; }
101-
private string EventLog { get; set; } = string.Empty;
102-
103-
#region Data generation
99+
private SankeyData? Data { get; set; }
104100
105101
protected override void OnInitialized()
106102
{
103+
var sourceNodes = 3;
104+
var destinationNodes = 3;
105+
107106
Data = new SankeyData()
108107
{
109108
Nodes = new SankeyDataNodes(),
110109
Links = new SankeyDataLinks()
111110
};
112111
113-
Data.Nodes.Add(new SankeyDataNode() { Id = 1, Label = new SankeyDataNodeLabel() { Text = "Tablet (12%)" } });
114-
Data.Nodes.Add(new SankeyDataNode() { Id = 2, Label = new SankeyDataNodeLabel() { Text = "Mobile (40%)" } });
115-
Data.Nodes.Add(new SankeyDataNode() { Id = 3, Label = new SankeyDataNodeLabel() { Text = "Desktop (48%)" } });
116-
Data.Nodes.Add(new SankeyDataNode() { Id = 4, Label = new SankeyDataNodeLabel() { Text = "< 18 years (8%)" } });
117-
Data.Nodes.Add(new SankeyDataNode() { Id = 5, Label = new SankeyDataNodeLabel() { Text = "18-26 years (35%)" } });
118-
Data.Nodes.Add(new SankeyDataNode() { Id = 6, Label = new SankeyDataNodeLabel() { Text = "27-40 years (38%)" } });
119-
Data.Nodes.Add(new SankeyDataNode() { Id = 7, Label = new SankeyDataNodeLabel() { Text = "> 40 years (19%)" } });
120-
121-
122-
Data.Links.Add(new SankeyDataLink() { SourceId = 1, TargetId = 4, Value = 4 });
123-
Data.Links.Add(new SankeyDataLink() { SourceId = 1, TargetId = 7, Value = 8 });
124-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 4, Value = 4 });
125-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 5, Value = 24 });
126-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 6, Value = 10 });
127-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 7, Value = 2 });
128-
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 5, Value = 11 });
129-
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 6, Value = 28 });
130-
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 7, Value = 9 });
131-
}
112+
for (int i = 1; i <= sourceNodes + destinationNodes; i++)
113+
{
114+
var nodeDescriptor = i <= sourceNodes ? "Source" : "Destination";
115+
Data.Nodes.Add(new SankeyDataNode() { Id = i, Label = new SankeyDataNodeLabel() { Text = $"{nodeDescriptor} {i}" } });
116+
}
132117
133-
#endregion Data generation
118+
for (int i = 1; i <= sourceNodes; i++)
119+
{
120+
for (int j = sourceNodes + 1; j <= sourceNodes + destinationNodes; j++)
121+
{
122+
Data.Links.Add(new SankeyDataLink()
123+
{
124+
SourceId = i,
125+
TargetId = j,
126+
Value = Random.Shared.Next(5, 30)
127+
});
128+
}
129+
}
130+
}
134131
}
135132
````
136133

‎components/sankey/elements/legend.md

Lines changed: 31 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,13 @@ To customize the legend in the Sankey chart, declare a `<SankeyLegend>` tag as a
1919

2020
| Parameter | Type and Default&nbsp;Value | Description |
2121
| --------- | ---- | ----------- |
22-
| `Align` | `SankeyLegendAlign` enum | The alignment of the legend. |
22+
| `Align` | [`SankeyLegendAlign` enum](/blazor-ui/api/telerik.blazor.sankeylegendalign) <br/> (`Start`) | The alignment of the legend. |
2323
| `Background` | `string` | The background color of the legend. |
2424
| `Height` | `double?` | The height of the legend. |
2525
| `OffsetX` | `double?` | The X offset of the legend. The offset is relative to the current position of the legend. |
2626
| `OffsetY` | `double?` | The Y offset of the legend. The offset is relative to the current position of the legend. |
27-
| `Orientation` | `SankeyLegendOrientation` enum <br/> (`SankeyLegendOrientation.Horizontal`) | The orientation of the legend. |
28-
| `Position` | `SankeyLegendPosition` enum <br/> (`SankeyLegendPosition.Bottom`)| The position of the legend. |
27+
| `Orientation` | [`SankeyLegendOrientation` enum](/blazor-ui/api/telerik.blazor.sankeylegendorientation) <br/> (`Horizontal`) | The orientation of the legend. |
28+
| `Position` | [`SankeyLegendPosition` enum](/blazor-ui/api/telerik.blazor.sankeylegendposition) <br/> (`Bottom`)| The position of the legend. |
2929
| `Reverse` | `double?` | Whether the legend items are reversed. |
3030
| `Spacing` | `double?` | The spacing between the labels of the legend. |
3131
| `Visible` | `bool?` <br/> (`true`) | Whether the legend is visible. |
@@ -52,57 +52,56 @@ The `<SankeyLegend>` tag exposes nested tags for further customization of the se
5252
5353
## Example
5454

55-
Customize the Sankey legend by using nested tag settings.
55+
>caption Customizing the Sankey legend by using nested tag settings
5656
5757
````CSHTML
5858
<TelerikSankey Data="@Data"
59-
Width="1000px"
59+
DisableAutoLayout="true"
6060
Height="400px">
61-
<SankeyLinks ColorType="@SankeyLinksColorType.Source"/>
61+
<SankeyLinks ColorType="@SankeyLinksColorType.Source" />
6262
<SankeyLegend Position="@SankeyLegendPosition.Top" Background="rgba(255, 99, 88, 0.1)">
6363
<SankeyLegendTitle Text="Device usage by age groups" Font="bold 17px sans-serif">
6464
<SankeyLegendTitlePadding Bottom="20"></SankeyLegendTitlePadding>
65-
</SankeyLegendTitle>
66-
<SankeyLegendItem AreaOpacity="0.7"/>
65+
</SankeyLegendTitle>
66+
<SankeyLegendItem AreaOpacity="0.7" />
6767
<SankeyLegendMargin Bottom="20" />
68-
<SankeyLegendPadding Top="10" Bottom="10"/>
68+
<SankeyLegendPadding Top="10" Bottom="10" />
6969
</SankeyLegend>
7070
</TelerikSankey>
7171
7272
@code {
73-
private SankeyData Data { get; set; }
74-
75-
#region Data generation
73+
private SankeyData? Data { get; set; }
7674
7775
protected override void OnInitialized()
7876
{
77+
var sourceNodes = 3;
78+
var destinationNodes = 3;
79+
7980
Data = new SankeyData()
8081
{
8182
Nodes = new SankeyDataNodes(),
8283
Links = new SankeyDataLinks()
8384
};
8485
85-
Data.Nodes.Add(new SankeyDataNode() { Id = 1, Label = new SankeyDataNodeLabel() { Text = "Tablet (12%)" } });
86-
Data.Nodes.Add(new SankeyDataNode() { Id = 2, Label = new SankeyDataNodeLabel() { Text = "Mobile (40%)" } });
87-
Data.Nodes.Add(new SankeyDataNode() { Id = 3, Label = new SankeyDataNodeLabel() { Text = "Desktop (48%)" } });
88-
Data.Nodes.Add(new SankeyDataNode() { Id = 4, Label = new SankeyDataNodeLabel() { Text = "< 18 years (8%)" } });
89-
Data.Nodes.Add(new SankeyDataNode() { Id = 5, Label = new SankeyDataNodeLabel() { Text = "18-26 years (35%)" } });
90-
Data.Nodes.Add(new SankeyDataNode() { Id = 6, Label = new SankeyDataNodeLabel() { Text = "27-40 years (38%)" } });
91-
Data.Nodes.Add(new SankeyDataNode() { Id = 7, Label = new SankeyDataNodeLabel() { Text = "> 40 years (19%)" } });
92-
93-
94-
Data.Links.Add(new SankeyDataLink() { SourceId = 1, TargetId = 4, Value = 4 });
95-
Data.Links.Add(new SankeyDataLink() { SourceId = 1, TargetId = 7, Value = 8 });
96-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 4, Value = 4 });
97-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 5, Value = 24 });
98-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 6, Value = 10 });
99-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 7, Value = 2 });
100-
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 5, Value = 11 });
101-
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 6, Value = 28 });
102-
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 7, Value = 9 });
103-
}
86+
for (int i = 1; i <= sourceNodes + destinationNodes; i++)
87+
{
88+
var nodeDescriptor = i <= sourceNodes ? "Source" : "Destination";
89+
Data.Nodes.Add(new SankeyDataNode() { Id = i, Label = new SankeyDataNodeLabel() { Text = $"{nodeDescriptor} {i}" } });
90+
}
10491
105-
#endregion Data generation
92+
for (int i = 1; i <= sourceNodes; i++)
93+
{
94+
for (int j = sourceNodes + 1; j <= sourceNodes + destinationNodes; j++)
95+
{
96+
Data.Links.Add(new SankeyDataLink()
97+
{
98+
SourceId = i,
99+
TargetId = j,
100+
Value = Random.Shared.Next(5, 30)
101+
});
102+
}
103+
}
104+
}
106105
}
107106
````
108107

‎components/sankey/elements/links.md

Lines changed: 26 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ To customize the nodes, declare the `<SankeyLinks>` tag as a direct child of `<T
2121

2222
| Parameter | Type and Default&nbsp;Value | Description |
2323
| --------- | ---- | ----------- |
24-
| `ColorType` | `SankeyLinksColorType` enum <br /> (`Static`) | The origin of the link color: <ul><li>`Static` - the link color is based on the `Color` property;</li><li>`Source` - the link color is based on the source node color; </li><li>`Target` - the link color is based on the target node color; </li></ul> |
24+
| `ColorType` | [`SankeyLinksColorType` enum](/blazor-ui/api/telerik.blazor.sankeylinkscolortype) <br /> (`Static`) | The origin of the link color: could be based on the `Color` property, on the source node color, or on the target node color. |
2525
| `Color` | `string` <br/> (`#666666`) | The color of the links. Applies when `ColorType="@SankeyLinksColorType.Static"`. |
2626
| `Opacity` | `double?` <br/> (`0.4`) | The opacity of the links. |
2727

@@ -36,52 +36,50 @@ The `<SankeyLinks>` tag exposes a child `<SankeyLinksHighlight>` tag that allows
3636

3737
## Example
3838

39-
Here is an example customization of the links in the Sankey Diagram.
39+
>caption Customizing the links in the Sankey diagram
4040
4141
````CSHTML
4242
<TelerikSankey Data="@Data"
43-
Width="700px"
43+
DisableAutoLayout="true"
4444
Height="400px">
4545
<SankeyLinks ColorType="@SankeyLinksColorType.Target" Opacity="0.5">
46-
<SankeyLinksHighlight Opacity="0.7" InactiveOpacity="0.2"></SankeyLinksHighlight>
46+
<SankeyLinksHighlight Opacity="0.7" InactiveOpacity="0.2"></SankeyLinksHighlight>
4747
</SankeyLinks>
4848
</TelerikSankey>
4949
5050
@code {
51-
private SankeyData Data { get; set; }
52-
private string EventLog { get; set; } = string.Empty;
53-
54-
#region Data generation
51+
private SankeyData? Data { get; set; }
5552
5653
protected override void OnInitialized()
5754
{
55+
var sourceNodes = 3;
56+
var destinationNodes = 3;
57+
5858
Data = new SankeyData()
5959
{
6060
Nodes = new SankeyDataNodes(),
6161
Links = new SankeyDataLinks()
6262
};
6363
64-
Data.Nodes.Add(new SankeyDataNode() { Id = 1, Label = new SankeyDataNodeLabel() { Text = "Tablet (12%)" } });
65-
Data.Nodes.Add(new SankeyDataNode() { Id = 2, Label = new SankeyDataNodeLabel() { Text = "Mobile (40%)" } });
66-
Data.Nodes.Add(new SankeyDataNode() { Id = 3, Label = new SankeyDataNodeLabel() { Text = "Desktop (48%)" } });
67-
Data.Nodes.Add(new SankeyDataNode() { Id = 4, Label = new SankeyDataNodeLabel() { Text = "< 18 years (8%)" } });
68-
Data.Nodes.Add(new SankeyDataNode() { Id = 5, Label = new SankeyDataNodeLabel() { Text = "18-26 years (35%)" } });
69-
Data.Nodes.Add(new SankeyDataNode() { Id = 6, Label = new SankeyDataNodeLabel() { Text = "27-40 years (38%)" } });
70-
Data.Nodes.Add(new SankeyDataNode() { Id = 7, Label = new SankeyDataNodeLabel() { Text = "> 40 years (19%)" } });
71-
72-
73-
Data.Links.Add(new SankeyDataLink() { SourceId = 1, TargetId = 4, Value = 4 });
74-
Data.Links.Add(new SankeyDataLink() { SourceId = 1, TargetId = 7, Value = 8 });
75-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 4, Value = 4 });
76-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 5, Value = 24 });
77-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 6, Value = 10 });
78-
Data.Links.Add(new SankeyDataLink() { SourceId = 2, TargetId = 7, Value = 2 });
79-
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 5, Value = 11 });
80-
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 6, Value = 28 });
81-
Data.Links.Add(new SankeyDataLink() { SourceId = 3, TargetId = 7, Value = 9 });
82-
}
64+
for (int i = 1; i <= sourceNodes + destinationNodes; i++)
65+
{
66+
var nodeDescriptor = i <= sourceNodes ? "Source" : "Destination";
67+
Data.Nodes.Add(new SankeyDataNode() { Id = i, Label = new SankeyDataNodeLabel() { Text = $"{nodeDescriptor} {i}" } });
68+
}
8369
84-
#endregion Data generation
70+
for (int i = 1; i <= sourceNodes; i++)
71+
{
72+
for (int j = sourceNodes + 1; j <= sourceNodes + destinationNodes; j++)
73+
{
74+
Data.Links.Add(new SankeyDataLink()
75+
{
76+
SourceId = i,
77+
TargetId = j,
78+
Value = Random.Shared.Next(5, 30)
79+
});
80+
}
81+
}
82+
}
8583
}
8684
````
8785

0 commit comments

Comments
 (0)