npm package: @hyperobjekt/legend
Description: <svg class="jss6" width="300" height="24"><g transform="translate(24 4)"><rect x="0" y="0" height="16" width="50.400000000000006" style="fill: rgb(0, 0, 4);"></rect><rect x="50.400000000000006" y="0" height="16" width="50.400000000000006" style="fill: rgb
Latest version: 4.0.0

# @hyperobjekt/legend

<svg class="jss6" width="300" height="24"><g transform="translate(24 4)"><rect x="0" y="0" height="16" width="50.400000000000006" style="fill: rgb(0, 0, 4);"></rect><rect x="50.400000000000006" y="0" height="16" width="50.400000000000006" style="fill: rgb(81, 18, 124);"></rect><rect x="100.80000000000001" y="0" height="16" width="50.39999999999999" style="fill: rgb(183, 55, 121);"></rect><rect x="151.2" y="0" height="16" width="50.40000000000002" style="fill: rgb(252, 137, 97);"></rect><rect x="201.60000000000002" y="0" height="16" width="50.39999999999999" style="fill: rgb(252, 253, 191);"></rect></g></svg>  
<svg width="300" viewBox="0,0,300,24"><g transform="translate(24 0.5)" fill="none" font-size="10" font-family="sans-serif" text-anchor="middle"><path class="domain" stroke="currentColor" d="M1,6V0H251V6"></path><g class="tick" opacity="1" transform="translate(1,0)"><line stroke="currentColor" y2="6"></line><text fill="currentColor" y="9" dy="0.71em">200</text></g><g class="tick" opacity="1" transform="translate(51,0)"><line stroke="currentColor" y2="6"></line><text fill="currentColor" y="9" dy="0.71em">360</text></g><g class="tick" opacity="1" transform="translate(101,0)"><line stroke="currentColor" y2="6"></line><text fill="currentColor" y="9" dy="0.71em">520</text></g><g class="tick" opacity="1" transform="translate(151,0)"><line stroke="currentColor" y2="6"></line><text fill="currentColor" y="9" dy="0.71em">680</text></g><g class="tick" opacity="1" transform="translate(201,0)"><line stroke="currentColor" y2="6"></line><text fill="currentColor" y="9" dy="0.71em">840</text></g><g class="tick" opacity="1" transform="translate(251,0)"><line stroke="currentColor" y2="6"></line><text fill="currentColor" y="9" dy="0.71em">1.0k</text></g></g></svg>

This package consists of react components for creating data scales that can be used for data readouts or legends.

It allows for several different types of scales, including:

- continuous scales
- category scales
- quantile scales
- quantize scales
- threshold scales

Each scale consists of a wrapper component with one or more child components.

- `<Scale.Colors />`: renders the scale's colors
- `<Scale.Ticks />`: renders an axis to label the scale
- `<Scale.Marker />` renders a marker on the scale at a given value

See the [storybook](https://hyperobjekt.github.io/core/) for further documentation and usage examples.

## Usage

Install the package with:

```
npm i @hyperobjekt/legend
```

or

```
yarn add @hyperobjekt/legend
```

Import the required components and the base CSS styles:

```jsx
import Scale from "@hyperobjekt/legend";
import "@hyperobjekt/legend/Scale.css";
```

Assemble the scale parts as desired:

```jsx
<Scale type="continuous" min={0} max={100} colors="YlGnBu">
  <Scale.Colors />
  <Scale.Ticks />
  <Scale.Marker value={33} pointer />
</Scale>
```

## Components

### `<Scale />`

The parent component that contains the scale configuration.

#### Props

- `type`: determines which type of scale to use ("category", "continuous", "quantize", "quantile", "threshold")
- `width`: determines the width of the scale
- `colors`: either an array of colors or a string representing a scale from [d3-scale-chromatic](https://observablehq.com/@d3/color-schemes?collection=@d3/d3-scale-chromatic)
- `margin`: an object containing top, left, bottom, right margins for the scale
- `nice`: adjusts the scale to use "nice" values (e.g. 1000 instead of 994)
- `data`: A set of data values to use for the scale
- `accessor`: A function that selects a data value (used when `data` is an array of objects instead of an array of values)
- `thresholds`: Contains threshold points when using `threshold` scale type
- `chunks`: Determines how many groups to split data into for `quantize` and `quantile` scales.
- `min`: Minimum value for the scale
- `max`: Maximum value for the scale

#### Usage

See the [storybook](https://hyperobjekt.github.io/core/) for usage and examples.

### `<Scale.Colors />`

Renders a color scale for the given data and scale type.

#### Props

- `height`: height of the color scale

#### Usage

See the [storybook](https://hyperobjekt.github.io/core/) for usage

### `<Scale.Ticks />`

Renders tick labels for the given data and scale type.

#### Props

- `ticks`: the target number of ticks to show on the scale (continuous)
- `tickFormat`: a formatter function for ticks on the scale
- `tickValues`: used to explicitly specify where to render ticks on the scale
- `tickSize`: size of the ticks on the scale
- `tickSizeInner`: size of the inner ticks on the scale
- `tickSizeOuter`: size of the outer ticks on the scale
- `tickPadding`: padding space between ticks

#### Usage

See the [storybook](https://hyperobjekt.github.io/core/) for usage

### `<Scale.Marker />`

Renders a marker with optional label at a given location on the scale.

#### Props

- `value`: determines which point on the scale has the marker
- `pointer`: when true, renders a pointer on the scale at the value
- `renderPointer`: a function that takes {color, position, value} and returns JSX to render the pointer
- `color`: overrides the pointer color (uses value color by default)

#### Usage

See the [storybook](https://hyperobjekt.github.io/core/) for usage

## Utility Functions

The following utility functions are provided by this package:

### `getScale(type, {data, accessor, min, max, thresholds, chunks })`

Returns all relevant scales for the given `type` and config object.

### `getColors(value, numColors)`

This function will return an array of hex color strings based on the provided `value` parameter.

**Parameters**

- `value`: either a string containing a scale name from [d3-scale-chromatic](https://observablehq.com/@d3/color-schemes) (e.g. "YlGnBu") or an array of color strings (e.g. ["#f00", "#0f0", "#00f"])
- `numColors`: the number of colors to return

### `getColorScale(type, domain, colors)`

Returns a color scale that maps a data domain to a color string.

- `type`: a string representing scale type ("category", "quantile", "quantize", "threshold", "linear", or "sequential")
- `domain`: the data domain for the scale
- `colors`: either a string containing a scale name from [d3-scale-chromatic](https://observablehq.com/@d3/color-schemes) (e.g. "YlGnBu") or an array of color strings (e.g. ["#f00", "#0f0", "#00f"]) that will be used to map domain values to

### `getPositionScale(type, domain, range, options)`

Returns a scale that maps a data domain to a pixel value range.

- `type`: a string representing scale type ("category", "quantile", "threshold", or "linear")
- `domain`: the data domain for the scale
- `range`: the range of pixel values to map to
- `options`: options for the scale
  - `nice`: when true, the domain is adjusted to have [nice values](https://github.com/d3/d3-scale#continuous_nice)

## `useScaleContext()`

You can use the `useScaleContext()` hook provided by this package to create your own child components. The scale context provides the following:

- `width`: width of the scale
- `margin`: margins for the scale
- `data`: data for the scale
- `position`: a scale for mapping values to position on the scale
- `color`: a scale for mapping values to colors
- `chunks`: objects containing data for "chunks" on discrete scales (not available on continuous scales)
- `extent`: an array with the [min, max] of the position / color scale