Merge pull request #82 from smplrspace/next

v2.25.0
smplrspace · Sep 12, 2024 · fa724a3 · fa724a3
2 parents b4c7b29 + 9081842
commit fa724a3
Show file tree

Hide file tree

Showing 9 changed files with 380 additions and 15 deletions.
diff --git a/docs/api-reference/color/legend.md b/docs/api-reference/color/legend.md
@@ -1,14 +1,18 @@
 ---
 sidebar_position: 3
-sidebar_label: Legend
+sidebar_label: Legends
 slug: legend
 ---
 
 import Legend from '@site/src/components/Legend';
+import ColorSwatches from '@site/src/components/ColorSwatches';
+import IconsSwatches from '@site/src/components/IconsSwatches';
 
-# Legend
+# Legends
 
-## React component
+## Numerical scale legends
+
+### React component
 
 To render the legend of a numerical color scale, you can use the `<Legend>` component as follow:
 
@@ -49,7 +53,7 @@ interface LegendProps {
 
 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.
 
-## Vanilla javascript
+### Vanilla javascript
 
 For non-react codebases, we provide a vanilla Javascript function that wraps this component and renders it into a container.
 
@@ -76,9 +80,9 @@ smplr.Color.drawLegend({
 ```
 
 - `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.
-- `...legendProps` represents all other options as per the [react component section](#react-component).
+- `...legendProps` represents all other options as per the previous section.
 
-## Example legend
+### Example
 
 <Legend />
 
@@ -100,3 +104,196 @@ smplr.Color.drawLegend({
   },
 });
 ```
+
+## Categorical scale legends
+
+### React component
+
+To render the legend of a numerical color scale, you can use the `<ColorSwatches>` component as follow:
+
+```tsx
+interface ColorSwatchesProps {
+  swatches: {
+    color: string
+    label: string
+    group?: string
+  }[]
+  size?: number
+  correctColor?: boolean
+  noLabels?: boolean
+}
+<ColorSwatches {...props: ColorSwatchesProps}>
+
+// example usage with Color from smplr
+<smplr.Color.ColorSwatches
+  swatches={[
+    {
+      color: 'red',
+      label: 'Alert',
+    },
+    {
+      color: 'orange',
+      label: 'Warning',
+    },
+    {
+      color: 'green',
+      label: 'All ok',
+    },
+  ]}
+/>
+```
+
+- `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.
+- `size` - _optional_ - is the size in pixels of each swatch. _Default value: 10._
+- `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._
+- `noLabels` - _optional_ - set this to true to hide labels. _Default value: false._
+
+
+### Vanilla javascript
+
+For non-react codebases, we provide a vanilla Javascript function that wraps this component and renders it into a container.
+
+```ts
+smplr.Color.drawColorSwatches({
+  containerId: string
+  ...swatchesProps: ColorSwatchesProps // see above
+})
+
+// example usage
+smplr.Color.drawColorSwatches({
+  containerId: 'smplr-legend',
+  swatches: [
+    {
+      color: 'red',
+      label: 'Alert',
+    },
+    {
+      color: 'orange',
+      label: 'Warning',
+    },
+    {
+      color: 'green',
+      label: 'All ok',
+    },
+  ]
+})
+```
+
+- `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.
+- `...swatchesProps` represents all other options as per the previous section.
+
+### Example
+
+<ColorSwatches />
+
+was rendered with the code below:
+
+```ts
+smplr.Color.drawColorSwatches({
+  containerId: 'smplr-legend',
+  swatches: [
+    {
+      color: 'red',
+      label: 'Alert',
+    },
+    {
+      color: 'orange',
+      label: 'Warning',
+    },
+    {
+      color: 'green',
+      label: 'All ok',
+    },
+  ]
+});
+```
+
+## Icons legends
+
+### React component
+
+To render the legend of a numerical color scale, you can use the `<IconsSwatches>` component as follow:
+
+```tsx
+interface IconsSwatchesProps {
+  icons: {
+    url: string
+    label: string
+    group?: string
+  }[]
+  height?: number
+  noLabels?: boolean
+}
+<IconsSwatches {...props: IconsSwatchesProps}>
+
+// example usage with Color from smplr
+<smplr.Color.IconsSwatches
+  icons={[
+    {
+      url: 'https://retail.smplrspace.io/img/electric.png',
+      label: 'EV charging',
+    },
+    {
+      url: 'https://retail.smplrspace.io/img/wheelchair.png',
+      label: 'Reduced mobility',
+    }
+  ]}
+/>
+```
+
+- `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.
+- `height` - _optional_ - is the height in pixels of each swatch. _Default value: 16._
+- `noLabels` - _optional_ - set this to true to hide labels. _Default value: false._
+
+
+### Vanilla javascript
+
+For non-react codebases, we provide a vanilla Javascript function that wraps this component and renders it into a container.
+
+```ts
+smplr.Color.drawIconsSwatches({
+  containerId: string
+  ...swatchesProps: IconsSwatchesProps // see above
+})
+
+// example usage
+smplr.Color.drawIconsSwatches({
+  containerId: 'smplr-legend',
+  icons: [
+    {
+      url: 'https://retail.smplrspace.io/img/electric.png',
+      label: 'EV charging',
+    },
+    {
+      url: 'https://retail.smplrspace.io/img/wheelchair.png',
+      label: 'Reduced mobility',
+    }
+  ]
+})
+```
+
+- `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.
+- `...swatchesProps` represents all other options as per the previous section.
+
+### Example
+
+<IconsSwatches />
+
+was rendered with the code below:
+
+```ts
+smplr.Color.drawIconsSwatches({
+  containerId: 'smplr-legend',
+  icons: [
+    {
+      url: 'https://retail.smplrspace.io/img/electric.png',
+      label: 'EV charging',
+    },
+    {
+      url: 'https://retail.smplrspace.io/img/wheelchair.png',
+      label: 'Reduced mobility',
+    }
+  ],
+  height: 20
+});
+```
diff --git a/docs/api-reference/color/scales.md b/docs/api-reference/color/scales.md
@@ -66,7 +66,7 @@ Configure a numerical scale using our interactive [colors playground](https://co
 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.
 
 ```ts
-smplr.Color.numericScale<C extends string>({
+smplr.Color.categoryScale<C extends string>({
   categories: Record<C, string>
   nodata?: string
 }): ((category: C) => string)
@@ -86,6 +86,28 @@ smplr.Color.categoryScale({
 
 Typescript tip: You may disable category typesafety by passing a "loose" type hint to the function: `categoryScale<string>({...})`.
 
+#### Easy swatches for your legend
+
+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).
+
+```ts
+smplr.Color.categorySwatches<C extends string>({
+  // same as categoryScale
+  categories: Record<C, string>
+  nodata?: string
+  // additional swatches config
+  excludeNoData?: boolean
+  noDataLabel?: string
+}): {
+  color: string
+  label: string
+}[]
+```
+
+- `categories` and `nodata` - refer to `categoryScale` above.
+- `excludeNoData` - _optional_ - lets you opt out of having a swatch for the `nodata` color. _Default value: false._
+- `noDataLabel` - _optional_ - lets you customize the label used for the `nodata` color. _Default value: 'No data'._
+
 ### ragScale
 
 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({
 - `nodata` - _optional_ - is the color used when the value passed to the scale is not a known category. _Default value: #6a6c6c._
 
 Typescript tip: You may disable category typesafety by passing a "loose" type hint to the function: `ragScale<string>({...})`.
+
+#### Easy swatches for your legend
+
+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).
+
+```ts
+smplr.Color.ragSwatches<C extends string | 'red' | 'amber' | 'green'>({
+  // same as ragScale
+  categories?: Partial<Record<'red' | 'amber' | 'green', C>>
+  colors?: {
+    red?: string
+    amber?: string
+    green?: string
+  }
+  nodata?: string
+  // additional swatches config
+  excludeNoData?: boolean
+  noDataLabel?: string
+}): {
+  color: string
+  label: string
+}[]
+```
+
+- `categories`, `colors` and `nodata` - refer to `ragScale` above.
+- `excludeNoData` - _optional_ - lets you opt out of having a swatch for the `nodata` color. _Default value: false._
+- `noDataLabel` - _optional_ - lets you customize the label used for the `nodata` color. _Default value: 'No data'._
diff --git a/docs/api-reference/space/custom-ux.md b/docs/api-reference/space/custom-ux.md
@@ -81,6 +81,7 @@ space.startViewer({
   autoRotate?: boolean,
   hideNavigationButtons?: boolean
   hideLevelPicker?: boolean
+  legendPosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
 }) => void
 ```
 
@@ -94,6 +95,7 @@ space.startViewer({
 - `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_
 - `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_
 - `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_
+- `legendPosition` - _optional_ - lets you choose where the legend (if any is configured in the data layers) would be rendered. _Default value: 'top-left'_
 
 ## Viewer controls
 
@@ -117,6 +119,24 @@ space.setMode(mode: '2d' | '3d') => void
 
 - `mode` - the desired rendering mode.
 
+### Show/hide level picker
+
+This is the programmatic equivalent of setting `hideLevelPicker` in `startViewer`:
+
+```ts
+space.showLevelPicker() => void
+space.hideLevelPicker() => void
+```
+
+### Show/hide the navigation buttons
+
+This is the programmatic equivalent of setting `hideNavigationButtons` in `startViewer`:
+
+```ts
+space.showNavigationButtons() => void
+space.hideNavigationButtons() => void
+```
+
 ### Navigate levels
 
 This is the programmatic equivalent to pressing the level buttons in the bottom-left controls:

diff --git a/docs/api-reference/space/data-layers.md b/docs/api-reference/space/data-layers.md
@@ -17,10 +17,35 @@ space.addDataLayer({
   tooltipTemplate?: string,
   tooltipContainerStyle?: string,
   persistentTooltip?: boolean,
+  legend?: LegendConfig, // see below
   onClick?: (dataElement: object, event: PointerEvent) => void,
   onHover?: (dataElement: object, event: LimitedPointerEvent) => void,
   onHoverOut?: (dataElement: object, event: LimitedPointerEvent) => void
 }) => DataLayerController
+
+type LegendConfig =
+  | {
+    type: 'numeric'
+    colorScale: (n: number | null | undefined) => string
+    domain?: [number, number]
+    ticks?: Record<number, number | string>
+  }
+  | {
+    type: 'swatches'
+    swatches: {
+      color: string
+      label: string
+      group?: string
+    }[]
+  }
+  | {
+    type: 'icons'
+    icons: {
+      url: string
+      label: string
+      group?: string
+    }[]
+  }
 ```
 
 - `...layerDefinition` - refer to the [overview](./overview#data-layers) page.
@@ -35,6 +60,10 @@ space.addDataLayer({
   - Without this helper, we use `'-'` as a default value for all fields.
 - `tooltipContainerStyle` - _optional_ - lets you override the style of the tooltip container with inline CSS.
 - `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_
+- `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).
+  - For `numeric` legends, refer to options in [the legend section](/api-reference/color/legend#numerical-scale-legends).
+  - For `swatches` legends, refer to options in [the legend section](/api-reference/color/legend#categorical-scale-legends).
+  - For `icons` legends, refer to options in [the legend section](/api-reference/color/legend#icons-legends).
 - `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.
 - `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.
 - `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.