You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/docs/migrate-to-v1.md
+331-3Lines changed: 331 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,6 +5,334 @@ next: ../../components/
5
5
6
6
# Migrate to v1.0
7
7
8
-
::: warning WIP
9
-
This guide is currently being written and will be published in the coming days.
10
-
:::
8
+
This guide covers notable changes and breaking changes introduced in **Charts.css** version 1.0. It will help you migrate from version 0.x to 1.x.
9
+
10
+
## Notable Changes
11
+
12
+
**New:**
13
+
14
+
* New chart type - Pie chart.
15
+
* New aspect-ratio for charts.
16
+
* New orientation utility classes to reverse labels.
17
+
* New utility classes to align labels.
18
+
* New utility classes to position data.
19
+
* New CSS variables to style legends.
20
+
* New `--end` CSS variable.
21
+
* New `@property` types added to all CSS variables.
22
+
* New SCSS prefix added to all CSS variables.
23
+
* Fix legend colors to make them repeat after the basic 10 colors.
24
+
* Fix axes by replace hardcoded SASS division with CSS `calc()`.
25
+
26
+
**Removals:**
27
+
28
+
*`--heading-size` variable was removed.
29
+
*`labels-align-start` class was replaced with `labels-align-{block|inline}-start`.
30
+
*`labels-align-center` class was replaced with `labels-align-{block|inline}-center`.
31
+
*`labels-align-end` class was replaced with `labels-align-{block|inline}-end`.
32
+
33
+
**Best Practices:**
34
+
35
+
* Prefer styling with a wrapper element.
36
+
* Custom chart `height` is no longer required.
37
+
38
+
### Wrapper
39
+
40
+
Previously, you could either apply custom `id` attributes on a `<table>` element:
41
+
42
+
```html{1}
43
+
<table class="charts-css bar ..." id="my-chart">
44
+
...
45
+
</table>
46
+
```
47
+
48
+
Or, on a wrapping `<div>`:
49
+
50
+
```html{1}
51
+
<div id="my-chart">
52
+
53
+
<table class="charts-css bar ...">
54
+
...
55
+
</table>
56
+
57
+
</div>
58
+
```
59
+
60
+
You can still do that, but as of this release it's no longer recommended.
61
+
62
+
All the docs have been updated to recommend using a wrapper `<div>` with custom `id` attribute. This change makes it easier to add new inner elements like the [legend](../components/legend/), [axes titles](../components/axes/#axis-title), [multiple mixed charts](./../charts/mixed/) etc.
63
+
64
+
We strongly recommend adding [wrapper elements](./../components/wrapper/) when migrating from version 0.x to 1.x.
65
+
66
+
### Chart Height
67
+
68
+
**Breaking change!** Previously, when serving an empty `<td>` or utilizing the `hide-data` / `show-data-on-hover` utility classes, the chart had no height. To overcome this issue, you had to set a custom style containing a minimum `height` value. It's no longer required.
69
+
70
+
```diff
71
+
- #my-chart .column {
72
+
- height: 200px;
73
+
- }
74
+
```
75
+
76
+
### Aspect Ratio
77
+
78
+
**Breaking change!** Version 1.0.0 uses `aspect-ratio` on `<tbody>` element, making sure the chart always has a height even when you don't set a `height`. This change sets a proportional height based on the chart width.
79
+
80
+
The change has the potential to change the height of existing charts. When migrating to 1.0, if the chart height is changed when you remove the `height` property, use `aspect-ratio` instead:
81
+
82
+
```css
83
+
#my-chart.columntbody {
84
+
aspect-ratio: 21 / 9;
85
+
}
86
+
```
87
+
88
+
Note that [each chart type has a different aspect ratio](./../customization/basic-styling/#aspect-ratio).
89
+
90
+
### Heading Size
91
+
92
+
Previously, when you had a long text inside the `<caption>`, the text and the chart were overlapping. To fix this visual issue, you could increase the size of the heading with the `--heading-size` variable, and tweak the size for each media query. It's no longer required.
93
+
94
+
As of this release, the size of the heading text fits to the content, without any external workarounds. When migrating to version 1.x, remove all the `--heading-size` variables from your chart customizations. This variable has been removed from **Charts.css**.
95
+
96
+
```diff
97
+
- #my-chart .column {
98
+
- --heading-size: 3rem;
99
+
- }
100
+
```
101
+
102
+
### Reverse Labels
103
+
104
+
Previously, there were three [orientation](../components/orientation/) utility classes for reversing the order of different elements inside the chart - `reverse`, `reverse-data` and `reverse-dataset`.
105
+
106
+
As of this release, a fourth orientation class was added, the `reverse-labels` class. This class allows you to [position the labels on the other side](./../components/orientation/#reverse-labels). Charts with reversed labels position the label where the data ends, rather where the data starts.
With this feature you can create **[Population Pyramid](./../components/orientation/#population-pyramid-chart)** charts. It can be achieved by positioning side-by-side two bar charts with reversed labels.
Version 1.0.0 also introduced [Pie charts](../charts/pie/), streamline the process of converting data tables to an additional [chart type](../charts/) using a simple CSS utility class. This is the first circular chart introduced by **Charts.css**.
Previously, all labels were aligned to the center of the `<th>` element. As of this release, the labels are aligned to the beginning of the row in [bar charts](../charts/bar/) and to the bottom of the column on [column](../charts/column/), [area](../charts/area/) and [line](../charts/line/) charts.
302
+
303
+
To control the [position alignment of the label](./../components/labels/#align-labels), you get more possibilities.
304
+
305
+
**Deprecated classes:**
306
+
307
+
*`labels-align-start`
308
+
*`labels-align-center`
309
+
*`labels-align-end`
310
+
311
+
**New classes:**
312
+
313
+
*`labels-align-inline-start`
314
+
*`labels-align-inline-center`
315
+
*`labels-align-inline-end`
316
+
*`labels-align-block-start`
317
+
*`labels-align-block-center`
318
+
*`labels-align-block-end`
319
+
320
+
### Data Position
321
+
322
+
Previously you couldn't control where the data will be displayed. It was fixed at the end of the row. Version 1.0.0 introduces additional CSS utility classes snd variables that help you customize the position of your data.
323
+
324
+
**New classes:**
325
+
326
+
*`data-start`
327
+
*`data-center`
328
+
*`data-end`
329
+
*`data-outside`
330
+
331
+
**New variables:**
332
+
333
+
*`--data-position`
334
+
335
+
Furthermore, when you have a very low or a very heigh value on your bar and column charts, the data seems out of position. Version 1.0.0 introduces new utility classes added either to the `<td>` element or to the `<span>` element wrapping the data. The new classes are:
0 commit comments