31:[] 2f:{"title":"Color Legend Element","cells":[{"id":0,"value":"# Color Legend Element\n\nA [Custom Element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) suitable for use as a legend in data\nvisualizations. Built using the [Lit](https://lit.dev) web-component library and [D3JS](https://d3js.org/). Inspired by [@mbostock](https://observablehq.com/@mbostock)'s [Color Legend](https://observablehq.com/@d3/color-legend) here on Observable.","pinned":false,"hidden":false,"mode":"md"},{"id":495,"value":" defaultWidth ? defaultWidth : width}\"\n/>","pinned":true,"hidden":false,"mode":"html"},{"id":518,"value":"Read more below to learn about how to use the ${cle()} here in Observable, or checkout the [Github repository](https://github.com/clhenrick/color-legend-element) and [color-legend docs](https://clhenrick.github.io/color-legend-element/).","pinned":false,"hidden":false,"mode":"md"},{"id":334,"value":"install = md`## Install`","pinned":false,"hidden":false,"mode":"ojs"},{"id":104,"value":"To use the ${cle()} within Observable, simply `require` the `color-legend-element` in a cell:\n\n```js\nrequire(\"color-legend-element\");\n```\n\nOr pin to a specific version:\n\n```js\nrequire(\"color-legend-element@1.1.0\");\n```\n\nIt is not necessary to use a named cell when you `require` the \"color-legend-element\" library as it will define a Custom Element named \"color-legend\" using the browser's built-in [CustomElementRegistry.define](https://developer.mozilla.org/en-US/docs/Web/API/CustomElementRegistry/define) method. This means we are free to simply write `` in HTML in our notebooks and the browser will recognize it as a valid HTML element. Read on to learn how to use the Color Legend Element's attributes and properties to customize it to your needs.","pinned":false,"hidden":false,"mode":"md"},{"id":1072,"value":"dependencies = md`### Dependencies`","pinned":false,"hidden":false,"mode":"ojs"},{"id":364,"value":"

\n**Note:** The ${cle()} assumes D3JS is available as a [peer dependency](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#peerdependencies). At the very least this should include the following modules from the D3JS library:\n\n`d3-scale`, \n`d3-array`, \n`d3-format`, \n`d3-interpolate`, and optionally\n`d3-scale-chromatic` (if using a d3 color scheme interpolator).\n\nThis isn't a problem on Observable because [D3JS is available in all notebooks by default](https://observablehq.com/@observablehq/recommended-libraries), but keep it in mind if using the ${cle()} outside of Observable.\n

","pinned":false,"hidden":false,"mode":"md"},{"id":97,"value":"example_usage = md`## Example Usage`","pinned":false,"hidden":false,"mode":"ojs"},{"id":36,"value":"### Continuous Legend\n\nWithout providing any attributes the ${cle()} renders a continuous legend by default: ","pinned":false,"hidden":false,"mode":"md"},{"id":24,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":143,"value":"

\n**Note:** in Observable self closing tags for custom elements are enabled via Observable's [Hypertext Literal](https://observablehq.com/@observablehq/htl) library. However, when declared in vanilla HTML, custom elements must have both an opening and closing tag: \n\n```\n\n```\n

","pinned":false,"hidden":false,"mode":"md"},{"id":60,"value":"The following default configuration options determine how the ${cle()} renders above: \n\n|property | default value |\n|---|---| \n|`titleText` | \"Color Legend Element\"|\n|`scaleType`| \"continuous\"|\n|`domain` | `[0, 1]` |\n|`range` | `[ \"#ffffcc\", \"#a1dab4\", \"#41b6c4\", \"#2c7fb8\", \"#253494\"]`|\n| `tickFormat` | \".1f\" |\n\nA full list of the ${cle()}'s HTML attributes and respective JavaScript properties may be found [in its README](https://github.com/clhenrick/color-legend-element#properties). More of them will be covered below.","pinned":false,"hidden":false,"mode":"md"},{"id":548,"value":"The color gradient for a continuous `${cle()}` may be altered one of two ways:\n\n1. By passing an array of color strings as the `range` attribute / property.\n2. By setting the `interpolator` property to a color interpolator function using JavaScript.\n\nBelow the range is updated using an array of color values from [d3-scale-chromatic](https://github.com/d3/d3-scale-chromatic):","pinned":false,"hidden":false,"mode":"md"},{"id":553,"value":"viewof scheme = Inputs.select(schemes, { label: md`**Color Scheme**` })","pinned":false,"hidden":false,"mode":"ojs"},{"id":557,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":570,"value":"

\n **Note:** The ${cle()} `domain` and `range` attributes must be specified as strings when set as HTML attributes, hence the use of `JSON.stringify()` above. Internally they are converted to arrays after being set, thanks to [Lit's auto handling of attribute values](https://lit.dev/docs/components/properties/#attributes). The `domain` and `range` properties may also be set as regular arrays using JavaScript.\n

","pinned":false,"hidden":false,"mode":"md"},{"id":93,"value":"#### Using a Color Interpolator","pinned":false,"hidden":false,"mode":"md"},{"id":86,"value":"By default, the [`d3.interpolateHcl`](https://github.com/d3/d3-interpolate#interpolateHcl) color `interpolator` is used in conjunction with the color values of the `range` property to render the color gradient for continuous legends. This behavior may be overridden by setting the `interpolator` property directly (to one of [`d3-scale-chromatic`](https://github.com/d3/d3-scale-chromatic)'s for example) using JavaScript:\n\n```js\nlet cle = document.querySelector(\"color-legend\");\ncle.interpolator = d3.interpolateViridis;\n```\n\nNote that the `interpolator` property is the only configuration option that may not be set as an HTML attribute on the ${cle()}. All other configuration options may be set via either HTML attributes or JavaScript properties.","pinned":false,"hidden":false,"mode":"md"},{"id":154,"value":"viewof interpolator = Inputs.select(interpolatorOptions, {\n label: md`**color interpolator**`,\n value: \"interpolateViridis\"\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":66,"value":"cleInterpolator = {\n let cle = htl.html``;\n cle.interpolator = d3[interpolator];\n return cle;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":305,"value":"

\n**Note**: Any ${cle()} JavaScript property that is written in \"camelCase\" will be converted to an HTML attribute in lowercase. For example, the `scaleType` property is accessible as `scaletype` as an HTML attribute as evident below:\n

","pinned":false,"hidden":false,"mode":"md"},{"id":320,"value":"cleInterpolator.outerHTML","pinned":true,"hidden":false,"mode":"ojs"},{"id":161,"value":"interpolatorOptions = `\n interpolateBrBG,\n interpolatePRGn,\n interpolatePiYG,\n interpolatePuOr,\n interpolateRdBu,\n interpolateRdGy,\n interpolateRdYlBu,\n interpolateRdYlGn,\n interpolateSpectral,\n interpolateBuGn,\n interpolateBuPu,\n interpolateGnBu,\n interpolateOrRd,\n interpolatePuBuGn,\n interpolatePuBu,\n interpolatePuRd,\n interpolateRdPu,\n interpolateYlGnBu,\n interpolateYlGn,\n interpolateYlOrBr,\n interpolateYlOrRd,\n interpolateBlues,\n interpolateGreens,\n interpolateGreys,\n interpolatePurples,\n interpolateReds,\n interpolateOranges,\n interpolateCividis,\n interpolateCubehelixDefault,\n interpolateWarm,\n interpolateCool,\n interpolateSinebow,\n interpolateTurbo,\n interpolateViridis,\n interpolateMagma,\n interpolateInferno,\n interpolatePlasma\n`\n .split(\",\")\n .map((x) => x.trim())","pinned":false,"hidden":false,"mode":"ojs"},{"id":681,"value":"#### Customizing the Axis Ticks\nYou may customize how the axis ticks are rendered by using the following attributes/properties: `ticks`, `tickSize`, `tickFormat`, and `tickValues`.","pinned":false,"hidden":false,"mode":"md"},{"id":1091,"value":"viewof tickFormat = Inputs.text({ label: \"tickFormat\", value: \".0f\" })","pinned":false,"hidden":false,"mode":"ojs"},{"id":1098,"value":"viewof tickSize = Inputs.range([3, 15], {\n label: \"tickSize\",\n value: 10,\n step: 1\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":684,"value":"{\n let cle = cleInterpolator.cloneNode(true);\n cle.tickSize = tickSize;\n cle.tickValues = [0, 25, 50, 75, 100];\n cle.tickFormat = tickFormat;\n return cle;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":948,"value":"There's also a `tickFormatter` property which can be set directly using JavaScript, in case the options in `d3-format` don't meet your needs. The `tickFormatter` is typically set internally after setting `tickFormat`, so prefer to use `tickFormat` instead when possible and consider this a fallback.","pinned":false,"hidden":false,"mode":"md"},{"id":968,"value":"cleTickFormatter = htl.html``","pinned":true,"hidden":false,"mode":"ojs"},{"id":1058,"value":"{\n cleTickFormatter.tickFormatter = (d) => `${d * 100}%`;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":168,"value":"### Discrete Legends\n\nTo render a discrete legend set the `scaleType` property to \"discrete\" and set the number of color values in the `range` property to the number of desired buckets. The `domain` will be divided according to the number of values in the `range`.","pinned":false,"hidden":false,"mode":"md"},{"id":182,"value":"viewof rangeLength = Inputs.number([2, 9], {\n step: 1,\n label: md`**Number of range values**`,\n placeholder: \"\",\n value: 9\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":171,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":212,"value":"rangeValues = [\n \"#fcfbfd\",\n \"#efedf5\",\n \"#dadaeb\",\n \"#bcbddc\",\n \"#9e9ac8\",\n \"#807dba\",\n \"#6a51a3\",\n \"#54278f\",\n \"#3f007d\"\n].slice(0, rangeLength)","pinned":false,"hidden":false,"mode":"ojs"},{"id":223,"value":"### Threshold Legends\n\nThreshold legends may be rendered by setting the `scaleType` property to \"threshold\", specifying the desired tick values as the `domain`, and the desired color values in the `range`. To render correctly, the length of the `range` should be one less than the length of the `domain`.","pinned":false,"hidden":false,"mode":"md"},{"id":234,"value":"viewof domainValues = Inputs.text({\n value: \"0, 11, 22, 33, 50, 100\",\n label: md`**domain values**`\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":226,"value":" +d.trim())}]\"\n range='[\"#fee5d9\", \"#fcae91\", \"#fb6a4a\", \"#de2d26\", \"#a50f15\"]'\n/>","pinned":true,"hidden":false,"mode":"html"},{"id":240,"value":"### Categorical Legends\n\nCategorical legends may be rendered by setting the `scaleType` to \"categorical\". This assumes an equal number of values in both the `domain` and `range`. The type of mark used to symbolize each category may be set to one of \"circle\", \"rect\", or \"line\". The default mark is \"circle\".","pinned":false,"hidden":false,"mode":"md"},{"id":264,"value":"viewof markType = Inputs.radio([\"circle\", \"rect\", \"line\"], {\n label: md`**markType**`,\n value: \"circle\"\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":243,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":621,"value":"categories = [\n \"Agriculture\",\n \"Business services\",\n \"Construction\",\n \"Education and Health\",\n \"Finance\",\n \"Government\"\n]","pinned":false,"hidden":false,"mode":"ojs"},{"id":630,"value":"categoricalRange = [\n \"#4e79a7\",\n \"#f28e2c\",\n \"#e15759\",\n \"#76b7b2\",\n \"#59a14f\",\n \"#edc949\"\n]","pinned":false,"hidden":false,"mode":"ojs"},{"id":348,"value":"Currently the ${cle()} is limited to these four scale types: continuous, discrete, threshold, and categorical. In the future more will be added, for example log and power.","pinned":false,"hidden":false,"mode":"md"},{"id":344,"value":"### Styling with CSS\n\nThe ${cle()} styles are encapsulated using the [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM). Thus its styles will not bleed out to pollute the styles of neighboring DOM elements, nor will external / global CSS rules affect it. To prove it, try uncommenting the CSS rule below to see how the child elements of all ${cle()} instances in this notebook are not affected:","pinned":false,"hidden":false,"mode":"md"},{"id":770,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":776,"value":"So what if we need to customize the ${cle()}'s internal CSS? All is not lost! The default styles of the ${cle()} may be customized by overriding one or more of its [CSS variables (custom properties)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties). All CSS variables are prefixed with `cle`, for example `--cle-font-family` will set the `font-family` property for the title and axis ticks.\n\nHere is an example of overriding the ${cle()}'s default styles by overriding its CSS variables. Note that this must be done from within the `color-legend` CSS selector:","pinned":false,"hidden":false,"mode":"md"},{"id":407,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":411,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":755,"value":"Or for example, to change the number of columns and swatch size in a categorical legend:","pinned":false,"hidden":false,"mode":"md"},{"id":637,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":633,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":402,"value":"You may choose to hide the ${cle()} until it loads using the [`:defined`](https://developer.mozilla.org/en-US/docs/Web/CSS/:defined) pseudo class:\n\n```css\ncolor-legend-element:not(:defined) {\n display: none;\n}\n\ncolor-legend-element:defined {\n display: inline-block;\n}\n```","pinned":false,"hidden":false,"mode":"md"},{"id":441,"value":"

\n**Tip:** If you would like to learn more about styling Custom Elements that use the Shadow DOM, [Nolan Lawson](https://github.com/nolanlawson) has a [pretty good write up](https://nolanlawson.com/2021/01/03/options-for-styling-web-components/) about it.\n

","pinned":false,"hidden":false,"mode":"md"},{"id":851,"value":"## Rendering Child Content with Slots\n\nThe ${cle()} has two [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Slot)s which allow for rendering child content above and below where the legend's marks are drawn. The slots are named \"subtitle\" and \"footer\" accordingly.","pinned":false,"hidden":false,"mode":"md"},{"id":865,"value":"\n

A subtitle paragraph

Some footer text here

\n","pinned":true,"hidden":false,"mode":"html"},{"id":872,"value":"Beware that slotted elements are considered part of the \"Light DOM\" and may be influenced by external CSS:","pinned":false,"hidden":false,"mode":"md"},{"id":888,"value":"\n

A subtitle paragraph

Some footer here

\n","pinned":true,"hidden":false,"mode":"html"},{"id":884,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":456,"value":"## The End\n\nAnd that's a wrap! Please let me know what you think of the ${cle()} element and how you use it in your projects. You may submit issues and pull requests in the [Github Repository](https://github.com/clhenrick/color-legend-element/) as well. Thanks for reading!","pinned":false,"hidden":false,"mode":"md"},{"id":110,"value":"---","pinned":false,"hidden":false,"mode":"md"},{"id":798,"value":"## Boring Zone","pinned":false,"hidden":false,"mode":"md"},{"id":27,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":1045,"value":"defaultWidth = 325","pinned":true,"hidden":false,"mode":"ojs"},{"id":1025,"value":"version = \"1.3.0\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":19,"value":"// Require a module from a local webserver, credit: https://observablehq.com/@john-guerra/require-npm-module-from-local-file\nlocalUrl = `http://127.0.0.1:8080/assets/color-legend-element.umd.js?${Date.now()}`","pinned":true,"hidden":false,"mode":"ojs"},{"id":1001,"value":"prodUrl = `https://unpkg.com/color-legend-element@${version}`","pinned":true,"hidden":false,"mode":"ojs"},{"id":21,"value":"ColorLegendElement = require(prodUrl)","pinned":true,"hidden":false,"mode":"ojs"},{"id":122,"value":"cle = () => \"``\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":546,"value":"schemes = Object.keys(d3)\n .filter((key) => key.includes(\"scheme\"))\n .filter((key) => {\n for (let np of notPermitted) {\n if (key.toLowerCase().includes(np)) {\n return false;\n }\n }\n return true;\n })","pinned":false,"hidden":false,"mode":"ojs"},{"id":583,"value":"notPermitted = new Set([\n \"dark\",\n \"category\",\n \"accent\",\n \"pastel\",\n \"set\",\n \"tableau\"\n])","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W31","stdlib":"1","titling":"auto"}