diff --git a/site/examples/brush/App.svelte b/site/examples/brush/App.svelte index de47b9f8..2e888080 100755 --- a/site/examples/brush/App.svelte +++ b/site/examples/brush/App.svelte @@ -69,8 +69,8 @@ $: { let keys = Object.keys(selectedPoints) if (keys.length > 0) { - averageA = keys.map(key => data.row(key).a).reduce((a, b) => a + b) / keys.length - averageB = keys.map(key => data.row(key).b).reduce((a, b) => a + b) / keys.length + averageA = keys.map(key => data.row({ key }).a).reduce((a, b) => a + b) / keys.length + averageB = keys.map(key => data.row({ key }).b).reduce((a, b) => a + b) / keys.length } else { averageA = undefined averageB = undefined diff --git a/site/examples/candlestick/App.svelte b/site/examples/candlestick/App.svelte index 9133341b..e9713ebd 100755 --- a/site/examples/candlestick/App.svelte +++ b/site/examples/candlestick/App.svelte @@ -1,70 +1,81 @@ {#if ready} - - r[0] > r[1] ? '#da344d' : '#32936f') } /> - + - + + {/if} diff --git a/site/examples/choropleth-map/App.svelte b/site/examples/choropleth-map/App.svelte index 18edea2b..3f801706 100644 --- a/site/examples/choropleth-map/App.svelte +++ b/site/examples/choropleth-map/App.svelte @@ -5,18 +5,23 @@ } from '@snlab/florence' import DataContainer from '@snlab/florence-datacontainer' - const COLORS = ['#d3d3d3', '#fff0d2', '#FDD1A5', '#FD9243', '#982f05', '#4e1802'] + const COLORS = ['#fff0d2', '#FDD1A5', '#FD9243', '#982f05', '#4e1802'] let dataContainer, geoScales, priceColorScale, ready (async () => { const geojson = await json('/data/plan_areas_choropleth.json') - dataContainer = new DataContainer(geojson).dropNA('resale_price_sqm') - geoScales = createGeoScales(data.domain('$geometry')) + dataContainer = new DataContainer(geojson).mutate({ + resale_price_sqm: r => r.resale_price_sqm === null ? undefined : r.resale_price_sqm + }) + geoScales = createGeoScales(dataContainer.bbox()) - priceColorScale = dataContainer.classify({ - column: 'resale_price_sqm', method: 'Jenks', numClasses: COLORS.length - }, COLORS) + priceColorScale = dataContainer + .dropNA('resale_price_sqm') + .classify({ + column: 'resale_price_sqm', method: 'EqualInterval', numClasses: 5 + }, COLORS) + .unknown('#d3d3d3') ready = true })() @@ -24,7 +29,13 @@ {#if ready} - + </Graphic> diff --git a/site/examples/density-contours/App.svelte b/site/examples/density-contours/App.svelte index eead9151..3d095c75 100755 --- a/site/examples/density-contours/App.svelte +++ b/site/examples/density-contours/App.svelte @@ -1,20 +1,34 @@ <script> import { tsv } from 'd3-fetch' + import { autoType } from 'd3-dsv' import { contourDensity } from 'd3-contour' + import { scaleLinear } from 'd3-scale' import { format } from 'd3-format' - import { Graphic, PointLayer, PolygonLayer, XAxis, YAxis } from '@snlab/florence' + import { Graphic, PolygonLayer, PointLayer, XAxis, YAxis } from '@snlab/florence' import DataContainer from '@snlab/florence-datacontainer' const width = 500 const height = 500 - let dataContainer, contours, ready + let dataContainer, scaleX, scaleY, contours, ready (async () => { - const data = await tsv('/data/eruptions.tsv') - + const data = await tsv('/data/eruptions.tsv', autoType) dataContainer = new DataContainer(data) + + scaleX = scaleLinear() + .domain(dataContainer.domain('waiting')) + .nice() + .range([0, width]) + + scaleY = scaleLinear() + .domain(dataContainer.domain('eruptions')) + .nice() + .range([height, 0]) + contours = contourDensity() + .x(d => scaleX(d.waiting)) + .y(d => scaleY(d.eruptions)) .size([width, height]) .bandwidth(30) .thresholds(30)(data) @@ -25,12 +39,9 @@ {#if ready} - <Graphic - {width} - {height} + <Graphic + {width} {height} padding={{ top: 20, right: 30, bottom: 30, left: 40 }} - scaleX={dataContainer.domain('waiting')} - scaleY={dataContainer.domain('eruptions')} > <PolygonLayer @@ -41,14 +52,14 @@ /> <PointLayer - x={dataContainer.column('waiting')} - y={dataContainer.column('eruptions')} + x={dataContainer.map('waiting', scaleX)} + y={dataContainer.map('eruptions', scaleY)} radius={2} /> - <XAxis baseLine={false} /> - <YAxis baseLine={false} labelFormat={format('.1f')} /> + <XAxis scale={scaleX} baseLine={false} /> + <YAxis scale={scaleY} baseLine={false} labelFormat={format('.1f')} /> -</Graphic> + </Graphic> {/if} diff --git a/site/examples/gapminder/App.svelte b/site/examples/gapminder/App.svelte index 5442e7eb..6d640b70 100755 --- a/site/examples/gapminder/App.svelte +++ b/site/examples/gapminder/App.svelte @@ -24,7 +24,7 @@ .unknown('black') ready = true - }) + })() setInterval(() => { if (ready && currentYear < 2009) { diff --git a/site/examples/isotype/App.svelte b/site/examples/isotype/App.svelte index 14f4ea4e..2a4e7255 100755 --- a/site/examples/isotype/App.svelte +++ b/site/examples/isotype/App.svelte @@ -14,7 +14,7 @@ .padding(0.01) const colScale = scalePoint() - .domain(dataContainer.domain('col')) + .domain(Array(10).fill(0).map((_, i) => i + 1)) .padding(0.8) .round(true) diff --git a/site/examples/linked-views/App.svelte b/site/examples/linked-views/App.svelte index de182f9d..23d85151 100644 --- a/site/examples/linked-views/App.svelte +++ b/site/examples/linked-views/App.svelte @@ -1,6 +1,7 @@ <script> import { scaleBand } from 'd3-scale' import { json } from 'd3-fetch' + import { tick } from 'svelte' import { Graphic, Section, @@ -67,25 +68,25 @@ } function onMouseout({ key }) { - if (hoverKey) hoverKey = undefined + hoverKey = undefined heatmapData = undefined } </script> {#if ready} - <Graphic width={1000} height={800}> + <Graphic width={500} height={800}> <Section - x1={50} x2={475} - y1={50} y2={350} + y1={0} y2={400} {...geoScales} + padding={25} flipY > <PolygonLayer geometry={geoData.column('$geometry')} - keys={geoData.keys()} + key={geoData.keys()} fill={geoData.map('resale_price_sqm', priceColorScale)} fillOpacity={({ key }) => hoverKey === key ? 1 : 0.5} stroke={'white'} @@ -95,7 +96,7 @@ transition={1000} /> - <DiscreteLegend + <!-- <DiscreteLegend fill={priceColorScale} labelAnchorPoint={'r'} title={'Ave. Resale Price/m2 (S$)'} @@ -104,15 +105,14 @@ hjust={'right'} flipLabels usePadding={true} - /> + /> --> </Section> <Section - x1={50} x2={475} - y1={350} y2={650} - scaleY={yearScale} + y1={400} y2={800} scaleX={monthScale} + scaleY={yearScale} padding={50} > @@ -126,6 +126,9 @@ fill={heatmapData.map('resale_price_sqm', priceColorScale)} /> + <XAxis flip vjust={'top'} baseLineOpacity={0} yOffset={3}/> + <YAxis baseLineOpacity={0} xOffset={3}/> + {/if} <Title diff --git a/site/examples/population-pyramid/App.svelte b/site/examples/population-pyramid/App.svelte index 8085e92e..4e6ebcc2 100755 --- a/site/examples/population-pyramid/App.svelte +++ b/site/examples/population-pyramid/App.svelte @@ -1,7 +1,7 @@ <script> import { scaleLinear, scaleBand } from 'd3-scale' - import { Graphic, Section, RectangleLayer, XAxis, YAxis } from '@snlab/florence' import { formatPrefix } from 'd3-format' + import { Graphic, Section, RectangleLayer, XAxis, YAxis } from '@snlab/florence' import DataContainer from '@snlab/florence-datacontainer' import { data } from './population.js' diff --git a/site/examples/scatterplot-temp-trends/App.svelte b/site/examples/scatterplot-temp-trends/App.svelte index e27ae026..296e798e 100755 --- a/site/examples/scatterplot-temp-trends/App.svelte +++ b/site/examples/scatterplot-temp-trends/App.svelte @@ -21,13 +21,14 @@ valuesTo: 'value' }) .mutate({ - date: row => new Date(row.date, months.indexOf(row.month), 1), + date: row => new Date(+row.Year, months.indexOf(row.month), 1), value: row => +row.value }) - scaleColor = scaleSequential() - .domain(dataContainer.domain('value').reverse()) - .range(interpolateRdBu) + scaleColor = scaleSequential(interpolateRdBu).domain([ + dataContainer.max('value'), + dataContainer.min('value') + ]) ready = true })() diff --git a/site/examples/stacked-area/App.svelte b/site/examples/stacked-area/App.svelte index 3bf52858..9911979b 100755 --- a/site/examples/stacked-area/App.svelte +++ b/site/examples/stacked-area/App.svelte @@ -4,7 +4,7 @@ import { autoType } from 'd3-dsv' import { csv } from 'd3-fetch' import { Graphic, AreaLayer, XAxis, YAxis } from '@snlab/florence' - import DataContainer from '@snlab/florene-datacontainer' + import DataContainer from '@snlab/florence-datacontainer' let dataContainer, industries, scaleColor, ready diff --git a/site/examples/stacked-horizontal-bars/App.svelte b/site/examples/stacked-horizontal-bars/App.svelte index 0c328d3d..f4adcb8f 100755 --- a/site/examples/stacked-horizontal-bars/App.svelte +++ b/site/examples/stacked-horizontal-bars/App.svelte @@ -24,6 +24,8 @@ namesTo: 'ageGroup', valuesTo: 'countInterval' }) + .mutate({ upper: r => r.countInterval[1] }) + .arrange({ upper: 'descending' }) maxX = dataContainer.max('countInterval') @@ -38,27 +40,31 @@ })() </script> -<Graphic - width={500} - height={500} - scaleX={scaleLinear().domain([0, maxX])} - scaleY={scaleBand().domain(dataContainer.domain('state')).padding(0.1)} - padding={{ left: 30, right: 10, top: 30, bottom: 0 }} -> +{#if ready} - {#each dataContainer.rows() as stateGroup} + <Graphic + width={500} + height={500} + scaleX={scaleLinear().domain([0, maxX])} + scaleY={scaleBand().domain(dataContainer.domain('state')).padding(0.1)} + padding={{ left: 30, right: 10, top: 30, bottom: 0 }} + > - <RectangleLayer - x1={stateGroup.$grouped.map('countInterval', d => d[0])} - x2={stateGroup.$grouped.map('countInterval', d => d[1])} - y1={stateGroup.state} - y2={({ scaleY }) => scaleY(stateGroup.state) + scaleY.bandwidth()} - fill={stateGroup.$grouped.map('ageGroup', scaleColor)} - /> + {#each dataContainer.rows() as stateGroup} - {/each} + <RectangleLayer + x1={stateGroup.$grouped.map('countInterval', d => d[0])} + x2={stateGroup.$grouped.map('countInterval', d => d[1])} + y1={stateGroup.state} + y2={({ scaleY }) => scaleY(stateGroup.state) + scaleY.bandwidth()} + fill={stateGroup.$grouped.map('ageGroup', scaleColor)} + /> - <XAxis vjust={'top'} flip={true} baseLine={false} labelFormat={formatPrefix(",.0", 1e6)}/> - <YAxis baseLine={false} /> + {/each} -</Graphic> + <XAxis vjust={'top'} flip={true} baseLine={false} labelFormat={formatPrefix(",.0", 1e6)}/> + <YAxis baseLine={false} /> + + </Graphic> + +{/if} diff --git a/site/package-lock.json b/site/package-lock.json index 7adab67a..a8cdeaed 100644 --- a/site/package-lock.json +++ b/site/package-lock.json @@ -1239,7 +1239,7 @@ "@snlab/rendervous": { "version": "0.0.2", "resolved": "https://registry.npmjs.org/@snlab/rendervous/-/rendervous-0.0.2.tgz", - "integrity": "sha1-0ZD2NRJT5IKbzONHoN9vf5b7wUg=", + "integrity": "sha512-LebyG+mGLwYDnlRrxEd48datWqxrnHmmpUkn/9O1U/iso/xZibHhf5yaZdeBOJxc1ef7xZj2tflB6AhCUwneGQ==", "dev": true, "requires": { "d3-scale": "^3.2.1" @@ -1254,7 +1254,7 @@ "@snlab/transshape": { "version": "0.1.2", "resolved": "https://registry.npmjs.org/@snlab/transshape/-/transshape-0.1.2.tgz", - "integrity": "sha1-PwxQxWNzvpcs7MJ+TRHr65uGzic=", + "integrity": "sha512-+RYiw8s/UJ+2JaL8mfAp/PScAnEUBSxUSPXkSCvYOzpcqNSyglRzTMPi8Z1MQa5GMq7zLJgje1DvMyzhkw+YyA==", "dev": true, "requires": { "d3-array": "^2.4.0", @@ -2849,7 +2849,7 @@ "earcut": { "version": "2.2.2", "resolved": "https://registry.npmjs.org/earcut/-/earcut-2.2.2.tgz", - "integrity": "sha1-QbC8NfY+D+gNp83f8oUR5+LoDRE=", + "integrity": "sha512-eZoZPPJcUHnfRZ0PjLvx2qBordSiO8ofC3vt+qACLM95u+4DovnbYNpQtJh0DNsWj8RnxrQytD4WA8gj5cRIaQ==", "dev": true }, "electron-to-chromium": { @@ -6433,7 +6433,13 @@ "quickselect": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/quickselect/-/quickselect-2.0.0.tgz", - "integrity": "sha1-8ZaApIal7vtYEwPgI+mPqvJd0Bg=", + "integrity": "sha512-RKJ22hX8mHe3Y6wH/N3wCM6BWtjaxIyyUIkpHOvfFnxdI4yD4tBXEBKSbriGujF6jnSVkJrffuo6vxACiSSxIw==", + "dev": true + }, + "ramda": { + "version": "0.27.1", + "resolved": "https://registry.npmjs.org/ramda/-/ramda-0.27.1.tgz", + "integrity": "sha512-PgIdVpn5y5Yns8vqb8FzBUEYn98V3xcPgawAkkgj0YJ0qDsnHCiNmZYfOGMgOvoB0eWFLpYbhxUR3mxfDIMvpw==", "dev": true }, "ramda": { @@ -6454,7 +6460,7 @@ "rbush": { "version": "3.0.1", "resolved": "https://registry.npmjs.org/rbush/-/rbush-3.0.1.tgz", - "integrity": "sha1-X6+op5s7mv3+UAhAOnIMwd6ILs8=", + "integrity": "sha512-XRaVO0YecOpEuIvbhbpTrZgoiI6xBlz6hnlr6EHhd+0x9ase6EmeN+hdwwUaJvLcsFFQ8iWVF1GAK1yB0BWi0w==", "dev": true, "requires": { "quickselect": "^2.0.0" diff --git a/site/src/routes/docs/_content-structure.js b/site/src/routes/docs/_content-structure.js index 13a92298..3a8cb388 100644 --- a/site/src/routes/docs/_content-structure.js +++ b/site/src/routes/docs/_content-structure.js @@ -45,6 +45,10 @@ export const posts = [ { title: 'Transitions', path: '/docs/concepts/transitions' + }, + { + title: 'Advanced rendering', + path: '/docs/concepts/advanced-rendering' } ] }, @@ -101,6 +105,32 @@ export const posts = [ { title: 'Legend', path: '/docs/guides/legend' + }, + { + title: 'X-gridlines', + path: '/docs/guides/xgridlines' + }, + { + title: 'Y-gridlines', + path: '/docs/guides/ygridlines' + } + ] + }, + { + title: 'Helpers', + path: '/docs/helpers/create-geo-scales', + children: [ + { + title: 'createGeoScales', + path: '/docs/helpers/create-geo-scales' + }, + { + title: 'createPanHandler', + path: '/docs/helpers/create-pan-handler' + }, + { + title: 'createZoomHandler', + path: '/docs/helpers/create-zoom-handler' } ] } diff --git a/site/src/routes/docs/concepts/advanced-rendering.sveltex b/site/src/routes/docs/concepts/advanced-rendering.sveltex new file mode 100644 index 00000000..59583151 --- /dev/null +++ b/site/src/routes/docs/concepts/advanced-rendering.sveltex @@ -0,0 +1 @@ +# Advanced rendering diff --git a/site/src/routes/docs/concepts/examples/_Highlight.svelte b/site/src/routes/docs/concepts/examples/_Highlight.svelte index dc10cb40..241bb646 100644 --- a/site/src/routes/docs/concepts/examples/_Highlight.svelte +++ b/site/src/routes/docs/concepts/examples/_Highlight.svelte @@ -2,10 +2,10 @@ import { Graphic, Section, PointLayer } from '@snlab/florence' import { scaleLinear } from 'd3-scale' - let selectedKey = null + let selectedIndex = null - const x = [1, 3, 5, 3] - const y = [3, 1, 3, 5] + const a = [1, 3, 5, 3] + const b = [3, 1, 3, 5] const name = ['West', 'North', 'East', 'South'] </script> @@ -18,16 +18,16 @@ > <PointLayer - {x} - {y} + x={a} + y={b} radius={10} - fill={key => key === selectedKey ? 'red' : 'black' } - onMouseover={({ key }) => selectedKey = key} - onMouseout={() => selectedKey = null} + fill={({ index }) => index === selectedIndex ? 'red' : 'black' } + onMouseover={({ index }) => selectedIndex = index} + onMouseout={() => selectedIndex = null} /> </Section> </Graphic> -<h1 style="color: blue;">{selectedKey === null ? 'None selected' : name[selectedKey]}</h1> \ No newline at end of file +<h1 style="color: blue;">{selectedIndex === null ? 'None selected' : name[selectedIndex]}</h1> diff --git a/site/src/routes/docs/concepts/interactivity.sveltex b/site/src/routes/docs/concepts/interactivity.sveltex index 93641039..58e58274 100644 --- a/site/src/routes/docs/concepts/interactivity.sveltex +++ b/site/src/routes/docs/concepts/interactivity.sveltex @@ -1,7 +1,5 @@ # Interactivity -## Description - `florence` takes a different approach to interactivity than other data visualization libraries. Where libraries like [Vega Lite](https://vega.github.io/vega-lite/) or [G6](https://g6.antv.vision/) use a high-level 'grammar' specifically designed for interactivity, `florence` takes a more low-level approach. Instead of explaining to `florence` through a special language how an event (like a mouse click) should trigger an action (like a Mark changing color), `florence` relies on plain JavaScript combined with Svelte's built-in reactivity system as much as possible. Although this approach can result in more boilerplate code, it does provide more control and flexibility for the end user to create tailored and innovative interactions. At the same time, many tricky aspects of interactivity have been abstracted away, so you do not need to reinvent the wheel either! ## Caveats @@ -142,7 +140,7 @@ Highlighting is a technique that allows the end user to request additional infor import { Graphic, Section, PointLayer } from '@snlab/florence' import { scaleLinear } from 'd3-scale' -let selectedKey = null +let selectedIndex = null const a = [1, 3, 5, 3] const b = [3, 1, 3, 5] @@ -162,16 +160,16 @@ const name = ['West', 'North', 'East', 'South'] x={a} y={b} radius={10} - fill={key => key === selectedKey ? 'red' : 'black' } - onMouseover={({ key }) => selectedKey = key} - onMouseout={() => selectedKey = null} + fill={({ index }) => index === selectedIndex ? 'red' : 'black' } + onMouseover={({ index }) => selectedIndex = index} + onMouseout={() => selectedIndex = null} /> </Section> </Graphic> -<h1 style="color: blue;">{selectedKey === null ? 'None selected' : name[selectedKey]}</h1> +<h1 style="color: blue;">{selectedIndex === null ? 'None selected' : name[selectedIndex]}</h1> ``` ```js exec diff --git a/site/src/routes/docs/concepts/local-coordinates.sveltex b/site/src/routes/docs/concepts/local-coordinates.sveltex index 4b675213..1dafce12 100644 --- a/site/src/routes/docs/concepts/local-coordinates.sveltex +++ b/site/src/routes/docs/concepts/local-coordinates.sveltex @@ -1,25 +1,20 @@ # Local coordinates -## Description - -Understanding how local coordinates work is key to understanding `florence`. -The `Graphic` and `Section` components can create local coordinate systems, -and all other components are affected by local coordinate systems. +Understanding how local coordinates work is key to understanding `florence`. The `Graphic` and `Section` components can create local coordinate systems, and all other components are affected by local coordinate systems. ## Creating local coordinate systems -As stated above, local coordinate systems are created with the `Graphic` and `Section` -components. The following props are used to create local coordinate systems: +As stated above, local coordinate systems are created with the `Graphic` and `Section` components. The following props are used to create local coordinate systems: -| Prop | Type(s) | Required | Default | Units | -| -------------- | ------------------------------------------ | -------- | ------------ | ------------- | -| scaleX | [d3 scale](https://github.com/d3/d3-scale) | no | `undefined` | - | -| scaleY | [d3 scale](https://github.com/d3/d3-scale) | no | `undefined` | - | -| transformation | `String`: `'identity'` or `'polar'` | no | `'identity'` | - | -| flipX | `Boolean` | no | `false` | - | -| flipY | `Boolean` | no | `false` | - | -| padding | `Number`, `Object` | no | `undefined` | screen pixels | -| zoomIdentity | `Object` | no | `undefined` | - | +| Prop | Required | Type(s) | Default | Unit(s) | +| -------------- | -------- | ------------------ | ------------ | ------------------------------------------ | +| scaleX | `false` | `Function` | `undefined` | [d3 scale](https://github.com/d3/d3-scale) | +| scaleY | `false` | `Function` | `undefined` | [d3 scale](https://github.com/d3/d3-scale) | +| transformation | `false` | `String` | `'identity'` | Should be either `'identity'` or `'polar'` | +| flipX | `false` | `Boolean` | `false` | - | +| flipY | `false` | `Boolean` | `false` | - | +| padding | `false` | `Number`, `Object` | `undefined` | Pixel | +| zoomIdentity | `false` | `Object` | `undefined` | - | The purpose of a local coordinate system is to convert coordinates, given to components within a `Graphic` or `Section`, to pixel values that end up on your screen. All marks and layers have so-called 'positioning props'. Below is a schematic representation of how `florence` converts local coordinates to pixel values: @@ -30,7 +25,7 @@ The purpose of a local coordinate system is to convert coordinates, given to com The three main steps in this process are: 1. Scaling -2. Applying the coordinate transformation +2. Applying the coordinate transformation, if any 3. Applying the 'final' transformation, which encompasses padding, zooming and flipping. These three concepts will be explained in depth in the next paragraphs. @@ -41,7 +36,7 @@ These three concepts will be explained in depth in the next paragraphs. Scaling is the process of ["mapping a dimension of abstract data to a visual representation"](https://github.com/d3/d3-scale). In `florence`, this is not always true. The output of the scaling step is not necessarily the final 'visual representation' (a pixel value). If the user chooses to apply a coordinate transformation, the output of the scaling step goes through another step of processing. Or, if the user specifies the `padding`, `flipX`, `flipY` or `zoomIdentity` props, there will be another ('final') step before we obtain a pixel value. But for now, let's forget about coordinate transformations and things like padding and flipping, and look at how scaling works in isolation. -To scale coordinates in a local coordinate system, pass a [d3 scale](https://github.com/d3/d3-scale) to `scaleX` or `scaleY`. D3 scales are functions that map domains to ranges, where a domain is the 'abstract data dimension' and the range is the output dimension. In `florence`, the range will be taken care of for you, so you only need to define the domain. +To scale coordinates in a local coordinate system, pass a [d3 scale](https://github.com/d3/d3-scale) to `scaleX` or `scaleY`. D3 scales are functions that map domains to ranges, where a domain is the 'abstract data dimension' and the range is the output dimension- in this case, pixels on your screen. In `florence`, the range will be taken care of for you, so you only need to define the domain. Say that we have the following point: @@ -51,11 +46,11 @@ const point = { x: 5, y: 5 } And we want to position this point in the middle of the following `Graphic`: -```js -import { Graphic } from '@snlab/florence' ``` +<script> + import { Graphic } from '@snlab/florence' +</script> -``` <Graphic width={200} height={200} @@ -66,12 +61,12 @@ import { Graphic } from '@snlab/florence' If we want to use the point's original coordinates, we can position it in the center using d3's [scaleLinear](https://github.com/d3/d3-scale#scaleLinear). We will also give the `Graphic` a background color. This makes it easier to see that the `Point` is actually in the middle. -```js -import { Graphic, Point } from '@snlab/florence' -import { scaleLinear } from 'd3-scale' ``` +<script> + import { Graphic, Point } from '@snlab/florence' + import { scaleLinear } from 'd3-scale' +</script> -``` <Graphic width={200} height={200} @@ -104,15 +99,15 @@ Scaling can also be used to convert `String`s or `Date`s, as long as the correct import StringTemporal from './examples/_StringTemporal.svelte' ``` -```js -import { Graphic, Rectangle } from '@snlab/florence' -import { scalePoint, scaleTime } from 'd3-scale' - -const domainX = ['a', 'b', 'c', 'd', 'e'] -const domainY = [new Date(2020, 1, 1), new Date(2020, 1, 10)]) ``` +<script> + import { Graphic, Rectangle } from '@snlab/florence' + import { scalePoint, scaleTime } from 'd3-scale' + + const domainX = ['a', 'b', 'c', 'd', 'e'] + const domainY = [new Date(2020, 1, 1), new Date(2020, 1, 10)]) +</script> -``` <Graphic width={200} height={200} @@ -141,7 +136,7 @@ const domainY = [new Date(2020, 1, 1), new Date(2020, 1, 10)]) ### Domain shorthand -It is also possible to simply pass the domain to `scaleX` or `scaleY`. In this case, `florence` will create a linear scale from the domain. Therefore this: +It is also possible to simply pass a numeric domain to `scaleX` or `scaleY`. In this case, `florence` will create a linear scale from the domain. Therefore this: ``` <Graphic scaleX={[0, 10]}> @@ -162,17 +157,24 @@ import CenterPointFunc from './examples/_CenterPointFunc.svelte' ``` ``` -<Graphic +<script> + import { Graphic, Point, Rectangle } from '@snlab/florence' + import { scaleLinear } from 'd3-scale' + + const point = { x: 5, y: 5 } +</script> + +<Graphic width={200} height={200} scaleX={scaleLinear().domain([0, 10])} scaleY={scaleLinear().domain([0, 10])} - backgroundColor="#b2ffb2" + backgroundColor={'#b2ffb2'} > - <Point x={point.x} y={point.y} radius={20} fill="red" /> + <Point x={point.x} y={point.y} radius={20} fill={'red'} /> - <Point x={() => 100} y={() => 100} radius={10} fill="green" /> + <Point x={() => 100} y={() => 100} radius={10} fill={'green'} /> </Graphic> ``` @@ -187,11 +189,14 @@ Currently, the only supported coordinate transformation is `'polar'`. More trans import PolarShowcase from './examples/_PolarShowcase.svelte' ``` -```js -let transformation = 'identity' ``` +<script> + import { Graphic, Rectangle, LineLayer, LabelLayer } from '@snlab/florence' + + let flipY = false // set this to true to flip the coordinate system + let transformation = 'identity' +</script> -``` <div> <label for="coordinate-select">Coordinates:</label> <select name="coordinate-select" bind:value={transformation}> @@ -205,6 +210,7 @@ let transformation = 'identity' height={500} {transformation} backgroundColor="#b2ffb2" + {flipY} > <Rectangle fill="white" opacity={0.4} transition={2000} /> @@ -212,7 +218,7 @@ let transformation = 'identity' <LineLayer x={[[0, 0], [125, 125], [250, 250], [375, 375]]} y={[[0, 500], [0, 500], [0, 500], [0, 500]]} - stroke={lineStrokes} + stroke={["red", "orange", "yellow" , "green"]} transition={2000} /> @@ -239,6 +245,8 @@ import PolarScalingShowcase from './examples/_PolarScalingShowcase.svelte' ``` ``` +... + <Graphic width={500} height={500} @@ -284,6 +292,8 @@ import Flip from './examples/_Flip.svelte' ``` ``` +... + <Graphic width={200} height={200} @@ -298,6 +308,8 @@ import Flip from './examples/_Flip.svelte' With `flipX` and `flipY`, it is moved to the bottom right corner instead: ``` +... + <Graphic width={200} height={200} @@ -341,11 +353,11 @@ An example: import Padding from './examples/_Padding.svelte' ``` -```js -import { Graphic, Rectangle } from '@snlab/florence' ``` +<script> + import { Graphic, Rectangle } from '@snlab/florence' +</script> -``` <Graphic width={200} height={200} @@ -389,18 +401,18 @@ An example: import Zoom from './examples/_Zoom.svelte' ``` -```js -import { Graphic, Point, Label } from '@snlab/florence' - -const zoomIdentity = { - x: 50, - y: -50, - kx: 2, - ky: 2 -} ``` +<script> + import { Graphic, Point, Label } from '@snlab/florence' + + const zoomIdentity = { + x: 50, + y: -50, + kx: 2, + ky: 2 + } +</script> -``` <Graphic width={200} height={200} @@ -423,12 +435,12 @@ An example: import NestedSection from './examples/_NestedSection.svelte' ``` -```js -import { Graphic, Section, Point } from '@snlab/florence' -import { scaleLinear } from 'd3-scale' ``` +<script> + import { Graphic, Section, Point } from '@snlab/florence' + import { scaleLinear } from 'd3-scale' +</script> -``` <Graphic width={500} height={500} @@ -476,9 +488,7 @@ import { scaleLinear } from 'd3-scale' <NestedSection /> -## Examples - -### Scaling example +## Example This example will illustrate working with `String`s and d3's [scalePoint](https://github.com/d3/d3-scale#scalePoint). Let's say that a street artist has three favorite locations to play: the square, the park, and the mall. Every day she randomly picks a location where she plays all day, and at the end of the day she writes down the location and how much money she made. To have some insight in which locations yield the best results, she decides to visualize the data of the last 100 days, which is stored in two `Array`s: `location` and `money`. How would she accomplish this in `florence`? For this example, we will also use axes, to make the result a bit easier to interpret. @@ -486,16 +496,17 @@ This example will illustrate working with `String`s and d3's [scalePoint](https: import StreetArtist from './examples/_StreetArtist.svelte' ``` -```js -import { Graphic, PointLayer, XAxis, YAxis } from '@snlab/florence' -import { scaleLinear, scalePoint } from 'd3-scale' +``` +<script> + import { Graphic, PointLayer, XAxis, YAxis } from '@snlab/florence' + import { scaleLinear, scalePoint } from 'd3-scale' + import { getData } from './data.js' -const { location, money } = getData() + const { location, money } = getData() -const locations = ['square', 'park', 'mall'] -``` + const locations = ['square', 'park', 'mall'] +</script> -``` <Graphic width={200} height={200} diff --git a/site/src/routes/docs/concepts/marks-vs-layers.sveltex b/site/src/routes/docs/concepts/marks-vs-layers.sveltex index f3b8dcca..ab8969ca 100644 --- a/site/src/routes/docs/concepts/marks-vs-layers.sveltex +++ b/site/src/routes/docs/concepts/marks-vs-layers.sveltex @@ -1,3 +1,50 @@ # Marks versus Layers -TODO \ No newline at end of file +With the exception of the [FuncLine](/docs/marks/funcline), all `Mark`s have a corresponding `Layer` component. While the two are designed to be as similar as possible, there are some subtle differences between the two. This documentation will discuss these differences. + +## Keys + +The first difference between `Mark`s and `Layer`s is that the latter have a `key` prop, which the former lack: + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---- | -------- | ---------- | ----------- | -------------------- | +| key | `false` | `String[]` | `undefined` | Array of unique keys | + +TODO + +## Positioning: marks vs. layers + +### Values vs. arrays of values + +TODO: explain arrays of values + +### Recycling + +TODO: explain recycling + +### Function syntax + +TODO: explain function syntax + +## Aesthetics: marks vs. layers + +### Values vs. arrays of values + +TODO: explain arrays of values + +### Recycling + +TODO: explain recycling + +### Function syntax + +TODO: explain function syntax + +## Interactions + +The main differences between `Mark`s and `Layer`s in the area of interactivity are + +- TODO +- TODO + +For more information, consult the [interactivity](/docs/concepts/interactivity) documentation. diff --git a/site/src/routes/docs/concepts/transitions.sveltex b/site/src/routes/docs/concepts/transitions.sveltex index 1fa86c4d..c8f38fa6 100644 --- a/site/src/routes/docs/concepts/transitions.sveltex +++ b/site/src/routes/docs/concepts/transitions.sveltex @@ -1,8 +1,6 @@ # Transitions -## Description - -Every `Mark` and every `Layer` has a `transition` prop. TODO +All `Mark`s `Layer`s can transition automatically when the data on which they depend changes. The details of this transition can be tweaked with the `transition` prop. ## Basics @@ -93,7 +91,7 @@ function move () { ## Other aesthetic transitions -For other aesthetics, transitions basically work as you would expect. Here is a full list of all other supported aesthetics: +For other aesthetics, transitions basically work as you would expect. Other supported aesthetics are: - radius - opacity @@ -104,4 +102,4 @@ For other aesthetics, transitions basically work as you would expect. Here is a - strokeOpacity - fontSize - fontWeight -- rotation \ No newline at end of file +- rotation diff --git a/site/src/routes/docs/core/examples/_GraphicSimple.svelte b/site/src/routes/docs/core/examples/_GraphicSimple.svelte new file mode 100644 index 00000000..7f94c8fa --- /dev/null +++ b/site/src/routes/docs/core/examples/_GraphicSimple.svelte @@ -0,0 +1,7 @@ +<script> + import { Graphic } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} backgroundColor={'blue'}> + +</Graphic> diff --git a/site/src/routes/docs/core/examples/_GridSimple.svelte b/site/src/routes/docs/core/examples/_GridSimple.svelte index ef1e0eda..779185f0 100644 --- a/site/src/routes/docs/core/examples/_GridSimple.svelte +++ b/site/src/routes/docs/core/examples/_GridSimple.svelte @@ -5,9 +5,6 @@ let columns = 2 $: rows = Math.ceil(colors.length / columns) - - const width = 200 - const height = 200 </script> <div> @@ -15,17 +12,16 @@ <input type="range" min="1" max="3" bind:value={columns} name="cols-slider" /> </div> -<Graphic {width} {height}> - <Grid - {columns} - {rows} - areaNames={colors} - let:cells - > - {#each colors as color} - <Section {...cells[color]} backgroundColor={color}> - </Section> - {/each} +<Graphic width={200} height={200}> + + <Grid {columns} {rows} names={colors} let:cells> + + {#each colors as color} + + <Section {...cells[color]} backgroundColor={color}></Section> + + {/each} + </Grid> -</Graphic> +</Graphic> diff --git a/site/src/routes/docs/core/examples/_SectionSimple.svelte b/site/src/routes/docs/core/examples/_SectionSimple.svelte new file mode 100644 index 00000000..9766e417 --- /dev/null +++ b/site/src/routes/docs/core/examples/_SectionSimple.svelte @@ -0,0 +1,17 @@ +<script> + import { Graphic, Section } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} backgroundColor={'blue'}> + + <Section + x1={50} + x2={150} + y1={50} + y2={150} + backgroundColor={'green'} + > + + </Section> + +</Graphic> diff --git a/site/src/routes/docs/core/examples/_TitleSimple.svelte b/site/src/routes/docs/core/examples/_TitleSimple.svelte new file mode 100644 index 00000000..33808f78 --- /dev/null +++ b/site/src/routes/docs/core/examples/_TitleSimple.svelte @@ -0,0 +1,9 @@ +<script> + import { Graphic, Title } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} backgroundColor={'green'}> + + <Title title={'Hello world!'} /> + +</Graphic> diff --git a/site/src/routes/docs/core/examples/_ViewBoxSimple.svelte b/site/src/routes/docs/core/examples/_ViewBoxSimple.svelte new file mode 100644 index 00000000..22845ab8 --- /dev/null +++ b/site/src/routes/docs/core/examples/_ViewBoxSimple.svelte @@ -0,0 +1,14 @@ +<script> + import { Graphic, Point } from '@snlab/florence' +</script> + +<Graphic + width={'50%'} + height={'100%'} + viewBox={'0 0 100 100'} + backgroundColor={'#d3d3d3'} +> + + <Point x={50} y={50} radius={20} /> + +</Graphic> diff --git a/site/src/routes/docs/core/graphic.sveltex b/site/src/routes/docs/core/graphic.sveltex index be69e4bd..0d6ed6ca 100644 --- a/site/src/routes/docs/core/graphic.sveltex +++ b/site/src/routes/docs/core/graphic.sveltex @@ -1,59 +1,102 @@ # Graphic -```svelte -<Graphic width={500} height={500}> +Every `florence` graphic starts with the `Graphic` component. Think of +it as a supercharged `svg` root element. + +```markup +<script> + import { Graphic } from '@snlab/florence' +</script> - ... +<Graphic width={200} height={200} backgroundColor={'blue'}> </Graphic> ``` -## Description +```js exec +import SimpleExample from './examples/_GraphicSimple.svelte' +``` -Every `florence` graphic starts with the `Graphic` component. Think of -it as a supercharged `svg` root element. +<SimpleExample /> ## Caveats - `florence` components cannot be used outside of a `Graphic` component - `Graphic` components cannot be nested -## Props +## Properties ### Positioning -| Prop | Type(s) | Required | Default | Units | -| ------ | -------- | -------- | ------- | ------------- | -| width | `Number` | yes | - | screen pixels | -| height | `Number` | yes | - | screen pixels | +| Prop | Required | Type(s) | Default | Unit(s) | | | +| ------- | ------------------------------ | ------------------ | ---------------------------- | ----------------- | ----------- | ----------------------------------------------------------------------------------------- | +| width | `true` | `Number`, `String` | `500` | Pixel, percentage | | | +| height | `true` | `Number`, `String` | `500` | Pixel, percentage | | | +| viewBox | `if (typeof width === 'string' && typeof height === 'string')` | `String` | `undefined` | [viewBox coordinates](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox) | + +In most cases, the `Graphic` will be positioned by providing the `width` and `height` in pixels, like so: + +```markup +<Graphic width={800} height={600}> +``` + +However, in responsive layouts, it can be desirable to define the `Graphic`'s `width` and `height` in percentages relative to its parent element. In this case, the `viewBox` prop must be specified in [viewBox coordinates](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox), which will determine the `Graphic`'s local coordinate system. Note, however, that this changes all variables that are defined in pixels! The radius below, for example, is much larger than 20px (depending on your screen size): + +```markup +<script> + import { Graphic, Point } from '@snlab/florence' +</script> + +<Graphic + width={'50%'} + height={'100%'} + viewBox={'0 0 100 100'} + backgroundColor={'#d3d3d3'} +> + + <Point x={50} y={50} radius={20} /> + +</Graphic> +``` + +```js exec +import ViewBoxExample from './examples/_ViewBoxSimple.svelte' +``` + +<ViewBoxExample /> + +::: div callout +`width` and `height` must always be of the same type, so either both `Number` or both `String`. +::: -### Aesthetic props +### Aesthetics -| Prop | Type(s) | Required | Default | Units | -| --------------- | -------- | -------- | ----------- | ----------- | -| backgroundColor | `String` | no | `undefined` | Color value | -| paddingColor | `String` | no | `undefined` | Color value | +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | -------- | ----------- | ---------------------------- | +| backgroundColor | `false` | `String` | `undefined` | Named, hex, rgb or hsl color | +| paddingColor | `false` | `String` | `undefined` | Named, hex, rgb or hsl color | -Where `backgroundColor` is the area within the padded area, and `paddingColor` is the background of the padded area (see `padding` below). +`backgroundColor` is the area within the padded area, and `paddingColor` is the background of the padded area (see `padding` below). ### Local coordinate system -| Prop | Type(s) | Required | Default | Units | -| -------------- | ------------------------------------------ | -------- | ------------ | ------------- | -| scaleX | [d3 scale](https://github.com/d3/d3-scale) | no | `undefined` | - | -| scaleY | [d3 scale](https://github.com/d3/d3-scale) | no | `undefined` | - | -| transformation | `String`: `'identity'` or `'polar'` | no | `'identity'` | - | -| flipX | `Boolean` | no | `false` | - | -| flipY | `Boolean` | no | `false` | - | -| padding | `Number`, `Object` | no | `undefined` | screen pixels | -| zoomIdentity | `Object` | no | `undefined` | - | +| Prop | Required | Type(s) | Default | Unit(s) | +| -------------- | -------- | ------------------ | ------------ | ------------------------------------------ | +| scaleX | `false` | `Function` | `undefined` | [d3 scale](https://github.com/d3/d3-scale) | +| scaleY | `false` | `Function` | `undefined` | [d3 scale](https://github.com/d3/d3-scale) | +| transformation | `false` | `String` | `'identity'` | Should be either `'identity'` or `'polar'` | +| flipX | `false` | `Boolean` | `false` | - | +| flipY | `false` | `Boolean` | `false` | - | +| padding | `false` | `Number`, `Object` | `undefined` | Pixel | +| zoomIdentity | `false` | `Object` | `undefined` | - | For more how to use these props, see the [local coordinates](/docs/concepts/local-coordinates) documentation. ### Other -| Prop | Type(s) | Required | Default | Units | -| --------------- | --------- | -------- | ------- | ----- | -| blockReindexing | `Boolean` | no | `false` | - | +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | ------- | ------- | +| blockReindexing | `false` | `Boolean` | `false` | - | +| clip | `false` | `Boolean` | `true` | - | -The purpose of `blockReindexing` is explained in the [interactivity](/docs/concepts/interactivity) documentation. \ No newline at end of file +The purpose of `blockReindexing` is explained in the [interactivity](/docs/concepts/interactivity) documentation. `clip` indicates whether the marks or layers inside of this `Graphic` should be clipped off if they extends this `Graphic`'s viewport (i.e. the area within the padding). diff --git a/site/src/routes/docs/core/grid.sveltex b/site/src/routes/docs/core/grid.sveltex index 83e96754..fc9c4afa 100644 --- a/site/src/routes/docs/core/grid.sveltex +++ b/site/src/routes/docs/core/grid.sveltex @@ -1,78 +1,110 @@ # Grid -The Grid component is used to quickly position and align 'square' components in a grid format. 'Square' here refers to any component that has x1, x2, y1 and y2 props. This includes the Section component, the Rectangle mark, and any custom component that you would want to create, given it has the props mentioned above. -```js exec -import SimpleExample from './examples/_GridSimple.svelte' -``` -<SimpleExample /> +The Grid component is used to quickly position and align 'square' components in a grid format. 'Square' here refers to any component that has x1, x2, y1 and y2 props. This includes the Section component, the Rectangle mark, and any custom component that you would want to create, given it has the props mentioned above. ```markup <script> - const colors = ['red', 'blue', 'green', 'orange'] + import { Graphic, Section, Grid } from '@snlab/florence' + + const colors = ['red', 'blue', 'green', 'orange', 'yellow', 'purple'] + + let columns = 2 + $: rows = Math.ceil(colors.length / columns) </script> -<Graphic {width} {height}> - <Grid - {columns} - {rows} - names={colors} - let:cells - > - {#each colors as color} - <Section {...cells[color]} backGroundColor={color}> - </Section> - {/each} + +<div> + <label for="cols-slider">Columns:</label> + <input type="range" min="1" max="3" bind:value={columns} name="cols-slider" /> +</div> + +<Graphic width={200} height={200}> + + <Grid {columns} {rows} names={colors} let:cells> + + {#each colors as color} + + <Section {...cells[color]} backgroundColor={color}></Section> + + {/each} + </Grid> + </Graphic> ``` +```js exec +import SimpleExample from './examples/_GridSimple.svelte' +``` + +<SimpleExample /> + ## Properties + ### Positioning -| Prop | Type(s) | Required | Default | Units | -| ---- | --------------- | --------------- | ----------- | ----------------- | -| x1 | see Section | see Section | `undefined` | local coordinates | -| x2 | see Section | see Section | `undefined` | local coordinates | -| y1 | see Section | see Section | `undefined` | local coordinates | -| y2 | see Section | see Section | `undefined` | local coordinates | +| Prop | Required | Types | Default | Unit(s) | +| ---- | ----------------------- | -------------------------------------- | ----------- | ---------------------------------------------------- | +| x1 | `if (x2 !== undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| x2 | `if (x1 !== undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| y1 | `if (y2 !== undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| y2 | `if (y1 !== undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | -The `Grid` positioning props work the same way as the [Section](/docs/core/section) -positioning props. +The `Grid` positioning props behave the same way as the [Section](/docs/core/section) positioning props. ### Grid settings -| Prop | Type(s) | Required | Default | Units | Description | -| ---------------- | --------- | -------- | ------- | ------------- | ----------- | -| rows | `Number` | ✅ | `1` | Integer | Number of rows in grid | -| columns | `Number` | ✅ | `1` | Integer | Number of columns in grid | -| rowGap | `Number` | ✅ | `0` | Integer | Margin between rows | -| columnGap | `Number` | ✅ | `0` | Integer | Margin between columns | -| areaNames | []`String` | ✅ | [] | | An array of cell or facet names | +| Prop | Required | Type(s) | Default | Unit(s) | +| --------- | -------- | ---------- | ----------- | ------- | +| names | `true` | `String[]` | `undefined` | - | +| rows | `false` | `Number` | `undefined` | Integer | +| columns | `false` | `Number` | `undefined` | Integer | +| rowGap | `false` | `Number` | `0` | Pixel | +| columnGap | `false` | `Number` | `0` | Pixel | +`names` is the only required prop among the grid settings. If `rows` and `columns` are `undefined`, values will be chosen automatically based on the number of cells and the aspect ratio result from the positioning props. If only `rows` is defined, `columns` will be calculated automatically and vice versa. Finally, if both `rows` and `columns` are defined, the `Grid` component will give a warning if the number of `names` exceeds the number of cells. + +`rowGap` and `columnGap` are used to create spacing between the cells. ### Other -| Prop | Type(s) | Required | Default | Units | Description | -| ---------------- | --------- | -------- | ------- | ------------- | --------------------------------- | --------------------------------------------------------- | -| viewGridTemplate | `Boolean` | | `false` | | Option to console log grid layout -| viewGridShape | `Boolean` | | `false` | | Option to console log grid layout +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------------- | -------- | --------- | ------- | ------- | +| viewGridTemplate | `false` | `Boolean` | `false` | - | +| viewGridShape | `false` | `Boolean` | `false` | - | + +Setting either of these to `true` will `console.log` the grid template or shape whenever the data on which the `Grid` relies changes. This can be helpful when debugging the `Grid`. -### Slot Scope -Grid exposes value called `cells` using the `let:cells` syntax. The `cells` object holds a series of objects in which the key is the 'area name' element in `areaNames` array and the value is a position object that will be used to position the cells of the grid. This uses the [native Svelte slot syntax](https://svelte.dev/docs#slot_let). It is this `cells` object that can be used to position the children or cells of the Grid (i.e. `Section` components) in their corresponding cell. +## Slot Scope -```svelte +`Grid` exposes a value called `cells` through its slot scope using the `let:cells` syntax. The `cells` object holds a series of objects in which the key is the 'area name' element in `areas` array and the value is a position object that will be used to position the cells of the grid. This uses the [native Svelte slot syntax](https://svelte.dev/docs#slot_let). It is this `cells` object is used to position the `Grid` component's children that form the cells of the Grid (i.e. `Section` components). + +With the following prop values: + +```html +<Grid + names={['someName', 'anotherName']} + let:cells +> + + <!-- In here we have access to the cells object --> + +</Grid> +``` + +the `cells` object will look something like this: + +```js { - "plot-1":{ - x1, - y1, - x2, - y2 - }, - "plot-2":{ - x1, - y1, - x2, - y2 + someName: { + x1: <Number>, + y1: <Number>, + x2: <Number>, + y2: <Number> }, - .... + anotherName: { + x1: <Number>, + y1: <Number>, + x2: <Number>, + y2: <Number> + } } -``` \ No newline at end of file diff --git a/site/src/routes/docs/core/section.sveltex b/site/src/routes/docs/core/section.sveltex index f90f0588..3d86901a 100644 --- a/site/src/routes/docs/core/section.sveltex +++ b/site/src/routes/docs/core/section.sveltex @@ -1,23 +1,37 @@ # Section -```svelte -<Section> +The `Section` is one of the corner stones of `florence`. It is used to: - ... +- define local coordinate systems +- apply coordinate transformations +- specify zooming and panning behavior +- enable interactions -</Section> -``` +```markup +<script> + import { Graphic, Section } from '@snlab/florence' +</script> -___ +<Graphic width={200} height={200} backgroundColor={'blue'}> -## Description + <Section + x1={50} + x2={150} + y1={50} + y2={150} + backgroundColor={'green'} + > + + </Section> -The `Section` is one of the corner stones of `florence`. It can be used to: +</Graphic> +``` -- define local coordinate systems -- apply coordinate transformations -- specify zooming and panning behavior -- enable interactions +```js exec +import SimpleExample from './examples/_SectionSimple.svelte' +``` + +<SimpleExample /> ## Caveats @@ -28,16 +42,14 @@ The `Section` is one of the corner stones of `florence`. It can be used to: ### Positioning -| Prop | Type(s) | Required | Default | Units | -| ---- | --------------- | --------------- | ----------- | ----------------- | -| x1 | see explanation | see explanation | `undefined` | local coordinates | -| x2 | see explanation | see explanation | `undefined` | local coordinates | -| y1 | see explanation | see explanation | `undefined` | local coordinates | -| y2 | see explanation | see explanation | `undefined` | local coordinates | +| Prop | Required | Types | Default | Unit(s) | +| ---- | ----------------------- | -------------------------------------- | ----------- | ---------------------------------------------------- | +| x1 | `if (x2 !== undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| x2 | `if (x1 !== undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| y1 | `if (y2 !== undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| y2 | `if (y1 !== undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | -It is possible to use the `Section` without providing any of the positioning props. -This will result in the `Section` inheriting the extents of the parent `Section` or -`Graphic`, taking padding into account. For example, +It is possible to use the `Section` without providing any of the positioning props. This will result in the `Section` inheriting the extents of the parent `Section` or `Graphic`, taking padding into account. For example, ```svelte <Graphic width={500} height={500}> @@ -136,59 +148,69 @@ would be equivalent to: </Graphic> ``` -### Aesthetic props +### Aesthetics -| Prop | Type(s) | Required | Default | Units | -| --------------- | -------- | -------- | ----------- | ----------- | -| backgroundColor | `String` | no | `undefined` | Color value | -| paddingColor | `String` | no | `undefined` | Color value | +| Prop | Required | Type(s) | Default | Units | +| --------------- | -------- | -------- | ----------- | ---------------------------- | +| backgroundColor | `false` | `String` | `undefined` | Named, hex, rgb or hsl color | +| paddingColor | `false` | `String` | `undefined` | Named, hex, rgb or hsl color | Where `backgroundColor` is the area within the padded area, and `paddingColor` is the background of the padded area (see `padding` below). ### Local coordinate system -| Prop | Type(s) | Required | Default | Units | -| -------------- | ---------------------------------------------------- | -------- | ------------ | ------------- | -| scaleX | [d3 scale](https://github.com/d3/d3-scale) or domain | no | `undefined` | - | -| scaleY | [d3 scale](https://github.com/d3/d3-scale) or domain | no | `undefined` | - | -| transformation | `String`: `'identity'` or `'polar'` | no | `'identity'` | - | -| flipX | `Boolean` | no | `false` | - | -| flipY | `Boolean` | no | `false` | - | -| padding | `Number`, `Object` | no | `undefnied` | screen pixels | -| zoomIdentity | `Object` | no | `undefined` | - | +| Prop | Required | Type(s) | Default | Unit(s) | +| -------------- | -------- | ------------------ | ------------ | ------------------------------------------ | +| scaleX | `false` | `Function` | `undefined` | [d3 scale](https://github.com/d3/d3-scale) | +| scaleY | `false` | `Function` | `undefined` | [d3 scale](https://github.com/d3/d3-scale) | +| transformation | `false` | `String` | `'identity'` | Should be either `'identity'` or `'polar'` | +| flipX | `false` | `Boolean` | `false` | - | +| flipY | `false` | `Boolean` | `false` | - | +| padding | `false` | `Number`, `Object` | `undefined` | Pixel | +| zoomIdentity | `false` | `Object` | `undefined` | - | For more how to use these props, see the [local coordinates](/docs/concepts/local-coordinates) documentation. -### Other +### Interactions + +#### Mouse events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onClick | `false` | `Function` | `undefined` | - | +| onMousedown | `false` | `Function` | `undefined` | - | +| onMouseup | `false` | `Function` | `undefined` | - | +| onMouseover | `false` | `Function` | `undefined` | - | +| onMouseout | `false` | `Function` | `undefined` | - | +| onMousedrag | `false` | `Function` | `undefined` | - | -| Prop | Type(s) | Required | Default | Units | -| --------------- | --------- | -------- | ------- | ----- | -| blockReindexing | `Boolean` | no | `false` | - | +#### Touch events -The purpose of `blockReindexing` is explained in the [interactivity](/docs/concepts/interactivity) documentation. +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onTouchdown | `false` | `Function` | `undefined` | - | +| onTouchup | `false` | `Function` | `undefined` | - | +| onTouchover | `false` | `Function` | `undefined` | - | +| onTouchout | `false` | `Function` | `undefined` | - | +| onTouchdrag | `false` | `Function` | `undefined` | - | -### Mouse events +#### Select events -| Prop | Description | -| ----------- | --------------------------------------------------------------------------------------- | -| onClick | Fires when a user clicks anywhere in the `Section` | -| onWheel | Fires when a user uses a mouse wheel or two-finger touchpad zoom while over a `Section` | -| onMousedown | Fires when a user presses the mouse button down while over a `Section` | -| onMouseup | Fires when a user releases the mouse button while over a `Section` | -| onMouseover | Fires once when a user moves the mouse over a `Section` | -| onMouseout | Fires once when a user moves the mouse out of a `Section` | -| onMousemove | Fires every time the mouse moves while it is over a `Section` | +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ---------- | ----------- | ------- | +| onSelect | `false` | `Function` | `undefined` | - | +| onDeselect | `false` | `Function` | `undefined` | - | + +See the [interactivity](/docs/concepts/interactivity) documentation for more information. + +### Other -### Touch events +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | ------- | ------- | +| blockReindexing | `false` | `Boolean` | `false` | - | +| clip | `false` | `Boolean` | `true` | - | -| Prop | Description | -| ----------- | ---------------------------------------------------------------------- | -| onPinch | Fires when a user makes a 'pinch' gesture with two fingers | -| onTouchdown | Fires when a user touches the area in a `Section` | -| onTouchup | Fires when a user lifts his or her finger from the `Section` | -| onTouchover | Fires when a user moves his or her finger into the `Section` | -| onTouchout | Fires when a user moves his or her finger out of the `Section` | -| onTouchmove | Fires every time the user moves his or her finger within the `Section` | +The purpose of `blockReindexing` is explained in the [interactivity](/docs/concepts/interactivity) documentation. `clip` indicates whether the marks or layers inside of this `Graphic` should be clipped off if they extends this `Graphic`'s viewport (i.e. the area within the padding). ## Methods @@ -214,4 +236,4 @@ section.selectRectangle(...) </Section> ``` -For more information on `Section` methods and how to use them to create advanced interactions like selection or brushing, check out the [interactivity](/docs/concepts/interactivity) documentation. \ No newline at end of file +For more information on `Section` methods and how to use them to create advanced interactions like selection or brushing, check out the [interactivity](/docs/concepts/interactivity) documentation. diff --git a/site/src/routes/docs/core/title.sveltex b/site/src/routes/docs/core/title.sveltex index f43fc5a4..8172ea69 100644 --- a/site/src/routes/docs/core/title.sveltex +++ b/site/src/routes/docs/core/title.sveltex @@ -1,38 +1,76 @@ # Plot title -The `Title` component is used to create a plot title and has smart defaults for positioning and aesthetics/visual properties. - -```html - <Graphic> - <Title - ... - /> - - <Section> - <Title - ... - /> - </Section> - - </Graphic> + +The `Title` component is used to create titles and has smart defaults for positioning and aesthetics/visual properties. + +```markup +<script> + import { Graphic, Title } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} backgroundColor={'green'}> + + <Title title={'Hello world!'} /> + +</Graphic> ``` +```js exec +import SimpleExample from './examples/_TitleSimple.svelte' +``` + +<SimpleExample /> + ## Properties ### Positioning -| Prop | Type(s) | Description | Required | Default | Units | -|------------|----------------------|-------------|----------|-------------|---------------------------------------------------| -| x | `Number`, `Function` | Horizontal position of title | ✅ | `undefined` | local coordinates (`Number`), pixels (`Function`) | -| y | `Number`, `Function` | Vertical position of title | ✅ | `undefined` | local coordinates (`Number`), pixels (`Function`) | -| vjust | `String` | Vertical position of title | ❌ | `top` | `top`, `center`/`centre`, `bottom` | -| hjust | `String` | Horizontal orientation of the title relative to the chart. | ❌ | `center` | `left`, `center`/`centre`, `right` | -| xOffset | `String` | Offsets position of the title by pixel values | ❌ | `0` | pixels | -| yOffset | `String` | Offsets position of the title by pixel values | ❌ | `10` | pixels | -| usePadding | `Boolean` | Positions title either within parent Section/Graphic (`usePadding=false`) or within padding of parent (`usePadding=true`) | ❌ | `false` | boolean | -| subtitleX | `Number` | Horizontal position of subtitle | ❌ | `undefined` | pixels | -| subtitleY | `Number` | Vertical position of title | ❌ | `undefined` | pixels | + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | -------------------- | ----------- | ---------------------------------------------------- | +| x | `false` | `Number`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| y | `false` | `Number`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| vjust | `false` | `String` | `'top'` | See explanation` | +| hjust | `false` | `String` | `'center'` | See explanation | +| xOffset | `false` | `String` | `0` | Pixel | +| yOffset | `false` | `String` | `10` | Pixel | +| usePadding | `false` | `Boolean` | `false` | - | +| subtitleX | `false` | `Number` | `undefined` | Pixel | +| subtitleY | `false` | `Number` | `undefined` | Pixel | + + +| Prop | Type(s) | Required | Default | Units | +| ---------- | -------------------- | -------- | ----------- | ------------------------------------------------- | +| x | `Number`, `Function` | Horizontal position of title | ✅ | `undefined` | local coordinates (`Number`), pixels (`Function`) | +| y | `Number`, `Function` | Vertical position of title | ✅ | `undefined` | local coordinates (`Number`), pixels (`Function`) | +| vjust | `String` | Vertical position of title | ❌ | `top` | `top`, `center`/`centre`, `bottom` | +| hjust | `String` | Horizontal orientation of the title relative to the chart. | ❌ | `center` | `left`, `center`/`centre`, `right` | +| xOffset | `String` | Offsets position of the title by pixel values | ❌ | `0` | pixels | +| yOffset | `String` | Offsets position of the title by pixel values | ❌ | `10` | pixels | +| usePadding | `Boolean` | Positions title either within parent Section/Graphic (`usePadding=false`) or within padding of parent (`usePadding=true`) | ❌ | `false` | boolean | +| subtitleX | `Number` | Horizontal position of subtitle | ❌ | `undefined` | pixels | +| subtitleY | `Number` | Vertical position of title | ❌ | `undefined` | pixels | + + + ### Title +| Prop | Required | Type(s) | Default | Unit(s) | +| ------------------ | -------- | -------- | -------------- | ---------------------------- | +| title | `false` | `String` | `'Title Text'` | - | +| titleFill | `false` | `String` | `'black'` | Named, hex, rgb or hsl color | +| titleStroke | `false` | `String` | `undefined` | Named, hex, rgb or hsl color | +| titleStrokeWidth | `false` | `Number` | `undefined` | Pixel | +| titleStrokeOpacity | `false` | `Number` | `undefined` | Number between 0 and 1 | +| titleFillOpacity | `false` | `Number` | `undefined` | Number between 0 and 1 | +| titleOpacity | `false` | `Number` | `1` | Number between 0 and 1 | +| titleFontFamily | `false` | `String` | `'Helvetica'` | - | +| titleFontSize | `false` | `Number` | `18` | Pixel | +| titleFontWeight | `false` | `Number` | `'bold'` | - | +| titleRotation | `false` | `Number` | `0` | Degree | +| titleAnchorPoint | `false` | `Number` | `'center'` | See explanation | + + + | Prop | Type(s) | Description | Required | Default | Units | |--------------------|----------|-----------------------------------------------|----------|--------------|--------------------------------------------------------------------------------| | title | `String` | Title text | ✅ | `Title Text` | | @@ -49,7 +87,25 @@ The `Title` component is used to create a plot title and has smart defaults for | titleAnchorPoint | `Number` | Anchor point of text | ❌ | `center` | 'left', 'right', 'top', 'bottom', 'center', 'tl', 'tr', 'tc', 'bl', 'br', 'bc' | -### Subtitle +### Subtitle + +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------------- | -------- | -------- | ----------- | ---------------------------- | +| subtitle | `false` | `String` | '' | - | +| subtitleFill | `false` | `String` | `black` | Named, hex, rgb or hsl color | +| subtitleStroke | `false` | `Number` | `undefined` | Named, hex, rgb or hsl color | +| subtitleStrokeWidth | `false` | `Number` | `undefined` | Pixel | +| subtitleStrokeOpacity | `false` | `Number` | `undefined` | Number between 0 and 1 | +| subtitleFillOpacity | `false` | `Number` | `undefined` | Number between 0 and 1 | +| subtitleOpacity | `false` | `Number` | `1` | Number between 0 and 1 | +| subtitleFontFamily | `false` | `String` | `Helvetica` | - | +| subtitleFontSize | `false` | `Number` | `14` | Pixel | +| subtitleFontWeight | `false` | `Number` | `normal` | - | +| subtitleRotation | `false` | `Number` | `0` | Degree | +| subtitleAnchorPoint | `false` | `String` | `center` | See explanation | + + + | Prop | Type(s) | Description | Required | Default | Units | |-----------------------|----------|--------------------------------------------------------|----------|-------------|--------------------------------------------------------------------------------| | subtitle | `String` | Subtitle text | ❌ | '' | | @@ -64,5 +120,3 @@ The `Title` component is used to create a plot title and has smart defaults for | subtitleFontWeight | `Number` | Font weight of subtitle text | ❌ | `normal` | | | subtitleRotation | `Number` | Rotation angle of subtitle text | ❌ | `0` | degrees | | subtitleAnchorPoint | `String` | Anchor point of subtitle text | ❌ | `center` | 'left', 'right', 'top', 'bottom', 'center', 'tl', 'tr', 'tc', 'bl', 'br', 'bc' | - -## Examples diff --git a/site/src/routes/docs/guides/legend.sveltex b/site/src/routes/docs/guides/legend.sveltex index bed14657..6042a0cc 100644 --- a/site/src/routes/docs/guides/legend.sveltex +++ b/site/src/routes/docs/guides/legend.sveltex @@ -25,7 +25,7 @@ ## Description Legends are guides used to show mappings for aesthetics like color, shape, size, opacity to a given domain. Each legend is mapped to a single dimension or variable. Florence supports two types of legends that map values to color and/or opacity – gradient and discrete legends. -## Props +## Properties ### Positioning diff --git a/site/src/routes/docs/guides/utils/_XAxisSimple.svelte b/site/src/routes/docs/guides/utils/_XAxisSimple.svelte new file mode 100644 index 00000000..d74c1b57 --- /dev/null +++ b/site/src/routes/docs/guides/utils/_XAxisSimple.svelte @@ -0,0 +1,9 @@ +<script> + import { Graphic, XAxis } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} scaleX={[0, 10]} padding={20}> + + <XAxis /> + +</Graphic> diff --git a/site/src/routes/docs/guides/utils/_XGridLinesSimple.svelte b/site/src/routes/docs/guides/utils/_XGridLinesSimple.svelte new file mode 100644 index 00000000..559a5ca4 --- /dev/null +++ b/site/src/routes/docs/guides/utils/_XGridLinesSimple.svelte @@ -0,0 +1,10 @@ +<script> + import { Graphic, XAxis, XGridLines } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} scaleX={[0, 10]} padding={20}> + + <XAxis /> + <XGridLines /> + +</Graphic> diff --git a/site/src/routes/docs/guides/utils/_YAxisSimple.svelte b/site/src/routes/docs/guides/utils/_YAxisSimple.svelte new file mode 100644 index 00000000..4bae58f0 --- /dev/null +++ b/site/src/routes/docs/guides/utils/_YAxisSimple.svelte @@ -0,0 +1,9 @@ +<script> + import { Graphic, YAxis } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} scaleY={[0, 10]} padding={20}> + + <YAxis /> + +</Graphic> diff --git a/site/src/routes/docs/guides/utils/_YGridLinesSimple.svelte b/site/src/routes/docs/guides/utils/_YGridLinesSimple.svelte new file mode 100644 index 00000000..b69d65d5 --- /dev/null +++ b/site/src/routes/docs/guides/utils/_YGridLinesSimple.svelte @@ -0,0 +1,10 @@ +<script> + import { Graphic, YAxis, YGridLines } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} scaleY={[0, 10]} padding={20}> + + <YAxis /> + <YGridLines /> + +</Graphic> diff --git a/site/src/routes/docs/guides/xaxis.sveltex b/site/src/routes/docs/guides/xaxis.sveltex index 4736232d..0f44cddd 100644 --- a/site/src/routes/docs/guides/xaxis.sveltex +++ b/site/src/routes/docs/guides/xaxis.sveltex @@ -1,78 +1,125 @@ # X-axis -```html -<Graphic width={500} height={500}> +Component that creates an x-axis in reference to its parent `Graphic` or `Section`'s local coordinate system. + +```markup +<script> + import { Graphic, XAxis } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} scaleX={[0, 10]} padding={20}> <XAxis /> </Graphic> ``` -## Description +```js exec +import SimpleExample from './utils/_XAxisSimple.svelte' +``` -Component that creates an x-axis in reference to its parent `Graphic` or `Section`'s local coordinate system. +<SimpleExample /> -## Props +## Properties ### Positioning -| Prop | Type(s) | Required | Default | Units | -| ------- | ------------------ | -------- | ---------- | --------------- | -| vjust | `String`, `Number` | no | `'bottom'` | See explanation | -| yOffset | `Number` | no | `0` | Pixels | -| flip | `Boolean` | no | `false` | - | +| Prop | Required | Type(s) | Default | Unit(s) | +| ------- | -------- | ------------------ | ---------- | --------------- | +| vjust | `false` | `String`, `Number` | `'bottom'` | See explanation | +| yOffset | `false` | `Number` | `0` | Pixel | +| flip | `false` | `Boolean` | `false` | - | + +- `vjust` can either be a `String` with the one of the values `'top'`, `'bottom'`, or `'center'`, or a `Number` where `0` corresponds to `'top'`, `1` corresponds to `'bottom'`, and `0.5` to `'center'`. This is the main way to determine where in the `Section` the `XAxis` will be positioned. +- `yOffset` allows shifting the axis a few pixels up (when it is negative) or down (when it is positive) from where it has been positioned using `vjust`. +- setting `flip` to `true` will make the `ticks` and `labels` switch sides accross the axis. ### Baseline -| Prop | Type(s) | Required | Default | Units | -| --------------- | --------- | -------- | --------- | ---------------------- | -| baseLine | `Boolean` | no | `true` | - | -| baseLineColor | `String` | no | `'black'` | Color value | -| baseLineOpacity | `Number` | no | 1 | Number between 0 and 1 | -| baseLineWidth | `Number` | no | 1 | Pixels | +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | --------- | ---------------------------- | +| baseLine | `false` | `Boolean` | `true` | - | +| baseLineColor | `false` | `String` | `'black'` | Named, hex, rgb or hsl color | +| baseLineOpacity | `false` | `Number` | `1` | Number between 0 and 1 | +| baseLineWidth | `false` | `Number` | `1` | Pixel | -### Ticks +- setting `baseLine` to `false` will hide the horizontal axis line. +- the rest should be self-explanatory. -| Prop | Type(s) | Required | Default | Units | -| ----------- | ------------------------------------------ | -------- | ----------- | ---------------------- | -| scale | [d3 scale](https://github.com/d3/d3-scale) | no | `undefined` | - | -| ticks | `Boolean` | no | `true` | - | -| tickCount | `Number` | no | `10` | - | -| tickExtra | `Boolean` | no | `false` | - | -| tickValues | `Array` | no | `undefined` | Local coordinates | -| tickSize | `Number` | no | `5` | Pixels | -| tickWidth | `Number` | no | `0.5` | Pixels | -| tickColor | `String` | no | `'black'` | Color value | -| tickOpacity | `Number` | no | `1` | Number between 0 and 1 | +### Ticks -The `scale` prop can be used to override the parent's `scaleX`. +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ---------------------------------------------------- | +| scale | `false` | `Function` | `undefined` | [d3 scale](https://github.com/d3/d3-scale) | +| ticks | `false` | `Boolean` | `true` | - | +| tickCount | `false` | `Number` | `10` | - | +| tickExtra | `false` | `Boolean` | `false` | - | +| tickValues | `false` | `Array` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| tickSize | `false` | `Number` | `5` | Pixel | +| tickWidth | `false` | `Number` | `0.5` | Pixel | +| tickColor | `false` | `String` | `'black'` | Named, hex, rgb or hsl color | +| tickOpacity | `false` | `Number` | `1` | Number between 0 and 1 | + +- the `scale` prop can be used to override the parent's `scaleX`. +- setting `ticks` to `false` will hide the ticks. +- `tickCount` will determine the number of ticks. +- `tickExtra` will add an extra tick to mark the lower end of the domain. +- `tickValues` can be used to manually place ticks, and will override `tickCount` and `tickExtra`. +- `tickSize` refers to the length of the ticks. +- `tickWidth` refers to the line width of the ticks. +- `tickOpacity` refers to the opacity of the ticks. ### Tick labels -| Prop | Type(s) | Required | Default | Units | -| --------------- | ---------- | -------- | ------------- | ---------------------- | -| labelFormat | `Function` | no | `undefined` | - | -| labelOffset | `Number` | no | `2` | Pixels | -| labelRotate | `Number` | no | `0` | Degrees | -| labelFont | `String` | no | `'Helvetica'` | Font | -| labelFontSize | `Number` | no | `10` | Pixels | -| labelFontWeight | `String` | no | `'normal'` | See explanation | -| labelOpacity | `Number` | no | `1` | Number between 0 and 1 | -| labelColor | `String` | no | `'black'` | Color value | +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | ---------- | ------------- | ----------------------------------- | +| labelFormat | `false` | `Function` | `undefined` | - | +| labelOffset | `false` | `Number` | `2` | Pixel | +| labelRotate | `false` | `Number` | `0` | Degree | +| labelFont | `false` | `String` | `'Helvetica'` | Font | +| labelFontSize | `false` | `Number` | `10` | Pixel | +| labelFontWeight | `false` | `String` | `'normal'` | See [Label](/docs/marks/label) Mark | +| labelOpacity | `false` | `Number` | `1` | Number between 0 and 1 | +| labelColor | `false` | `String` | `'black'` | Named, hex, rgb or hsl color | + +- `labelFormat` is a `Function` that receives a tick value, and can return a formatted tick value (for example, passing `Math.floor` to `labelFormat` in a numeric domain will coerce all tick values into integers). +- `labelOffset` allows shifting the labels a few pixels up (negative) or down (positive). +- `labelRotate` allows rotating the tick labels. This can be useful when the tick labels are close together. +- the rest should be self-explanatory. ### Title -| Prop | Type(s) | Required | Default | Units | -| ---------------- | ------------------ | -------- | ------------- | ---------------------- | -| titleHjust | `String`, `Number` | no | `'center'` | See explanation | -| titleXOffset | `Number` | no | `0` | Pixels | -| titleVjust | `String`, `Number` | no | `'axis'` | See explanation | -| titleYOffset | `String`, `Number` | no | `'axis'` | See explanation | -| title | `String` | no | `''` | - | -| titleColor | `String` | no | `'black'` | Color value | -| titleFont | `String` | no | `'Helvetica'` | Font | -| titleFontSize | `Number` | no | `12` | Pixels | -| titleFontWeight | `String` | no | `'normal'` | See explanation | -| titleOpacity | `Number` | no | `1` | Number between 0 and 1 | -| titleRotation | `Number` | no | `0` | Degrees | -| titleAnchorPoint | `String` | no | `'t'` | See explanation | +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------------- | -------- | ------------------ | ------------- | ----------------------------------- | +| titleHjust | `false` | `String`, `Number` | `'center'` | See explanation | +| titleXOffset | `false` | `Number` | `0` | Pixel | +| titleVjust | `false` | `String`, `Number` | `'axis'` | See explanation | +| titleYOffset | `false` | `String`, `Number` | `'axis'` | See explanation | +| titleAnchorPoint | `false` | `String` | `'t'` | See [Label](/docs/marks/label) Mark | +| title | `false` | `String` | `''` | - | +| titleColor | `false` | `String` | `'black'` | Named, hex, rgb or hsl color | +| titleFont | `false` | `String` | `'Helvetica'` | Font | +| titleFontSize | `false` | `Number` | `12` | Pixel | +| titleFontWeight | `false` | `String` | `'normal'` | See explanation | +| titleOpacity | `false` | `Number` | `1` | Number between 0 and 1 | +| titleRotation | `false` | `Number` | `0` | Degree | + +`titleHjust`, `titleXOffset`, `titleVjust` and `titleYOffset` can be used to position the axis title similar to the `XAxis`'s `vjust` and `yOffset` props. The `titleVjust` and `titleYOffset` props, however, also allow a `String` with the value `'axis'`, which automatically places the title in a reasonable default position. For an explanation of `titleAnchorPoint`, see the `anchorPoint` explanation in the [Label](/docs/marks/label) Mark documentation. + +The rest should be self-explanatory. + +### Transitions + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ------------------ | ----------- | -------------------------------- | +| transition | `false` | `Number`, `Object` | `undefined` | Duration in ms or options object | + +Transitions will be applied to the marks (`Line`s and `Label`s) of which the axis consists. See the [transition](/docs/concepts/transitions) documentation for more information. + +### Other + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---- | -------- | --------- | ------- | ------- | +| clip | `false` | `Boolean` | `false` | - | + +Setting this to `true` will let the parent `Graphic` or `Section` clip off the axis if it leaves the viewport. Usually not desirable for axes. diff --git a/site/src/routes/docs/guides/xgridlines.sveltex b/site/src/routes/docs/guides/xgridlines.sveltex new file mode 100644 index 00000000..7c5c0464 --- /dev/null +++ b/site/src/routes/docs/guides/xgridlines.sveltex @@ -0,0 +1,36 @@ +# X-gridlines + +Component that creates grid lines extending the ticks of the [x-axis](/docs/guides/xaxis). + +```markup +<script> + import { Graphic, XAxis, XGridLines } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} scaleX={[0, 10]} padding={20}> + + <XAxis /> + <XGridLines /> + +</Graphic> +``` + +```js exec +import SimpleExample from './utils/_XGridLinesSimple.svelte' +``` + +<SimpleExample /> + +## Properties + +| Prop | Required | Type(s) | Default | Unit(s) | +| ------- | -------- | ---------- | ----------- | ---------------------------------------------------- | +| scale | `false` | `Function` | `undefined` | [d3 scale](https://github.com/d3/d3-scale) | +| count | `false` | `Number` | `10` | - | +| extra | `false` | `Boolean` | `false` | - | +| values | `false` | `Array` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| width | `false` | `Number` | `0.25` | Pixel | +| color | `false` | `String` | `'black'` | Named, hex, rgb or hsl color | +| opacity | `false` | `Number` | `1` | Number between 0 and 1 | + +These properties mirror the 'ticks' properties of the [XAxis](/docs/guides/xaxis). diff --git a/site/src/routes/docs/guides/yaxis.sveltex b/site/src/routes/docs/guides/yaxis.sveltex index 8ab48bf6..db889986 100644 --- a/site/src/routes/docs/guides/yaxis.sveltex +++ b/site/src/routes/docs/guides/yaxis.sveltex @@ -1,78 +1,125 @@ # Y-axis -```html -<Graphic width={500} height={500}> +Component that creates an y-axis in reference to its parent `Graphic` or `Section`'s local coordinate system. + +```markup +<script> + import { Graphic, YAxis } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} scaleY={[0, 10]} padding={20}> <YAxis /> </Graphic> ``` -## Description +```js exec +import SimpleExample from './utils/_YAxisSimple.svelte' +``` -Component that creates an y-axis in reference to its parent `Graphic` or `Section`'s local coordinate system. +<SimpleExample /> -## Props +## Properties ### Positioning -| Prop | Type(s) | Required | Default | Units | -| ------- | ------------------ | -------- | ---------- | --------------- | -| hjust | `String`, `Number` | no | `'bottom'` | See explanation | -| xOffset | `Number` | no | `0` | Pixels | -| flip | `Boolean` | no | `false` | - | +| Prop | Required | Type(s) | Default | Unit(s) | +| ------- | -------- | ------------------ | -------- | --------------- | +| hjust | `false` | `String`, `Number` | `'left'` | See explanation | +| xOffset | `false` | `Number` | `0` | Pixel | +| flip | `false` | `Boolean` | `false` | - | + +- `hjust` can either be a `String` with the one of the values `'left'`, `'right'`, or `'center'`, or a `Number` where `0` corresponds to `'left'`, `1` corresponds to `'right'`, and `0.5` to `'center'`. This is the main way to determine where in the `Section` the `YAxis` will be positioned. +- `xOffset` allows shifting the axis a few pixels right (when it is negative) or left (when it is positive) from where it has been positioned using `hjust`. +- setting `flip` to `true` will make the `ticks` and `labels` switch sides accross the axis. ### Baseline -| Prop | Type(s) | Required | Default | Units | -| --------------- | --------- | -------- | --------- | ---------------------- | -| baseLine | `Boolean` | no | `true` | - | -| baseLineColor | `String` | no | `'black'` | Color value | -| baseLineOpacity | `Number` | no | 1 | Number between 0 and 1 | -| baseLineWidth | `Number` | no | 1 | Pixels | +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | --------- | ---------------------------- | +| baseLine | `false` | `Boolean` | `true` | - | +| baseLineColor | `false` | `String` | `'black'` | Named, hex, rgb or hsl color | +| baseLineOpacity | `false` | `Number` | `1` | Number between 0 and 1 | +| baseLineWidth | `false` | `Number` | `1` | Pixel | -### Ticks +- setting `baseLine` to `false` will hide the horizontal axis line. +- the rest should be self-explanatory. -| Prop | Type(s) | Required | Default | Units | -| ----------- | ------------------------------------------ | -------- | ----------- | ---------------------- | -| scale | [d3 scale](https://github.com/d3/d3-scale) | no | `undefined` | - | -| ticks | `Boolean` | no | `true` | - | -| tickCount | `Number` | no | `10` | - | -| tickExtra | `Boolean` | no | `false` | - | -| tickValues | `Array` | no | `undefined` | Local coordinates | -| tickSize | `Number` | no | `5` | Pixels | -| tickWidth | `Number` | no | `0.5` | Pixels | -| tickColor | `String` | no | `'black'` | Color value | -| tickOpacity | `Number` | no | `1` | Number between 0 and 1 | +### Ticks -The `scale` prop can be used to override the parent's `scaleY`. +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ---------------------------------------------------- | +| scale | `false` | `Function` | `undefined` | [d3 scale](https://github.com/d3/d3-scale) | +| ticks | `false` | `Boolean` | `true` | - | +| tickCount | `false` | `Number` | `10` | - | +| tickExtra | `false` | `Boolean` | `false` | - | +| tickValues | `false` | `Array` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| tickSize | `false` | `Number` | `5` | Pixel | +| tickWidth | `false` | `Number` | `0.5` | Pixel | +| tickColor | `false` | `String` | `'black'` | Named, hex, rgb or hsl color | +| tickOpacity | `false` | `Number` | `1` | Number between 0 and 1 | + +- the `scale` prop can be used to override the parent's `scaleY`. +- setting `ticks` to `false` will hide the ticks. +- `tickCount` will determine the number of ticks. +- `tickExtra` will add an extra tick to mark the lower end of the domain. +- `tickValues` can be used to manually place ticks, and will override `tickCount` and `tickExtra`. +- `tickSize` refers to the length of the ticks. +- `tickWidth` refers to the line width of the ticks. +- `tickOpacity` refers to the opacity of the ticks. ### Tick labels -| Prop | Type(s) | Required | Default | Units | -| --------------- | ---------- | -------- | ------------- | ---------------------- | -| labelFormat | `Function` | no | `undefined` | - | -| labelOffset | `Number` | no | `2` | Pixels | -| labelRotate | `Number` | no | `0` | Degrees | -| labelFont | `String` | no | `'Helvetica'` | Font | -| labelFontSize | `Number` | no | `10` | Pixels | -| labelFontWeight | `String` | no | `'normal'` | See explanation | -| labelOpacity | `Number` | no | `1` | Number between 0 and 1 | -| labelColor | `String` | no | `'black'` | Color value | +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | ---------- | ------------- | ----------------------------------- | +| labelFormat | `false` | `Function` | `undefined` | - | +| labelOffset | `false` | `Number` | `2` | Pixel | +| labelRotate | `false` | `Number` | `0` | Degree | +| labelFont | `false` | `String` | `'Helvetica'` | Font | +| labelFontSize | `false` | `Number` | `10` | Pixel | +| labelFontWeight | `false` | `String` | `'normal'` | See [Label](/docs/marks/label) Mark | +| labelOpacity | `false` | `Number` | `1` | Number between 0 and 1 | +| labelColor | `false` | `String` | `'black'` | Named, hex, rgb or hsl color | + +- `labelFormat` is a `Function` that receives a tick value, and can return a formatted tick value (for example, passing `Math.floor` to `labelFormat` in a numeric domain will coerce all tick values into integers). +- `labelOffset` allows shifting the labels a few pixels up (negative) or down (positive). +- `labelRotate` allows rotating the tick labels. This can be useful when the tick labels are close together. +- the rest should be self-explanatory. ### Title -| Prop | Type(s) | Required | Default | Units | -| ---------------- | ------------------ | -------- | ------------- | ---------------------- | -| titleHjust | `String`, `Number` | no | `'axis'` | See explanation | -| titleXOffset | `Number` | no | `'axis'` | Pixels | -| titleVjust | `String`, `Number` | no | `'center'` | See explanation | -| titleYOffset | `String`, `Number` | no | `0` | See explanation | -| title | `String` | no | `''` | - | -| titleColor | `String` | no | `'black'` | Color value | -| titleFont | `String` | no | `'Helvetica'` | Font | -| titleFontSize | `Number` | no | `12` | Pixels | -| titleFontWeight | `String` | no | `'normal'` | See explanation | -| titleOpacity | `Number` | no | `1` | Number between 0 and 1 | -| titleRotation | `Number` | no | `-90` | Degrees | -| titleAnchorPoint | `String` | no | `'center'` | See explanation | +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------------- | -------- | ------------------ | ------------- | ---------------------------- | +| titleVjust | `false` | `String`, `Number` | `'center'` | See explanation | +| titleYOffset | `false` | `Number` | `0` | Pixel | +| titleHjust | `false` | `String`, `Number` | `'axis'` | See explanation | +| titleXOffset | `false` | `String`, `Number` | `'axis'` | See explanation | +| title | `false` | `String` | `''` | - | +| titleColor | `false` | `String` | `'black'` | Named, hex, rgb or hsl color | +| titleFont | `false` | `String` | `'Helvetica'` | Font | +| titleFontSize | `false` | `Number` | `12` | Pixel | +| titleFontWeight | `false` | `String` | `'normal'` | See explanation | +| titleOpacity | `false` | `Number` | `1` | Number between 0 and 1 | +| titleRotation | `false` | `Number` | `0` | Degree | +| titleAnchorPoint | `false` | `String` | `'t'` | See explanation | + +`titleVjust`, `titleYOffset`, `titleHjust` and `titleXOffset` can be used to position the axis title similar to the `YAxis`'s `hjust` and `xOffset` props. The `titleHjust` and `titleXOffset` props, however, also allow a `String` with the value `'axis'`, which automatically places the title in a reasonable default position. For an explanation of `titleAnchorPoint`, see the `anchorPoint` explanation in the [Label](/docs/marks/label) Mark documentation. + +The rest should be self-explanatory. + +### Transitions + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ------------------ | ----------- | -------------------------------- | +| transition | `false` | `Number`, `Object` | `undefined` | Duration in ms or options object | + +Transitions will be applied to the marks (`Line`s and `Label`s) of which the axis consists. See the [transition](/docs/concepts/transitions) documentation for more information. + +### Other + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---- | -------- | --------- | ------- | ------- | +| clip | `false` | `Boolean` | `false` | - | + +Setting this to `true` will let the parent `Graphic` or `Section` clip off the axis if it leaves the viewport. Usually not desirable for axes. diff --git a/site/src/routes/docs/guides/ygridlines.sveltex b/site/src/routes/docs/guides/ygridlines.sveltex new file mode 100644 index 00000000..34d1fb10 --- /dev/null +++ b/site/src/routes/docs/guides/ygridlines.sveltex @@ -0,0 +1,36 @@ +# Y-gridlines + +Component that creates grid lines extending the ticks of the [y-axis](/docs/guides/yaxis). + +```markup +<script> + import { Graphic, YAxis, YGridLines } from '@snlab/florence' +</script> + +<Graphic width={200} height={200} scaleY={[0, 10]} padding={20}> + + <YAxis /> + <YGridLines /> + +</Graphic> +``` + +```js exec +import SimpleExample from './utils/_YGridLinesSimple.svelte' +``` + +<SimpleExample /> + +## Properties + +| Prop | Required | Type(s) | Default | Unit(s) | +| ------- | -------- | ---------- | ----------- | ---------------------------------------------------- | +| scale | `false` | `Function` | `undefined` | [d3 scale](https://github.com/d3/d3-scale) | +| count | `false` | `Number` | `10` | - | +| extra | `false` | `Boolean` | `false` | - | +| values | `false` | `Array` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | +| width | `false` | `Number` | `0.25` | Pixel | +| color | `false` | `String` | `'black'` | Named, hex, rgb or hsl color | +| opacity | `false` | `Number` | `1` | Number between 0 and 1 | + +These properties mirror the 'ticks' properties of the [YAxis](/docs/guides/xaxis). diff --git a/site/src/routes/docs/helpers/create-geo-scales.sveltex b/site/src/routes/docs/helpers/create-geo-scales.sveltex new file mode 100644 index 00000000..5611125a --- /dev/null +++ b/site/src/routes/docs/helpers/create-geo-scales.sveltex @@ -0,0 +1,76 @@ +# createGeoScales + +Helper function for creating linear scales that maintain the aspect ratio of x and y domains. The main usecase for this is when creating maps. + +```markup +<script> + import { Graphic, Section, Rectangle, createGeoScales } from '@snlab/florence' + import { scaleLinear } from 'd3-scale' + + const domains = { + x: [2.5, 7.5], + y: [0, 10] + } + + const regularScales = { + scaleX: scaleLinear().domain(domains.x), + scaleY: scaleLinear().domain(domains.y) + } + + const geoScales = createGeoScales(domains) +</script> + +<Graphic width={400} height={200}> + + <Section + x1={0} + x2={200} + {...regularScales} + padding={20} + backgroundColor={'#d3d3d3'} + > + <Rectangle x1={2.5} x2={7.5} y1={0} y2={10} fill={'red'} /> + </Section> + + <Section + x1={200} + x2={400} + {...geoScales} + padding={20} + backgroundColor={'#d3d3d3'} + > + <Rectangle x1={2.5} x2={7.5} y1={0} y2={10} fill={'blue'} /> + </Section> + +</Graphic> +``` + +```js exec +import BasicExample from './examples/_GeoBasic.svelte' +``` + +<BasicExample /> + +## Arguments + + +| Argument | Required | Type(s) | Default | Unit(s) | +| -------- | -------- | ---------- | ----------- | --------------- | +| bbox | `true` | `Object` | `undefined` | See explanation | +| bbox.x | `true` | `Number[]` | `undefined` | See explanation | +| bbox.y | `true` | `Number[]` | `undefined` | See explanation | + +`bbox` is an Object with two members `x` and `y`, which are both `Array`s containing two numbers: + +```js +const bbox = { + x: [<Number>, <Number>], + y: [<Number>, <Number>] +} +``` + +The `x` and `y` members represent the domains of the variables that will be used as x and y dimensions. + +## Return value + +TODO \ No newline at end of file diff --git a/site/src/routes/docs/helpers/create-pan-handler.sveltex b/site/src/routes/docs/helpers/create-pan-handler.sveltex new file mode 100644 index 00000000..6c27a9ba --- /dev/null +++ b/site/src/routes/docs/helpers/create-pan-handler.sveltex @@ -0,0 +1,108 @@ +# createPanHandler + +Helper function to set up panning behavior on `Section`s. + +```markup +<script> + import { + Graphic, Section, Rectangle, XAxis, YAxis, createPanHandler + } from '@snlab/florence' + + let zoomIdentity = { x: 0, y: 0, kx: 1, ky: 1 } + let blockReindexing = false + + const setZoomIdentity = zoomId => { zoomIdentity = zoomId } + const setBlockReindexing = bool => { blockReindexing = bool } + + const pan = createPanHandler(zoomIdentity, { + setZoomIdentity, + setBlockReindexing, + extentX: [-100, 100], + extentY: [-100, 100] + }) +</script> + +<Graphic width={200} height={200} padding={20}> + + <Section + scaleX={[0, 10]} + scaleY={[0, 10]} + {zoomIdentity} + {...pan.handlers} + {blockReindexing} + > + + <Rectangle x1={2.5} x2={7.5} y1={2.5} y2={7.5} /> + + <XAxis /> + <YAxis /> + + </Section> + +</Graphic> +``` + +```js exec +import SimpleExample from './examples/_PanExample.svelte' +``` + +<SimpleExample /> + +## Arguments + +| Argument | Required | Type(s) | Default | Unit(s) | +| ------------------------------ | -------- | ---------- | ----------------------- | ------------------------ | +| zoomIdentity | `true` | `Object` | `undefined` | See explanation | +| panSettings | `true` | `Object` | `undefined` | See explanation | +| panSettings.setZoomIdentity | `true` | `Function` | `undefined` | See explanation | +| panSettings.setBlockReindexing | `false` | `Function` | `() => {}` | See explanation | +| panSettings.dimension | `false` | `String` | `'both'` | `'x'`, `'y'` or `'both'` | +| panSettings.extentX | `false` | `Number[]` | `[-Infinity, Infinity]` | Pixel | +| panSettings.extentY | `false` | `Number[]` | `[-Infinity, Infinity]` | Pixel | + +`zoomIdentity` must be an `Object` of the form: + +```js +{ + x: <Number>, + y: <Number>, + kx: <Number>, + ky: <Number> +} +``` +Where `x` and `y` represent the amount in pixels that the `Section` is panned to the right and bottom. `kx` and `ky` represent zooming factors, which are not used for panning. Its default values (i.e. no zooming and panning) are: + +```js +{ + x: 0, + y: 0, + kx: 1, + ky: 1 +} +``` + +`panSettings` must be an `Object` with the following possible members: + +```js +{ + setZoomIdentity: <Function>, + setBlockReindexing: <Function>, + dimension: <String>, + extentX: <Array>, + extentY: <Array> +} +``` + +where + +- `setZoomIdentity` is a function that updates the `zoomIdentity` +- `setBlockReindexing`is a function that updates the `blockReindexing` +- `dimension` can be used to limit scrolling to a either the x or y dimension +- `extentX` determines how far can be scrolled in the x dimension (if set to `[0, 0]` scrolling will be disabled in the x dimension) +- `extentY` determines how far can be scrolled in the y dimension (if set to `[0, 0]` scrolling will be disabled in the y dimension) + +TODO explain `setZoomIdentity` and `setBlockReindexing`. + +## Return value + +TODO diff --git a/site/src/routes/docs/helpers/create-zoom-handler.sveltex b/site/src/routes/docs/helpers/create-zoom-handler.sveltex new file mode 100644 index 00000000..e68feb5c --- /dev/null +++ b/site/src/routes/docs/helpers/create-zoom-handler.sveltex @@ -0,0 +1,3 @@ +# createZoomHandler + +TODO \ No newline at end of file diff --git a/site/src/routes/docs/helpers/examples/_GeoBasic.svelte b/site/src/routes/docs/helpers/examples/_GeoBasic.svelte new file mode 100644 index 00000000..f9bd6059 --- /dev/null +++ b/site/src/routes/docs/helpers/examples/_GeoBasic.svelte @@ -0,0 +1,40 @@ +<script> + import { Graphic, Section, Rectangle, createGeoScales } from '@snlab/florence' + import { scaleLinear } from 'd3-scale' + + const domains = { + x: [2.5, 7.5], + y: [0, 10] + } + + const regularScales = { + scaleX: scaleLinear().domain(domains.x), + scaleY: scaleLinear().domain(domains.y) + } + + const geoScales = createGeoScales(domains) +</script> + +<Graphic width={400} height={200}> + + <Section + x1={0} + x2={200} + {...regularScales} + padding={20} + backgroundColor={'#d3d3d3'} + > + <Rectangle x1={2.5} x2={7.5} y1={0} y2={10} fill={'red'} /> + </Section> + + <Section + x1={200} + x2={400} + {...geoScales} + padding={20} + backgroundColor={'#d3d3d3'} + > + <Rectangle x1={2.5} x2={7.5} y1={0} y2={10} fill={'blue'} /> + </Section> + +</Graphic> diff --git a/site/src/routes/docs/helpers/examples/_PanExample.svelte b/site/src/routes/docs/helpers/examples/_PanExample.svelte new file mode 100644 index 00000000..6ff33164 --- /dev/null +++ b/site/src/routes/docs/helpers/examples/_PanExample.svelte @@ -0,0 +1,37 @@ +<script> + import { + Graphic, Section, Rectangle, XAxis, YAxis, createPanHandler + } from '@snlab/florence' + + let zoomIdentity = { x: 0, y: 0, kx: 1, ky: 1 } + let blockReindexing = false + + const setZoomIdentity = zoomId => { zoomIdentity = zoomId } + const setBlockReindexing = bool => { blockReindexing = bool } + + const pan = createPanHandler(zoomIdentity, { + setZoomIdentity, + setBlockReindexing, + extentX: [-100, 100], + extentY: [-100, 100] + }) +</script> + +<Graphic width={200} height={200} padding={20}> + + <Section + scaleX={[0, 10]} + scaleY={[0, 10]} + {zoomIdentity} + {...pan.handlers} + {blockReindexing} + > + + <Rectangle x1={2.5} x2={7.5} y1={2.5} y2={7.5} /> + + <XAxis /> + <YAxis /> + + </Section> + +</Graphic> \ No newline at end of file diff --git a/site/src/routes/docs/marks/area.sveltex b/site/src/routes/docs/marks/area.sveltex index 0dd4bf5c..203665e2 100644 --- a/site/src/routes/docs/marks/area.sveltex +++ b/site/src/routes/docs/marks/area.sveltex @@ -40,7 +40,7 @@ import SimpleExample from './examples/_AreaSimple.svelte' ### Positioning -| Name | Required | Type(s) | Default | Unit(s) | +| Prop | Required | Type(s) | Default | Unit(s) | | --------------- | -------- | -------------------------------------------- | ----------- | ---------------------------------------------------- | | x1 | `true` | `Number[]`, `String[]`, `Date[]`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | | x2 | `false` | `Number[]`, `String[]`, `Date[]`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | @@ -59,7 +59,7 @@ import VerticalAreaBoth from './utils/_VerticalAreaBoth.svelte' import HorizontalAreaLower from './utils/_HorizontalAreaLower.svelte' ``` -| Name | Description | Representation | | | +| Prop | Description | Representation | | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- | --- | --- | | x1 | X coordinates of both upper and lower bounds of an area when x is the independent variable;<br>x coordinates of the right bound of an area when y is the independent variable. | <HorizontalAreaBoth /> <VerticalAreaRight /> | | | | x2 | X coordinates of the left bound of an area when y is the independent variable. | <VerticalAreaLeft /> | | | @@ -87,14 +87,14 @@ For all positioning props, a function can be supplied that bypasses the scaling ### Aesthetics -| Prop | Required | Type(s) | Default | Unit(s) | -| ------------- | -------- | -------- | ----------- | --------------------------- | -| stroke | `false` | `String` | `'none'` | Name, hex, rgb or hsl color | -| strokeWidth | `false` | `Number` | `0` | Pixel | -| strokeOpacity | `false` | `Number` | `undefined` | Number between 0 and 1 | -| fill | `false` | `String` | `'#000000'` | Name, hex, rgb or hsl color | -| fillOpacity | `false` | `Number` | `undefined` | Number between 0 and 1 | -| opacity | `false` | `Number` | `1` | Number between 0 and 1 | +| Prop | Required | Type(s) | Default | Unit(s) | +| ------------- | -------- | -------- | ----------- | ---------------------------- | +| stroke | `false` | `String` | `'none'` | Named, hex, rgb or hsl color | +| strokeWidth | `false` | `Number` | `0` | Pixel | +| strokeOpacity | `false` | `Number` | `undefined` | Number between 0 and 1 | +| fill | `false` | `String` | `'#000000'` | Named, hex, rgb or hsl color | +| fillOpacity | `false` | `Number` | `undefined` | Number between 0 and 1 | +| opacity | `false` | `Number` | `1` | Number between 0 and 1 | These aesthetic props are similar to attributes of the SVG [path](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/path) element. The analogous `path` attributes are shown below in brackets: @@ -107,15 +107,63 @@ These aesthetic props are similar to attributes of the SVG [path](https://develo ### Transitions -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ------------------ | ----------- | -------------------------------- | +| transition | `false` | `Number`, `Object` | `undefined` | Duration in ms or options object | + +See the [transition](/docs/concepts/transitions) documentation for more information. ### Interactions - TODO +#### Mouse events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onClick | `false` | `Function` | `undefined` | - | +| onMousedown | `false` | `Function` | `undefined` | - | +| onMouseup | `false` | `Function` | `undefined` | - | +| onMouseover | `false` | `Function` | `undefined` | - | +| onMouseout | `false` | `Function` | `undefined` | - | +| onMousedrag | `false` | `Function` | `undefined` | - | + +#### Touch events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onTouchdown | `false` | `Function` | `undefined` | - | +| onTouchup | `false` | `Function` | `undefined` | - | +| onTouchover | `false` | `Function` | `undefined` | - | +| onTouchout | `false` | `Function` | `undefined` | - | +| onTouchdrag | `false` | `Function` | `undefined` | - | + +#### Select events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ---------- | ----------- | ------- | +| onSelect | `false` | `Function` | `undefined` | - | +| onDeselect | `false` | `Function` | `undefined` | - | + +See the [interactivity](/docs/concepts/interactivity) documentation for more information. ### Other -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | ----------- | ------- | +| renderSettings | `false` | `Object` | `undefined` | - | +| blockReindexing | `false` | `Boolean` | `false` | - | +| clip | `false` | `Boolean` | `true` | - | + +- `renderSettings`: see the [advanced rendering](/docs/concepts/advanced-rendering) documentation for more information +- `blockReindexing`: see the [interactivity](/docs/concepts/interactivity) documentation for more information. +- `clip`: indicates whether the Mark or Layer should be clipped off if it extends beyond its parent `Section` or `Graphic` viewport (i.e. the area within the padding). + +In addition, the `AreaLayer` has the `key` prop: + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---- | -------- | ---------- | ----------- | -------------------- | +| key | `false` | `String[]` | `undefined` | Array of unique keys | + +See the [marks versus layers](/docs/concepts/marks-vs-layers) documentation for more information on how keys work. ## Examples diff --git a/site/src/routes/docs/marks/funcline.sveltex b/site/src/routes/docs/marks/funcline.sveltex index ec5221af..ed76912d 100644 --- a/site/src/routes/docs/marks/funcline.sveltex +++ b/site/src/routes/docs/marks/funcline.sveltex @@ -1,6 +1,6 @@ # FuncLine -The `FuncLine` mark can be used to plot functions over intervals. +The `FuncLine` mark can be used to plot functions over intervals. It is the only mark that does not have a corresponding layer element. ```markup <script> @@ -34,10 +34,10 @@ import SimpleExample from './examples/_FuncLineSimple.svelte' ### Positioning -| Name | Required | Type(s) | Default | Unit(s) | +| Prop | Required | Type(s) | Default | Unit(s) | | ---- | -------- | ---------- | ----------- | ----------------------------------------------------- | -| func | `true` | `Function` | `undefined` | NA | -| x | `false` | `Number[]` | `undefined` | [Local coordinates](/docs/concepts/local-coordinates) | +| func | `true` | `Function` | `undefined` | - | +| x | `false` | `Number[]` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | To render `FuncLine`, a `Function` that maps a numeric input to a numeric output has to be passed to the `func` prop. By default, this function will be plotted over a domain that is inherited from the parent `Graphic` or `Section`. To provide a different custom domain, the `x` prop can be passed an `Array` containing two numbers. For example: @@ -75,7 +75,7 @@ The `FuncLine` only works if its parent `Graphic` or `Section`'s scales have qua ### Aesthetics -| Name | Required | Type(s) | Default | Unit(s) | +| Prop | Required | Type(s) | Default | Unit(s) | | ----------- | -------- | -------- | ----------- | ---------------------------- | | stroke | `false` | `String` | `'#000000'` | Named, hex, rgb or hsl color | | strokeWidth | `false` | `Number` | `3` | Pixel | @@ -89,15 +89,55 @@ These aesthetic props are similar to attributes of the SVG [line](https://develo ### Transitions -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ------------------ | ----------- | -------------------------------- | +| transition | `false` | `Number`, `Object` | `undefined` | Duration in ms or options object | + +See the [transition](/docs/concepts/transitions) documentation for more information. ### Interactions -TODO +#### Mouse events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onClick | `false` | `Function` | `undefined` | - | +| onMousedown | `false` | `Function` | `undefined` | - | +| onMouseup | `false` | `Function` | `undefined` | - | +| onMouseover | `false` | `Function` | `undefined` | - | +| onMouseout | `false` | `Function` | `undefined` | - | +| onMousedrag | `false` | `Function` | `undefined` | - | + +#### Touch events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onTouchdown | `false` | `Function` | `undefined` | - | +| onTouchup | `false` | `Function` | `undefined` | - | +| onTouchover | `false` | `Function` | `undefined` | - | +| onTouchout | `false` | `Function` | `undefined` | - | +| onTouchdrag | `false` | `Function` | `undefined` | - | + +#### Select events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ---------- | ----------- | ------- | +| onSelect | `false` | `Function` | `undefined` | - | +| onDeselect | `false` | `Function` | `undefined` | - | + +See the [interactivity](/docs/concepts/interactivity) documentation for more information. ### Other -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | ----------- | ------- | +| renderSettings | `false` | `Object` | `undefined` | - | +| blockReindexing | `false` | `Boolean` | `false` | - | +| clip | `false` | `Boolean` | `true` | - | + +- `renderSettings`: see the [advanced rendering](/docs/concepts/advanced-rendering) documentation for more information +- `blockReindexing`: see the [interactivity](/docs/concepts/interactivity) documentation for more information. +- `clip`: indicates whether the Mark should be clipped off if it extends beyond its parent `Section` or `Graphic` viewport (i.e. the area within the padding). ## Examples diff --git a/site/src/routes/docs/marks/label.sveltex b/site/src/routes/docs/marks/label.sveltex index 71f4de15..bdc6cc8d 100644 --- a/site/src/routes/docs/marks/label.sveltex +++ b/site/src/routes/docs/marks/label.sveltex @@ -28,12 +28,12 @@ import SimpleExample from './examples/_LabelSimple.svelte' ### Positioning -| Name | Required | Type(s) | Default | Unit(s) | +| Prop | Required | Type(s) | Default | Unit(s) | | ----------- | ----------------------------------------- | -------------------------------------------------------------------------- | ----------- | ---------------------------------------------------- | | x | `if (geometry === undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | | y | `if (geometry === undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | | geometry | `if (x === undefined && y === undefined)` | GeoJSON [Point](https://tools.ietf.org/html/rfc7946#section-3.1.2) feature | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | -| anchorPoint | `false` | `String` | `'center'` | See below | +| anchorPoint | `false` | `String` | `'center'` | See explanation | To render a `Label`, you will need to provide either the `x` and `y` props, or the `geometry` prop. The two uses are mutually exclusive. The `x` and `y` coordinates, or the coordinates in the GeoJSON feature passed to `geometry`, control the anchor point of the text. @@ -55,9 +55,9 @@ The ancher point is by default in the center, but can be changed to with the `an | Prop | Required | Types | Default | Unit(s) | | ------------- | -------- | ------------------ | ------------- | ----------------------------- | -| text | `false` | `Number`, `String` | `undefined` | NA | +| text | `false` | `Number`, `String` | `undefined` | - | | fontSize | `false` | `Number` | `16` | Pixel | -| fontWeight | `false` | `Number`, `String` | `'normal'` | See below | +| fontWeight | `false` | `Number`, `String` | `'normal'` | See explanation | | fontFamily | `false` | `String` | `'Helvetica'` | Name of font family | | rotation | `false` | `Number` | `0` | Degree | | fill | `false` | `String` | `'#000000'` | Named, hex, rgb, or hsl color | @@ -83,15 +83,63 @@ These aesthetic props are similar to attributes of the SVG [text](https://develo ### Transitions -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ------------------ | ----------- | -------------------------------- | +| transition | `false` | `Number`, `Object` | `undefined` | Duration in ms or options object | + +See the [transition](/docs/concepts/transitions) documentation for more information. ### Interactions -TODO +#### Mouse events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onClick | `false` | `Function` | `undefined` | - | +| onMousedown | `false` | `Function` | `undefined` | - | +| onMouseup | `false` | `Function` | `undefined` | - | +| onMouseover | `false` | `Function` | `undefined` | - | +| onMouseout | `false` | `Function` | `undefined` | - | +| onMousedrag | `false` | `Function` | `undefined` | - | + +#### Touch events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onTouchdown | `false` | `Function` | `undefined` | - | +| onTouchup | `false` | `Function` | `undefined` | - | +| onTouchover | `false` | `Function` | `undefined` | - | +| onTouchout | `false` | `Function` | `undefined` | - | +| onTouchdrag | `false` | `Function` | `undefined` | - | + +#### Select events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ---------- | ----------- | ------- | +| onSelect | `false` | `Function` | `undefined` | - | +| onDeselect | `false` | `Function` | `undefined` | - | + +See the [interactivity](/docs/concepts/interactivity) documentation for more information. ### Other -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | ----------- | ------- | +| renderSettings | `false` | `Object` | `undefined` | - | +| blockReindexing | `false` | `Boolean` | `false` | - | +| clip | `false` | `Boolean` | `true` | - | + +- `renderSettings`: see the [advanced rendering](/docs/concepts/advanced-rendering) documentation for more information +- `blockReindexing`: see the [interactivity](/docs/concepts/interactivity) documentation for more information. +- `clip`: indicates whether the Mark or Layer should be clipped off if it extends beyond its parent `Section` or `Graphic` viewport (i.e. the area within the padding). + +In addition, the `LabelLayer` has the `key` prop: + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---- | -------- | ---------- | ----------- | -------------------- | +| key | `false` | `String[]` | `undefined` | Array of unique keys | + +See the [marks versus layers](/docs/concepts/marks-vs-layers) documentation for more information on how keys work. ## Examples diff --git a/site/src/routes/docs/marks/line.sveltex b/site/src/routes/docs/marks/line.sveltex index ea1b7df6..f073c4fe 100644 --- a/site/src/routes/docs/marks/line.sveltex +++ b/site/src/routes/docs/marks/line.sveltex @@ -39,7 +39,7 @@ To render the Line mark, you will need to provide the `x` and `y` or the `geomet ### Positioning -| Name | Required | Type(s) | Default | Unit(s)(s) | +| Prop | Required | Type(s) | Default | Unit(s)(s) | | -------- | ----------------------------------------- | ------------------------------------------------------------------------------------ | ----------- | ---------------------------------------------------- | | x | `if (geometry === undefined)` | `Number[]`, `String[]`, `Date[]`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | | y | `if (geometry === undefined)` | `Number[]`, `String[]`, `Date[]`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | @@ -49,7 +49,7 @@ To render the Line mark, you will need to provide the `x` and `y` or the `geomet ### Aesthetics -| Name | Required | Type(s) | Default | Unit(s) | +| Prop | Required | Type(s) | Default | Unit(s) | | ----------- | -------- | -------- | ----------- | ---------------------------- | | stroke | `false` | `String` | `'#000000'` | Named, hex, rgb or hsl color | | strokeWidth | `false` | `Number` | `3` | Pixel | @@ -63,15 +63,63 @@ These aesthetic props are similar to attributes of the SVG [line](https://develo ### Transitions -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ------------------ | ----------- | -------------------------------- | +| transition | `false` | `Number`, `Object` | `undefined` | Duration in ms or options object | + +See the [transition](/docs/concepts/transitions) documentation for more information. ### Interactions -TODO +#### Mouse events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onClick | `false` | `Function` | `undefined` | - | +| onMousedown | `false` | `Function` | `undefined` | - | +| onMouseup | `false` | `Function` | `undefined` | - | +| onMouseover | `false` | `Function` | `undefined` | - | +| onMouseout | `false` | `Function` | `undefined` | - | +| onMousedrag | `false` | `Function` | `undefined` | - | + +#### Touch events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onTouchdown | `false` | `Function` | `undefined` | - | +| onTouchup | `false` | `Function` | `undefined` | - | +| onTouchover | `false` | `Function` | `undefined` | - | +| onTouchout | `false` | `Function` | `undefined` | - | +| onTouchdrag | `false` | `Function` | `undefined` | - | + +#### Select events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ---------- | ----------- | ------- | +| onSelect | `false` | `Function` | `undefined` | - | +| onDeselect | `false` | `Function` | `undefined` | - | + +See the [interactivity](/docs/concepts/interactivity) documentation for more information. ### Other -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | ----------- | ------- | +| renderSettings | `false` | `Object` | `undefined` | - | +| blockReindexing | `false` | `Boolean` | `false` | - | +| clip | `false` | `Boolean` | `true` | - | + +- `renderSettings`: see the [advanced rendering](/docs/concepts/advanced-rendering) documentation for more information +- `blockReindexing`: see the [interactivity](/docs/concepts/interactivity) documentation for more information. +- `clip`: indicates whether the Mark or Layer should be clipped off if it extends beyond its parent `Section` or `Graphic` viewport (i.e. the area within the padding). + +In addition, the `LineLayer` has the `key` prop: + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---- | -------- | ---------- | ----------- | -------------------- | +| key | `false` | `String[]` | `undefined` | Array of unique keys | + +See the [marks versus layers](/docs/concepts/marks-vs-layers) documentation for more information on how keys work. ## Examples diff --git a/site/src/routes/docs/marks/point.sveltex b/site/src/routes/docs/marks/point.sveltex index e6dab2c7..d8484f45 100644 --- a/site/src/routes/docs/marks/point.sveltex +++ b/site/src/routes/docs/marks/point.sveltex @@ -27,7 +27,7 @@ import SimpleExample from './examples/_PointSimple.svelte' ### Positioning -| Name | Required | Type(s) | Default | Unit(s)(s) | +| Prop | Required | Type(s) | Default | Unit(s)(s) | | ---- | ----------------------------------------- | -------------------------------------------------------------------------- | ----------- | ---------------------------------------------------- | | x | `if (geometry === undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | | y | `if (geometry === undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | @@ -39,7 +39,7 @@ To render a `Point`, you will need to provide either the `x` and `y` props, or t ### Aesthetics -| Name | Required | Type(s) | Default | Unit(s) | +| Prop | Required | Type(s) | Default | Unit(s) | | ------------- | -------- | -------- | ----------- | ---------------------------- | | radius | `false` | `Number` | `3` | Pixel | | fill | `false` | `String` | `'#000000'` | Named, hex, rgb or hsl color | @@ -61,15 +61,63 @@ These aesthetic props are similar to attributes of the SVG [circle](https://deve ### Transitions -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ------------------ | ----------- | -------------------------------- | +| transition | `false` | `Number`, `Object` | `undefined` | Duration in ms or options object | + +See the [transition](/docs/concepts/transitions) documentation for more information. ### Interactions -TODO +#### Mouse events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onClick | `false` | `Function` | `undefined` | - | +| onMousedown | `false` | `Function` | `undefined` | - | +| onMouseup | `false` | `Function` | `undefined` | - | +| onMouseover | `false` | `Function` | `undefined` | - | +| onMouseout | `false` | `Function` | `undefined` | - | +| onMousedrag | `false` | `Function` | `undefined` | - | + +#### Touch events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onTouchdown | `false` | `Function` | `undefined` | - | +| onTouchup | `false` | `Function` | `undefined` | - | +| onTouchover | `false` | `Function` | `undefined` | - | +| onTouchout | `false` | `Function` | `undefined` | - | +| onTouchdrag | `false` | `Function` | `undefined` | - | + +#### Select events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ---------- | ----------- | ------- | +| onSelect | `false` | `Function` | `undefined` | - | +| onDeselect | `false` | `Function` | `undefined` | - | + +See the [interactivity](/docs/concepts/interactivity) documentation for more information. ### Other -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | ----------- | ------- | +| renderSettings | `false` | `Object` | `undefined` | - | +| blockReindexing | `false` | `Boolean` | `false` | - | +| clip | `false` | `Boolean` | `true` | - | + +- `renderSettings`: see the [advanced rendering](/docs/concepts/advanced-rendering) documentation for more information +- `blockReindexing`: see the [interactivity](/docs/concepts/interactivity) documentation for more information. +- `clip`: indicates whether the Mark or Layer should be clipped off if it extends beyond its parent `Section` or `Graphic` viewport (i.e. the area within the padding). + +In addition, the `PointLayer` has the `key` prop: + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---- | -------- | ---------- | ----------- | -------------------- | +| key | `false` | `String[]` | `undefined` | Array of unique keys | + +See the [marks versus layers](/docs/concepts/marks-vs-layers) documentation for more information on how keys work. ## Examples diff --git a/site/src/routes/docs/marks/polygon.sveltex b/site/src/routes/docs/marks/polygon.sveltex index 06a590cb..171257a0 100644 --- a/site/src/routes/docs/marks/polygon.sveltex +++ b/site/src/routes/docs/marks/polygon.sveltex @@ -38,7 +38,7 @@ import SimpleExample from './examples/_PolygonSimple.svelte' ### Positioning -| Name | Required | Type(s) | Default | Unit(s)(s) | +| Prop | Required | Type(s) | Default | Unit(s)(s) | | -------- | ----------------------------------------- | ------------------------------------------------------------------------------------ | ----------- | ---------------------------------------------------- | | x | `if (geometry === undefined)` | `Number[]`, `String[]`, `Date[]`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | | y | `if (geometry === undefined)` | `Number[]`, `String[]`, `Date[]`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | @@ -72,15 +72,63 @@ These aesthetic props are similar to attributes of the SVG [polygon](https://dev ### Transitions -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ------------------ | ----------- | -------------------------------- | +| transition | `false` | `Number`, `Object` | `undefined` | Duration in ms or options object | + +See the [transition](/docs/concepts/transitions) documentation for more information. ### Interactions -TODO +#### Mouse events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onClick | `false` | `Function` | `undefined` | - | +| onMousedown | `false` | `Function` | `undefined` | - | +| onMouseup | `false` | `Function` | `undefined` | - | +| onMouseover | `false` | `Function` | `undefined` | - | +| onMouseout | `false` | `Function` | `undefined` | - | +| onMousedrag | `false` | `Function` | `undefined` | - | + +#### Touch events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onTouchdown | `false` | `Function` | `undefined` | - | +| onTouchup | `false` | `Function` | `undefined` | - | +| onTouchover | `false` | `Function` | `undefined` | - | +| onTouchout | `false` | `Function` | `undefined` | - | +| onTouchdrag | `false` | `Function` | `undefined` | - | + +#### Select events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ---------- | ----------- | ------- | +| onSelect | `false` | `Function` | `undefined` | - | +| onDeselect | `false` | `Function` | `undefined` | - | + +See the [interactivity](/docs/concepts/interactivity) documentation for more information. ### Other -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | ----------- | ------- | +| renderSettings | `false` | `Object` | `undefined` | - | +| blockReindexing | `false` | `Boolean` | `false` | - | +| clip | `false` | `Boolean` | `true` | - | + +- `renderSettings`: see the [advanced rendering](/docs/concepts/advanced-rendering) documentation for more information +- `blockReindexing`: see the [interactivity](/docs/concepts/interactivity) documentation for more information. +- `clip`: indicates whether the Mark or Layer should be clipped off if it extends beyond its parent `Section` or `Graphic` viewport (i.e. the area within the padding). + +In addition, the `PolygonLayer` has the `key` prop: + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---- | -------- | ---------- | ----------- | -------------------- | +| key | `false` | `String[]` | `undefined` | Array of unique keys | + +See the [marks versus layers](/docs/concepts/marks-vs-layers) documentation for more information on how keys work. ## Examples diff --git a/site/src/routes/docs/marks/rectangle.sveltex b/site/src/routes/docs/marks/rectangle.sveltex index df714ce2..271b2db5 100644 --- a/site/src/routes/docs/marks/rectangle.sveltex +++ b/site/src/routes/docs/marks/rectangle.sveltex @@ -54,7 +54,7 @@ import SimpleExample from './examples/_RectangleSimple.svelte' | y1 | `if (y2 !== undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | | y2 | `if (y1 !== undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | -The `Rectangle` mark draws a rectangle with four corners defined by the `x1`, `x2`, `y1` and `y2` props. In many cases (i.e. bar charts), this involves using the `bandwidth` of a [band scale](https://github.com/d3/d3-scale#band-scales) as shown in the example above- see the [local coordinates](/docs/concepts/local-coordinates) documentation for a more in-depth explanation of this syntax. If `x` and/or `y` coordinates are left undefined, the `Rectangle` will inherit the respective domains from its parent `Graphic` or `Section`: +The `Rectangle` mark draws a rectangle with four corners defined by the `x1`, `x2`, `y1` and `y2` props. As such, the positioning of the `Rectangle` is identical to the [Section](/docs/core/section). In many cases (i.e. bar charts), this involves using the `bandwidth` of a [band scale](https://github.com/d3/d3-scale#band-scales) as shown in the example above- see the [local coordinates](/docs/concepts/local-coordinates) documentation for a more in-depth explanation of this syntax. Like the [Section](/docs/core/section), If `x` and/or `y` coordinates are omitted, the `Rectangle` will inherit the extents of its parent `Graphic` or `Section`: ```markup <script> @@ -107,15 +107,63 @@ These aesthetic props are similar to attributes of the SVG [rect](https://develo ### Transitions -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ------------------ | ----------- | -------------------------------- | +| transition | `false` | `Number`, `Object` | `undefined` | Duration in ms or options object | + +See the [transition](/docs/concepts/transitions) documentation for more information. ### Interactions -TODO +#### Mouse events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onClick | `false` | `Function` | `undefined` | - | +| onMousedown | `false` | `Function` | `undefined` | - | +| onMouseup | `false` | `Function` | `undefined` | - | +| onMouseover | `false` | `Function` | `undefined` | - | +| onMouseout | `false` | `Function` | `undefined` | - | +| onMousedrag | `false` | `Function` | `undefined` | - | + +#### Touch events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onTouchdown | `false` | `Function` | `undefined` | - | +| onTouchup | `false` | `Function` | `undefined` | - | +| onTouchover | `false` | `Function` | `undefined` | - | +| onTouchout | `false` | `Function` | `undefined` | - | +| onTouchdrag | `false` | `Function` | `undefined` | - | + +#### Select events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ---------- | ----------- | ------- | +| onSelect | `false` | `Function` | `undefined` | - | +| onDeselect | `false` | `Function` | `undefined` | - | + +See the [interactivity](/docs/concepts/interactivity) documentation for more information. ### Other -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | ----------- | ------- | +| renderSettings | `false` | `Object` | `undefined` | - | +| blockReindexing | `false` | `Boolean` | `false` | - | +| clip | `false` | `Boolean` | `true` | - | + +- `renderSettings`: see the [advanced rendering](/docs/concepts/advanced-rendering) documentation for more information +- `blockReindexing`: see the [interactivity](/docs/concepts/interactivity) documentation for more information. +- `clip`: indicates whether the Mark or Layer should be clipped off if it extends beyond its parent `Section` or `Graphic` viewport (i.e. the area within the padding). + +In addition, the `RectangleLayer` has the `key` prop: + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---- | -------- | ---------- | ----------- | -------------------- | +| key | `false` | `String[]` | `undefined` | Array of unique keys | + +See the [marks versus layers](/docs/concepts/marks-vs-layers) documentation for more information on how keys work. ## Examples diff --git a/site/src/routes/docs/marks/symbol.sveltex b/site/src/routes/docs/marks/symbol.sveltex index 74497de9..526c8d06 100644 --- a/site/src/routes/docs/marks/symbol.sveltex +++ b/site/src/routes/docs/marks/symbol.sveltex @@ -31,7 +31,7 @@ Note that the symbol mark is imported/used as `Symbol_` to prevent conflicts wit ### Positioning -| Name | Required | Type(s) | Default | Unit(s)(s) | +| Prop | Required | Type(s) | Default | Unit(s)(s) | | ---- | ----------------------------------------- | -------------------------------------------------------------------------- | ----------- | ---------------------------------------------------- | | x | `if (geometry === undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | | y | `if (geometry === undefined)` | `Number`, `String`, `Date`, `Function` | `undefined` | [Local coordinate](/docs/concepts/local-coordinates) | @@ -45,7 +45,7 @@ To render a `Symbol_`, you will need to provide either the `x` and `y` props, or | Prop | Required | Types | Default | Unit(s) | | ------------- | -------- | -------- | ----------- | ---------------------------- | -| shape | `false` | `String` | `'circle'` | See below | +| shape | `false` | `String` | `'circle'` | See explanation | | size | `false` | `Number` | `10` | Pixel | | fill | `false` | `String` | `'#000000'` | Named, hex, rgb or hsl color | | fillOpacity | `false` | `Number` | `undefined` | Number between 0 and 1 | @@ -94,15 +94,63 @@ import CustomShape from './utils/_CustomShape.svelte' ### Transitions -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ------------------ | ----------- | -------------------------------- | +| transition | `false` | `Number`, `Object` | `undefined` | Duration in ms or options object | + +See the [transition](/docs/concepts/transitions) documentation for more information. ### Interactions -TODO +#### Mouse events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onClick | `false` | `Function` | `undefined` | - | +| onMousedown | `false` | `Function` | `undefined` | - | +| onMouseup | `false` | `Function` | `undefined` | - | +| onMouseover | `false` | `Function` | `undefined` | - | +| onMouseout | `false` | `Function` | `undefined` | - | +| onMousedrag | `false` | `Function` | `undefined` | - | + +#### Touch events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ----------- | -------- | ---------- | ----------- | ------- | +| onTouchdown | `false` | `Function` | `undefined` | - | +| onTouchup | `false` | `Function` | `undefined` | - | +| onTouchover | `false` | `Function` | `undefined` | - | +| onTouchout | `false` | `Function` | `undefined` | - | +| onTouchdrag | `false` | `Function` | `undefined` | - | + +#### Select events + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---------- | -------- | ---------- | ----------- | ------- | +| onSelect | `false` | `Function` | `undefined` | - | +| onDeselect | `false` | `Function` | `undefined` | - | + +See the [interactivity](/docs/concepts/interactivity) documentation for more information. ### Other -TODO +| Prop | Required | Type(s) | Default | Unit(s) | +| --------------- | -------- | --------- | ----------- | ------- | +| renderSettings | `false` | `Object` | `undefined` | - | +| blockReindexing | `false` | `Boolean` | `false` | - | +| clip | `false` | `Boolean` | `true` | - | + +- `renderSettings`: see the [advanced rendering](/docs/concepts/advanced-rendering) documentation for more information +- `blockReindexing`: see the [interactivity](/docs/concepts/interactivity) documentation for more information. +- `clip`: indicates whether the Mark or Layer should be clipped off if it extends beyond its parent `Section` or `Graphic` viewport (i.e. the area within the padding). + +In addition, the `SymbolLayer` has the `key` prop: + +| Prop | Required | Type(s) | Default | Unit(s) | +| ---- | -------- | ---------- | ----------- | -------------------- | +| key | `false` | `String[]` | `undefined` | Array of unique keys | + +See the [marks versus layers](/docs/concepts/marks-vs-layers) documentation for more information on how keys work. ## Examples diff --git a/site/src/routes/examples/area-chart.sveltex b/site/src/routes/examples/area-chart.sveltex index d77b17c3..59f595ae 100644 --- a/site/src/routes/examples/area-chart.sveltex +++ b/site/src/routes/examples/area-chart.sveltex @@ -1,6 +1,8 @@ # Area Chart -Some testing text +A simple area chart showing the closing price of Apple stock for a period between 2007 and 2013. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/area-chart ::: \ No newline at end of file diff --git a/site/src/routes/examples/brush.sveltex b/site/src/routes/examples/brush.sveltex index da0b7d29..fb333292 100644 --- a/site/src/routes/examples/brush.sveltex +++ b/site/src/routes/examples/brush.sveltex @@ -1,6 +1,6 @@ # Brush -Some testing text. +An example setup for a brush interaction. Draw a selection rectangle in the scatterplot with your mouse. After that, drag the rectangle around, and notice that the average x and y values of the points within the selection are updated. Of course, this particular use of brushing is not super useful, but is intended to illustrate how easy `florence` interactions integrate with the rest of the web page. ::: example examples/brush ::: \ No newline at end of file diff --git a/site/src/routes/examples/candlestick.sveltex b/site/src/routes/examples/candlestick.sveltex index e20f56f2..62531fa2 100644 --- a/site/src/routes/examples/candlestick.sveltex +++ b/site/src/routes/examples/candlestick.sveltex @@ -1,6 +1,8 @@ # Candlestick Chart -Some testing text +A candlestick chart showing open and closing prices of Apple stock from the end of 2017 until May 2018. Adapted from https://observablehq.com/@d3/candlestick-chart. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/candlestick ::: \ No newline at end of file diff --git a/site/src/routes/examples/categorical-dot.sveltex b/site/src/routes/examples/categorical-dot.sveltex index 186fe9c4..138b99af 100644 --- a/site/src/routes/examples/categorical-dot.sveltex +++ b/site/src/routes/examples/categorical-dot.sveltex @@ -1,6 +1,6 @@ # A categorical dot plot -Some testing text. +A simple graphic based on made-up data about fruits and their diameters, intended to illustrate the use of categorical domains. ::: example examples/categorical-dot ::: \ No newline at end of file diff --git a/site/src/routes/examples/choropleth-map.sveltex b/site/src/routes/examples/choropleth-map.sveltex index 0dd330c3..670ba42f 100644 --- a/site/src/routes/examples/choropleth-map.sveltex +++ b/site/src/routes/examples/choropleth-map.sveltex @@ -1,6 +1,8 @@ # A choropleth map of Singapore -Some testing text. +A basic choropleth map of Sinagpore, showing the mean resale price per square meter for houses in different [planning areas](https://en.wikipedia.org/wiki/Planning_Areas_of_Singapore). + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/choropleth-map ::: \ No newline at end of file diff --git a/site/src/routes/examples/choropleth.sveltex b/site/src/routes/examples/choropleth.sveltex index 354e2582..3bcf68e9 100644 --- a/site/src/routes/examples/choropleth.sveltex +++ b/site/src/routes/examples/choropleth.sveltex @@ -1,6 +1,8 @@ # Choropleth -Some testing text. +A basic choropleth map showing the population of U.S. states. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/choropleth ::: \ No newline at end of file diff --git a/site/src/routes/examples/density-contours.sveltex b/site/src/routes/examples/density-contours.sveltex index 96444219..1830ec33 100644 --- a/site/src/routes/examples/density-contours.sveltex +++ b/site/src/routes/examples/density-contours.sveltex @@ -1,6 +1,8 @@ # Density Contours -Some testing text +A chart showing the relationship between waiting and eruption times of the [Old Faithful](https://en.wikipedia.org/wiki/Old_Faithful) geyser in Yellowstone National Park. Adapted from https://observablehq.com/@d3/density-contours. This example is intended to illustrate how external libraries (in this case [d3-contour](https://github.com/d3/d3-contour)) can easily be integrated into `florence`. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/density-contours ::: \ No newline at end of file diff --git a/site/src/routes/examples/donut.sveltex b/site/src/routes/examples/donut.sveltex index c0a88ffb..60321441 100644 --- a/site/src/routes/examples/donut.sveltex +++ b/site/src/routes/examples/donut.sveltex @@ -1,6 +1,8 @@ # Donut Chart -Some testing text. +A donut chart showing the estimated population per age group in the U.S. in 2015. Adapted from https://observablehq.com/@d3/donut-chart. Data can be found [here](https://gist.githubusercontent.com/mbostock/a3541c73fdccd432acc8b11bf9f02641/raw/2bd0fce0bf34b020e93c5f6527b5a9d08c33ff06/population-by-age.csv). + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/donut ::: \ No newline at end of file diff --git a/site/src/routes/examples/dubois-simple.sveltex b/site/src/routes/examples/dubois-simple.sveltex index 7cc3a479..9e3bf9da 100644 --- a/site/src/routes/examples/dubois-simple.sveltex +++ b/site/src/routes/examples/dubois-simple.sveltex @@ -1,6 +1,6 @@ # Dubois simple -Some testing text. +Remake of one of [W.E.B Du Bois'](https://en.wikipedia.org/wiki/W._E._B._Du_Bois) classic [data portraits](https://www.amazon.com/W-Boiss-Data-Portraits-Visualizing/dp/1616897066) of black America. ::: example examples/dubois-simple ::: \ No newline at end of file diff --git a/site/src/routes/examples/gapminder.sveltex b/site/src/routes/examples/gapminder.sveltex index 0b2f3943..5ef0840b 100644 --- a/site/src/routes/examples/gapminder.sveltex +++ b/site/src/routes/examples/gapminder.sveltex @@ -1,6 +1,8 @@ # Gapminder -Some testing text +Remake of Hans Rosling's famous [Gapminder](https://www.gapminder.org/tools/?from=world) visualization. Adapted from https://observablehq.com/@mbostock/the-wealth-health-of-nations. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/gapminder ::: \ No newline at end of file diff --git a/site/src/routes/examples/heatmap.sveltex b/site/src/routes/examples/heatmap.sveltex index 4da8c1f0..667e4056 100644 --- a/site/src/routes/examples/heatmap.sveltex +++ b/site/src/routes/examples/heatmap.sveltex @@ -1,7 +1,8 @@ - # Heatmap -Some testing text. +Heatmap showing the relation between IMDB ratings and Rotten Tomatoes ratings of the same movies. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/heatmap ::: \ No newline at end of file diff --git a/site/src/routes/examples/isotype.sveltex b/site/src/routes/examples/isotype.sveltex index 55a676b4..2fd607fe 100644 --- a/site/src/routes/examples/isotype.sveltex +++ b/site/src/routes/examples/isotype.sveltex @@ -1,6 +1,6 @@ # Isotype Plot -Some testing text +Isotype plot showing the differences in livestock between the UK and U.S. from the 1943 book [Only An Ocean Between](http://www.thomwhite.co.uk/?p=1303). Adapted from https://vega.github.io/vega-lite/examples/isotype_bar_chart.html. Original by [@jwoLondon](https://github.com/jwoLondon). ::: example examples/isotype ::: \ No newline at end of file diff --git a/site/src/routes/examples/linked-views.sveltex b/site/src/routes/examples/linked-views.sveltex index e92ab32b..524cfd33 100644 --- a/site/src/routes/examples/linked-views.sveltex +++ b/site/src/routes/examples/linked-views.sveltex @@ -1,6 +1,8 @@ # Linked views -Some testing text +An example of linked views in `florence`. Hover over a [planning areas](https://en.wikipedia.org/wiki/Planning_Areas_of_Singapore) to see how the mean resale price per square meter for houses changed over time for that particular planning area. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/linked-views ::: \ No newline at end of file diff --git a/site/src/routes/examples/plain-scatterplot.sveltex b/site/src/routes/examples/plain-scatterplot.sveltex index 1be239e1..f42dc455 100644 --- a/site/src/routes/examples/plain-scatterplot.sveltex +++ b/site/src/routes/examples/plain-scatterplot.sveltex @@ -1,6 +1,8 @@ # A Plain Scatterplot -Some testing text. +A plain old scatterplot. Adapted from https://vega.github.io/vega-lite/examples/point_color_with_shape.html. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/plain-scatterplot ::: \ No newline at end of file diff --git a/site/src/routes/examples/population-pyramid.sveltex b/site/src/routes/examples/population-pyramid.sveltex index 3c2f716b..6447ecd7 100644 --- a/site/src/routes/examples/population-pyramid.sveltex +++ b/site/src/routes/examples/population-pyramid.sveltex @@ -1,6 +1,6 @@ # Population Pyramid -Some testing text. +Population pyramid based on the estimated population of the U.S. in 2015. Adapted from https://observablehq.com/@d3/population-pyramid. ::: example examples/population-pyramid ::: \ No newline at end of file diff --git a/site/src/routes/examples/scatterplot-temp-trends.sveltex b/site/src/routes/examples/scatterplot-temp-trends.sveltex index 5d3d655a..deccb8e7 100644 --- a/site/src/routes/examples/scatterplot-temp-trends.sveltex +++ b/site/src/routes/examples/scatterplot-temp-trends.sveltex @@ -1,6 +1,8 @@ # Global Temperature Trends -Some testing text +Original based on [How 2016 Became Earth’s Hottest Year on Record](https://www.nytimes.com/interactive/2017/01/18/science/earth/2016-hottest-year-on-record.html). Adapted from https://observablehq.com/@mbostock/global-temperature-trends. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/scatterplot-temp-trends ::: \ No newline at end of file diff --git a/site/src/routes/examples/scatterplot-transition.sveltex b/site/src/routes/examples/scatterplot-transition.sveltex index 05bf4f1c..024783cc 100644 --- a/site/src/routes/examples/scatterplot-transition.sveltex +++ b/site/src/routes/examples/scatterplot-transition.sveltex @@ -1,6 +1,6 @@ # Scatterplot with transition -Some testing text +Basic scatterplot based on randomly generated data, intended to illustrate transitions. ::: example examples/scatterplot-transition ::: \ No newline at end of file diff --git a/site/src/routes/examples/stacked-area.sveltex b/site/src/routes/examples/stacked-area.sveltex index f34602cf..7dce5420 100644 --- a/site/src/routes/examples/stacked-area.sveltex +++ b/site/src/routes/examples/stacked-area.sveltex @@ -1,6 +1,8 @@ # Stacked Area Chart -Some testing text +Stacked area chart showing unemployment by industry from 2000 to 2010. Original data from [U.S. Bureau of Labor Statistics](https://www.bls.gov/). Adapted from https://observablehq.com/@d3/stacked-area-chart. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/stacked-area ::: \ No newline at end of file diff --git a/site/src/routes/examples/stacked-horizontal-bars.sveltex b/site/src/routes/examples/stacked-horizontal-bars.sveltex index d74afd55..9799bcae 100644 --- a/site/src/routes/examples/stacked-horizontal-bars.sveltex +++ b/site/src/routes/examples/stacked-horizontal-bars.sveltex @@ -1,6 +1,8 @@ # Stacked Horizontal Bar Chart -Some testing text +Stacked horizontal bar chart showing the cumulative population of different age groups per state in the U.S. (2018). Adapted from https://observablehq.com/@d3/stacked-horizontal-bar-chart. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/stacked-horizontal-bars ::: \ No newline at end of file diff --git a/site/src/routes/examples/violin-plot.sveltex b/site/src/routes/examples/violin-plot.sveltex index 66b3b777..c829000a 100644 --- a/site/src/routes/examples/violin-plot.sveltex +++ b/site/src/routes/examples/violin-plot.sveltex @@ -1,6 +1,8 @@ # Violin Plot -Some testing text +Violin plot based on the classic [iris dataset](https://en.wikipedia.org/wiki/Iris_flower_data_set). Adapted from https://www.d3-graph-gallery.com/graph/violin_basicDens.html. + +The `(async () => { ... })()` bit is a so-called [Immediately Invoked Function Expression](https://developer.mozilla.org/en-US/docs/Glossary/IIFE), which is just a way to define a function and run it immediately without having to give it a name. It is used here to contain all logic that depends on asynchronous operations like fetching datasets. ::: example examples/violin-plot ::: \ No newline at end of file diff --git a/site/src/routes/tutorials/basic.sveltex b/site/src/routes/tutorials/basic.sveltex index 7bdbdf75..7979983a 100644 --- a/site/src/routes/tutorials/basic.sveltex +++ b/site/src/routes/tutorials/basic.sveltex @@ -83,7 +83,7 @@ let data = new DataContainer({ }); data = data - .dropNA() // drops NA values + .dropNA() // drops - values .filter(row => row.fruit !== "anchovies") // filters out unwanted values .groupBy("fruit") // groups data by common categorical values .summarise({ meanQuantity: { diameter: "mean" } }) // gets mean of groups diff --git a/site/static/images/coordinates.png b/site/static/images/coordinates.png index a84f6eb6..0d6de37e 100644 Binary files a/site/static/images/coordinates.png and b/site/static/images/coordinates.png differ diff --git a/site/styleguide/docs-marks.md b/site/styleguide/docs-marks.md index 7b0983f6..e8db67ce 100644 --- a/site/styleguide/docs-marks.md +++ b/site/styleguide/docs-marks.md @@ -7,10 +7,20 @@ ## Properties +- If 'Unit(s)' has no meaningful value, use ` - `. +- Common values for 'Unit(s)' include: + - Local coordinate (with link to /docs/concepts/local-coordinates) + - Pixel + - Named, hex, rgb or hsl color + - Number between 0 and 1 + - See explanation + - Font + - Degree + ### Positioning - A table with the following columns: - - Name (plain text) + - Prop (plain text) - Required (backticks) (with `if` statement showing how the prop depends on other props, or `true` or `false`) - Type(s) (backticks) (`Array` etc, seperated by commas) - Default (backticks) @@ -23,7 +33,7 @@ ### Aesthetics - A table with the following columns: - - Name (plain text) + - Prop (plain text) - Required (will always be plain text I guess) - Type(s) (backticks) - Default (backticks) @@ -44,7 +54,7 @@ Link to interactions docs ### Other - A table with the following columns: - - Name (plain text) + - Prop (plain text) - Required (plain text) - Type(s) (backticks) - Default diff --git a/src/components/Core/Grid/Grid.svelte b/src/components/Core/Grid/Grid.svelte index 8cd0ef76..11022775 100644 --- a/src/components/Core/Grid/Grid.svelte +++ b/src/components/Core/Grid/Grid.svelte @@ -15,7 +15,7 @@ export let columns = undefined export let rowGap = 0 export let columnGap = 0 - export let names = undefined + export let names export let viewGridTemplate = false // Option to console log grid layout export let viewGridShape = false // Option to console log rows in cols in grid diff --git a/src/components/Core/Title/Title.svelte b/src/components/Core/Title/Title.svelte index 9939815e..325a9fa3 100644 --- a/src/components/Core/Title/Title.svelte +++ b/src/components/Core/Title/Title.svelte @@ -53,6 +53,8 @@ export let onMouseover = undefined export let onMouseout = undefined + export let clip = false + // Contexts const sectionContext = SectionContext.subscribe() const graphicContext = GraphicContext.subscribe() @@ -129,7 +131,7 @@ text={title} fontFamily={titleFontFamily} fontSize={titleFontSize} fontWeight={titleFontWeight} rotation={titleRotation} anchorPoint={titleAnchorPoint} {transition} {onClick} {onMouseover} {onMouseout} - _asPolygon={false} + _asPolygon={false} {clip} /> {/if} @@ -145,6 +147,6 @@ text={subtitle} fontFamily={subtitleFontFamily} fontSize={subtitleFontSize} fontWeight={subtitleFontWeight} rotation={subtitleRotation} anchorPoint={subtitleAnchorPoint} {transition} {onClick} {onMouseover} {onMouseout} - _asPolygon={false} + _asPolygon={false} {clip} /> <!-- {/if} --> diff --git a/src/components/Marks/Mark/Mark.svelte b/src/components/Marks/Mark/Mark.svelte index fca9d858..7f6611c8 100644 --- a/src/components/Marks/Mark/Mark.svelte +++ b/src/components/Marks/Mark/Mark.svelte @@ -467,26 +467,32 @@ {#if renderLabel} - <text + <g clip-path={clip ? `url(#clip-${$sectionContext.sectionId})` : 'none'} - class="label" - x={$tr_screenGeometry.coordinates[0]} - y={$tr_screenGeometry.coordinates[1]} - fill={$tr_fill} - stroke={$tr_stroke} - stroke-width={$tr_strokeWidth} - fill-opacity={$tr_fillOpacity} - stroke-opacity={$tr_strokeOpacity} - opacity={$tr_opacity} - transform={rotateTransform} - font-family={fontFamily} - font-size={$tr_fontSize + 'px'} - font-weight={$tr_fontWeight} - text-anchor={parsedTextAnchorPoint.textAnchor} - dominant-baseline={parsedTextAnchorPoint.dominantBaseline} + class="label-group" > - {aesthetics.text} - </text> + + <text + class="label" + x={$tr_screenGeometry.coordinates[0]} + y={$tr_screenGeometry.coordinates[1]} + fill={$tr_fill} + stroke={$tr_stroke} + stroke-width={$tr_strokeWidth} + fill-opacity={$tr_fillOpacity} + stroke-opacity={$tr_strokeOpacity} + opacity={$tr_opacity} + transform={rotateTransform} + font-family={fontFamily} + font-size={$tr_fontSize + 'px'} + font-weight={$tr_fontWeight} + text-anchor={parsedTextAnchorPoint.textAnchor} + dominant-baseline={parsedTextAnchorPoint.dominantBaseline} + > + {aesthetics.text} + </text> + + </g> {/if} diff --git a/test/integration/tests/components/__snapshots__/label.spec.js.snap b/test/integration/tests/components/__snapshots__/label.spec.js.snap index a23e77ab..55aba928 100644 --- a/test/integration/tests/components/__snapshots__/label.spec.js.snap +++ b/test/integration/tests/components/__snapshots__/label.spec.js.snap @@ -25,24 +25,25 @@ exports[`Assertions > Label Mark Tests > [render] labels snapshot correctly #0`] </mask> </defs> <g class="section"> - <text - clip-path="url(#clip-sc0)" - class="label" - x="210" - y="310" - fill="yellow" - stroke="none" - stroke-width="0" - opacity="1" - transform="rotate(45, 210, 310)" - font-family="Georgia" - font-size="20px" - font-weight="bold" - text-anchor="middle" - dominant-baseline="middle" - > - Testing1 - </text> + <g clip-path="url(#clip-sc0)" class="label-group"> + <text + class="label" + x="210" + y="310" + fill="yellow" + stroke="none" + stroke-width="0" + opacity="1" + transform="rotate(45, 210, 310)" + font-family="Georgia" + font-size="20px" + font-weight="bold" + text-anchor="middle" + dominant-baseline="middle" + > + Testing1 + </text> + </g> <g clip-path="url(#clip-sc0)" class="label-layer"> <text class="label" diff --git a/test/integration/tests/components/axes.spec.js b/test/integration/tests/components/axes.spec.js index 12f7c1a4..316ac28b 100644 --- a/test/integration/tests/components/axes.spec.js +++ b/test/integration/tests/components/axes.spec.js @@ -12,7 +12,7 @@ context('Assertions', () => { }) it('[render] axis has title', () => { - cy.get('g.x-axis > .label').should('have.length', 1) + cy.get('g.x-axis > g.label-group > .label').should('have.length', 1) }) it('[render] axis has tick marks', () => { diff --git a/test/sandbox/src/App.svelte b/test/sandbox/src/App.svelte index f1088e74..c3e9faeb 100644 --- a/test/sandbox/src/App.svelte +++ b/test/sandbox/src/App.svelte @@ -42,6 +42,8 @@ // Bugs import GraphicAreaBug from './examples/GraphicAreaBug.svelte' import FuncLineBug from './examples/FuncLineBug.svelte' + + import RecycleTest from './examples/RecycleTest.svelte' // and add them to this component array const components = [ @@ -224,6 +226,11 @@ name: 'Func line bug', url: 'func-line-bug', component: FuncLineBug + }, + { + name: 'Recycle test', + url: 'recycle-test', + component: RecycleTest } ] </script> diff --git a/test/sandbox/src/examples/RecycleTest.svelte b/test/sandbox/src/examples/RecycleTest.svelte new file mode 100644 index 00000000..481db6fd --- /dev/null +++ b/test/sandbox/src/examples/RecycleTest.svelte @@ -0,0 +1,21 @@ +<script> + import { + Graphic, + Area, + AreaLayer, + XAxis, + YAxis + } from '../../../../src/' +</script> + +<Graphic flipY padding={30}> + + <Area + x1={[100, 200, 300]} + y1={[200, 100, 300]} + /> + + <XAxis /> + <YAxis /> + +</Graphic> \ No newline at end of file