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: docs/api-reference/color/legend.md
+203-6Lines changed: 203 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,18 @@
1
1
---
2
2
sidebar_position: 3
3
-
sidebar_label: Legend
3
+
sidebar_label: Legends
4
4
slug: legend
5
5
---
6
6
7
7
import Legend from '@site/src/components/Legend';
8
+
import ColorSwatches from '@site/src/components/ColorSwatches';
9
+
import IconsSwatches from '@site/src/components/IconsSwatches';
8
10
9
-
# Legend
11
+
# Legends
10
12
11
-
## React component
13
+
## Numerical scale legends
14
+
15
+
### React component
12
16
13
17
To render the legend of a numerical color scale, you can use the `<Legend>` component as follow:
14
18
@@ -49,7 +53,7 @@ interface LegendProps {
49
53
50
54
Note that the Legend will fill the width of its container. [Get in touch](mailto:[email protected]) if you have ideas on improvements or pragmatic options we may have missed.
51
55
52
-
## Vanilla javascript
56
+
### Vanilla javascript
53
57
54
58
For non-react codebases, we provide a vanilla Javascript function that wraps this component and renders it into a container.
55
59
@@ -76,9 +80,9 @@ smplr.Color.drawLegend({
76
80
```
77
81
78
82
- `containerId` is the "id" of the html container where smplr.js should render the legend, something like "smplr-legend" that can be found in your html. Only ids are supported, not classes.
79
-
- `...legendProps` represents all other options as per the [react component section](#react-component).
83
+
- `...legendProps` represents all other options as per the previous section.
80
84
81
-
## Example legend
85
+
### Example
82
86
83
87
<Legend />
84
88
@@ -100,3 +104,196 @@ smplr.Color.drawLegend({
100
104
},
101
105
});
102
106
```
107
+
108
+
## Categorical scale legends
109
+
110
+
### React component
111
+
112
+
To render the legend of a numerical color scale, you can use the `<ColorSwatches>` component as follow:
113
+
114
+
```tsx
115
+
interface ColorSwatchesProps {
116
+
swatches: {
117
+
color: string
118
+
label: string
119
+
group?:string
120
+
}[]
121
+
size?:number
122
+
correctColor?:boolean
123
+
noLabels?:boolean
124
+
}
125
+
<ColorSwatches{...props: ColorSwatchesProps}>
126
+
127
+
// example usage with Color from smplr
128
+
<smplr.Color.ColorSwatches
129
+
swatches={[
130
+
{
131
+
color: 'red',
132
+
label: 'Alert',
133
+
},
134
+
{
135
+
color: 'orange',
136
+
label: 'Warning',
137
+
},
138
+
{
139
+
color: 'green',
140
+
label: 'All ok',
141
+
},
142
+
]}
143
+
/>
144
+
```
145
+
146
+
- `swatches` defines the colors and labels used for the swatches. Note that an optional group can be provided to create multiple lines with a label ahead of each group. You can refer to the [`ragSwatches`](/api-reference/color/scales#ragscale) and [`categorySwatches`](/api-reference/color/scales#categoryscale) helpers to generate swatches for categorical scales generated with our functions.
147
+
- `size` - _optional_ - is the size in pixels of each swatch. _Default value: 10._
148
+
- `correctColor` - _optional_ - lets you choose if the colors of the legend should be corrected to match the ones from the viewer as per the explanation in the [color mapping section](./overview#color-mapping). We correct them by default. _Default value: true._
149
+
- `noLabels` - _optional_ - set this to true to hide labels. _Default value: false._
150
+
151
+
152
+
### Vanilla javascript
153
+
154
+
For non-react codebases, we provide a vanilla Javascript function that wraps this component and renders it into a container.
155
+
156
+
```ts
157
+
smplr.Color.drawColorSwatches({
158
+
containerId: string
159
+
...swatchesProps: ColorSwatchesProps// see above
160
+
})
161
+
162
+
// example usage
163
+
smplr.Color.drawColorSwatches({
164
+
containerId: 'smplr-legend',
165
+
swatches: [
166
+
{
167
+
color: 'red',
168
+
label: 'Alert',
169
+
},
170
+
{
171
+
color: 'orange',
172
+
label: 'Warning',
173
+
},
174
+
{
175
+
color: 'green',
176
+
label: 'All ok',
177
+
},
178
+
]
179
+
})
180
+
```
181
+
182
+
- `containerId` is the "id" of the html container where smplr.js should render the legend, something like "smplr-legend" that can be found in your html. Only ids are supported, not classes.
183
+
- `...swatchesProps` represents all other options as per the previous section.
184
+
185
+
### Example
186
+
187
+
<ColorSwatches />
188
+
189
+
was rendered with the code below:
190
+
191
+
```ts
192
+
smplr.Color.drawColorSwatches({
193
+
containerId: 'smplr-legend',
194
+
swatches: [
195
+
{
196
+
color: 'red',
197
+
label: 'Alert',
198
+
},
199
+
{
200
+
color: 'orange',
201
+
label: 'Warning',
202
+
},
203
+
{
204
+
color: 'green',
205
+
label: 'All ok',
206
+
},
207
+
]
208
+
});
209
+
```
210
+
211
+
## Icons legends
212
+
213
+
### React component
214
+
215
+
To render the legend of a numerical color scale, you can use the `<IconsSwatches>` component as follow:
- `icons` defines the icons and labels used for the swatches. Note that an optional group can be provided to create multiple lines with a label ahead of each group.
245
+
- `height` - _optional_ - is the height in pixels of each swatch. _Default value: 16._
246
+
- `noLabels` - _optional_ - set this to true to hide labels. _Default value: false._
247
+
248
+
249
+
### Vanilla javascript
250
+
251
+
For non-react codebases, we provide a vanilla Javascript function that wraps this component and renders it into a container.
- `containerId` is the "id" of the html container where smplr.js should render the legend, something like "smplr-legend" that can be found in your html. Only ids are supported, not classes.
276
+
- `...swatchesProps` represents all other options as per the previous section.
Copy file name to clipboardExpand all lines: docs/api-reference/color/scales.md
+50-1Lines changed: 50 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -66,7 +66,7 @@ Configure a numerical scale using our interactive [colors playground](https://co
66
66
This function lets you quickly map a discrete number of named categories to colors. It comes with fallback color built-in, as well as type safe categories.
67
67
68
68
```ts
69
-
smplr.Color.numericScale<Cextendsstring>({
69
+
smplr.Color.categoryScale<Cextendsstring>({
70
70
categories: Record<C, string>
71
71
nodata?: string
72
72
}): ((category:C) =>string)
@@ -86,6 +86,28 @@ smplr.Color.categoryScale({
86
86
87
87
Typescript tip: You may disable category typesafety by passing a "loose" type hint to the function: `categoryScale<string>({...})`.
88
88
89
+
#### Easy swatches for your legend
90
+
91
+
When using a category scale, you can use the same arguments provided to create the scale to generate the corresponding swatches. This makes it easy to use a [legend for the scale](/api-reference/color/legend#categorical-scale-legends).
92
+
93
+
```ts
94
+
smplr.Color.categorySwatches<Cextendsstring>({
95
+
// same as categoryScale
96
+
categories: Record<C, string>
97
+
nodata?: string
98
+
// additional swatches config
99
+
excludeNoData?:boolean
100
+
noDataLabel?:string
101
+
}): {
102
+
color: string
103
+
label: string
104
+
}[]
105
+
```
106
+
107
+
-`categories` and `nodata` - refer to `categoryScale` above.
108
+
-`excludeNoData` - _optional_ - lets you opt out of having a swatch for the `nodata` color. _Default value: false._
109
+
-`noDataLabel` - _optional_ - lets you customize the label used for the `nodata` color. _Default value: 'No data'._
110
+
89
111
### ragScale
90
112
91
113
This function is built on top of `categoryScale` and provide a shortcut for red/amber/green scenarios. Here, the scale comes with pre-defined and optimized RAG colors, that can be customized. And the values "red", "amber", and "green" are always valid for quick testing.
@@ -116,3 +138,30 @@ smplr.Color.ragScale({
116
138
-`nodata` - _optional_ - is the color used when the value passed to the scale is not a known category. _Default value: #6a6c6c._
117
139
118
140
Typescript tip: You may disable category typesafety by passing a "loose" type hint to the function: `ragScale<string>({...})`.
141
+
142
+
#### Easy swatches for your legend
143
+
144
+
When using a RAG scale, you can use the same arguments provided to create the scale to generate the corresponding swatches. This makes it easy to use a [legend for the scale](/api-reference/color/legend#categorical-scale-legends).
-`autoRotate` - _optional_ - set this to true to have the viewer spin around the space automatically. You can also start, set the rotation speed, and stop the rotation as described [below](#auto-rotate-the-viewer). _Default value: false_
95
96
-`hideNavigationButtons` - _optional_ - set this to true if you want the user to control the camera but want to remove the navigation buttons. Mouse, touch and keyboard inputs will work while the buttons are hidden. _Default value: false_
96
97
-`hideLevelPicker` - _optional_ - set this to true if you want to remove the level picker from the viewer. Levels can still be controlled programmatically, so you could use your own buttons or logic. _Default value: false_
98
+
-`legendPosition` - _optional_ - lets you choose where the legend (if any is configured in the data layers) would be rendered. _Default value: 'top-left'_
- `...layerDefinition` - refer to the [overview](./overview#data-layers) page.
@@ -35,6 +60,10 @@ space.addDataLayer({
35
60
- Without this helper, we use `'-'` as a default value for all fields.
36
61
- `tooltipContainerStyle` - _optional_ - lets you override the style of the tooltip container with inline CSS.
37
62
- `persistentTooltip` - _optional_ - set this to `true` to turn tooltips into small cards that are all visible at once instead of on hover. Persistent tooltips are automatically positioned on the center of the data element they're attached to. They disappear when the camera is moving and reappear when it stops. They are only displayed for the top visible level. They only work for data elements with a non null or undefined `id`. _Default value: false_
63
+
- `legend` - _optional_ - lets you configure a legend to be rendered automatically in a collapsible overlay on the viewer. The legend can be positioned using `legendPosition` in [viewer options](/api-reference/space/custom-ux#viewer-options).
64
+
- For `numeric` legends, refer to options in [the legend section](/api-reference/color/legend#numerical-scale-legends).
65
+
- For `swatches` legends, refer to options in [the legend section](/api-reference/color/legend#categorical-scale-legends).
66
+
- For `icons` legends, refer to options in [the legend section](/api-reference/color/legend#icons-legends).
38
67
- `onClick` - _optional_ - is taking the data element that was clicked as argument, as well as the Javascript [pointer event](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent) that triggered the click. It is called each time a click or tap event happens.
39
68
- `onHover` - _optional_ - is taking the newly hovered data element as argument, as well as a limited (due to the rendering engine's internals) "pointer event" that triggered the handler. The limited event only includes the coordinates within the viewer of the pointer at the time when the event was triggered. The handler is called once when the pointer starts to hover a data element.
40
69
- `onHoverOut` - _optional_ - is taking the previously hovered data element as argument, as well as the same limited "pointer event" as for `onHover`. The handler is called once when the pointer stops hovering a data element.
0 commit comments