From 873d346c6606677d3ba0aa6077aa0f0f11cfc1a1 Mon Sep 17 00:00:00 2001
From: sbosse <sbosse@uni-bremen.de>
Date: Mon, 21 Jul 2025 23:36:13 +0200
Subject: [PATCH] Mon 21 Jul 22:43:21 CEST 2025

---
 js/ui/chart/docs/axes/cartesian/linear.md | 75 +++++++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 js/ui/chart/docs/axes/cartesian/linear.md

diff --git a/js/ui/chart/docs/axes/cartesian/linear.md b/js/ui/chart/docs/axes/cartesian/linear.md
new file mode 100644
index 0000000..ad82c55
--- /dev/null
+++ b/js/ui/chart/docs/axes/cartesian/linear.md
@@ -0,0 +1,75 @@
+# Linear Cartesian Axis
+
+The linear scale is use to chart numerical data. It can be placed on either the x or y axis. The scatter chart type automatically configures a line chart to use one of these scales for the x axis. As the name suggests, linear interpolation is used to determine where a value lies on the axis.
+
+## Tick Configuration Options
+
+The following options are provided by the linear scale. They are all located in the `ticks` sub options. These options extend the [common tick configuration](README.md#tick-configuration).
+
+| Name | Type | Default | Description
+| ---- | ---- | ------- | -----------
+| `beginAtZero` | `boolean` | | if true, scale will include 0 if it is not already included.
+| `min` | `number` | | User defined minimum number for the scale, overrides minimum value from data. [more...](#axis-range-settings)
+| `max` | `number` | | User defined maximum number for the scale, overrides maximum value from data. [more...](#axis-range-settings)
+| `maxTicksLimit` | `number` | `11` | Maximum number of ticks and gridlines to show.
+| `precision` | `number` | | if defined and `stepSize` is not specified, the step size will be rounded to this many decimal places.
+| `stepSize` | `number` | | User defined fixed step size for the scale. [more...](#step-size)
+| `suggestedMax` | `number` | | Adjustment used when calculating the maximum data value. [more...](#axis-range-settings)
+| `suggestedMin` | `number` | | Adjustment used when calculating the minimum data value. [more...](#axis-range-settings)
+
+## Axis Range Settings
+
+Given the number of axis range settings, it is important to understand how they all interact with each other.
+
+The `suggestedMax` and `suggestedMin` settings only change the data values that are used to scale the axis. These are useful for extending the range of the axis while maintaining the auto fit behaviour.
+
+```javascript
+let minDataValue = Math.min(mostNegativeValue, options.ticks.suggestedMin);
+let maxDataValue = Math.max(mostPositiveValue, options.ticks.suggestedMax);
+```
+
+In this example, the largest positive value is 50, but the data maximum is expanded out to 100. However, because the lowest data value is below the `suggestedMin` setting, it is ignored.
+
+```javascript
+let chart = new Chart(ctx, {
+    type: 'line',
+    data: {
+        datasets: [{
+            label: 'First dataset',
+            data: [0, 20, 40, 50]
+        }],
+        labels: ['January', 'February', 'March', 'April']
+    },
+    options: {
+        scales: {
+            yAxes: [{
+                ticks: {
+                    suggestedMin: 50,
+                    suggestedMax: 100
+                }
+            }]
+        }
+    }
+});
+```
+
+In contrast to the `suggested*` settings, the `min` and `max` settings set explicit ends to the axes. When these are set, some data points may not be visible.
+
+## Step Size
+If set, the scale ticks will be enumerated by multiple of `stepSize`, having one tick per increment. If not set, the ticks are labeled automatically using the nice numbers algorithm.
+
+This example sets up a chart with a y axis that creates ticks at `0, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 4.5, 5`.
+
+```javascript
+let options = {
+    scales: {
+        yAxes: [{
+            ticks: {
+                max: 5,
+                min: 0,
+                stepSize: 0.5
+            }
+        }]
+    }
+};
+```