@graphenedata/cli 0.0.1

package/dist/docs/data_apps/components/maps/area-map.md

@@ -0,0 +1,397 @@
+---
+title: Area Map
+description: Compare a metric across different regions on a map using a choropleth map
+---
+
+Compare a metric across different regions on a map using a choropleth map
+
+**Example:**
+
+```svelte
+<AreaMap 
+    data="la_zip_sales" 
+    areaCol=zip_code
+    geoJsonUrl='path/to/your/geoJson'
+    geoId=ZCTA5CE10
+    value=sales
+    valueFmt=usd
+    height=250
+/>
+```
+
+
+## Examples
+
+### Custom Basemap
+You can add a different basemap by passing in a basemap URL. You can find examples here: https://leaflet-extras.github.io/leaflet-providers/preview/
+
+**Example:**
+
+**Note:** you need to wrap the url in curly braces and backticks to avoid the curly braces in the URL being read as variables on your page
+
+```svelte
+<AreaMap 
+    data="la_zip_sales" 
+    areaCol=zip_code
+    geoJsonUrl='path/to/your/geoJson'
+    geoId=ZCTA5CE10
+    value=sales
+    valueFmt=usd
+    height=250
+    basemap="`https://tile.openstreetmap.org/{z"/{x}/{y}.png`}
+/>
+```
+
+### Using an Online GeoJSON
+
+
+**Example:**
+
+```svelte
+<AreaMap 
+    data="orders_by_state" 
+    areaCol=state
+    geoJsonUrl=https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_110m_admin_1_states_provinces.geojson
+    geoId=name
+    value=orders
+/>
+```
+
+### Custom Tooltip
+
+#### `tooltipType=hover`
+
+**Example:**
+
+```svelte
+<AreaMap 
+    data="la_zip_sales" 
+    areaCol=zip_code
+    geoJsonUrl='path/to/your/geoJson'
+    geoId=ZCTA5CE10
+    value=sales
+    valueFmt=usd
+    height=250
+    tooltip="[
+        {id: 'zip_code', fmt: 'id', showColumnName: false, valueClass: 'text-xl font-semibold'",
+        {id: 'sales', fmt: 'eur', fieldClass: 'text-[grey]', valueClass: 'text-[green]'}
+    ]}
+/>
+```
+
+#### With clickable link and `tooltipType=click`
+
+**Example:**
+
+```svelte
+<AreaMap 
+    data="la_zip_sales" 
+    areaCol=zip_code
+    geoJsonUrl='path/to/your/geoJson'
+    geoId=ZCTA5CE10
+    value=sales
+    valueFmt=usd
+    height=250
+    tooltipType=click
+    tooltip="[
+        {id: 'zip_code', fmt: 'id', showColumnName: false, valueClass: 'text-xl font-semibold'",
+        {id: 'sales', fmt: 'eur', fieldClass: 'text-[grey]', valueClass: 'text-[green]'},
+        {id: 'link_col', showColumnName: false, contentType: 'link', linkLabel: 'Click here', valueClass: 'font-bold mt-1'}
+    ]}
+/>
+```
+
+### Custom Styling
+
+**Example:**
+
+```svelte
+<AreaMap 
+    data="la_zip_sales" 
+    areaCol=zip_code
+    geoJsonUrl='path/to/your/geoJson'
+    geoId=ZCTA5CE10
+    value=sales
+    valueFmt=usd
+    height=250
+    color=#fff5d9
+    borderColor=#737373
+    borderWidth=0.5
+/>
+```
+
+### Custom Color Palette
+
+**Example:**
+
+```svelte
+<AreaMap 
+    data="la_zip_sales" 
+    areaCol=zip_code
+    geoJsonUrl='path/to/your/geoJson'
+    geoId=ZCTA5CE10
+    value=sales
+    valueFmt=usd
+    height=250
+    colorPalette="[
+        ['yellow', 'yellow'],
+        ['orange', 'orange'],
+        ['red', 'red'],
+        ['darkred', 'darkred'],
+    ]"
+/>
+```
+
+### Link Drilldown
+Pass in a `link` column to enable navigation on click of the point. These can be absolute or relative URLs
+
+**Example:**
+
+```svelte
+<AreaMap 
+    data="la_zip_sales" 
+    areaCol=zip_code
+    geoJsonUrl='path/to/your/geoJson'
+    geoId=ZCTA5CE10
+    value=sales
+    valueFmt=usd
+    height=250
+    link=link_col
+/>
+```
+
+### Use Map as Input
+Use the `name` prop to set an input name for the map - when a point is clicked, it will set the input value to that row of data
+
+**Example:**
+
+```svelte
+<AreaMap 
+    data="la_zip_sales" 
+    areaCol=zip_code
+    geoJsonUrl='path/to/your/geoJson'
+    geoId=ZCTA5CE10
+    value=sales
+    valueFmt=usd
+    height=250
+    name=my_area_map
+/>
+```
+
+*Click an area on the map to see the input value get updated:*
+
+#### Selected value for `{inputs.my_area_map}`: 
+
+<pre class="text-sm">{JSON.stringify(inputs.my_area_map, null, 2)}</pre>
+
+#### Selected value for `{inputs.my_area_map.zip_code}`: 
+  
+{inputs.my_area_map.zip_code}
+
+
+#### Filtered Data
+<DataTable data="filtered_areas">  	
+    <Column id=id/> 	
+    <Column id=zip_code fmt=id/> 	
+    <Column id=sales fmt=usd/> 	
+</DataTable>
+
+### Legends
+
+
+#### Categorical Legend
+
+**Example:**
+
+```svelte
+<AreaMap
+    data="grouped_locations"
+    lat=lat
+    long=long
+    value=Category
+    geoId=ZCTA5CE10
+    areaCol=zip_code
+/>
+```
+
+#### Custom Colors
+Set custom legend colors using the `colorPalette` prop to match the number of categories; excess categorical options will default to standard colors.
+
+**Example:**
+
+```svelte
+<AreaMap
+    data="grouped_locations"
+    lat=lat
+    long=long
+    value=Category
+    geoId=ZCTA5CE10
+    areaCol=zip_code
+    colorPalette={['#C65D47', '#5BAF7A', '#4A8EBA', '#D35B85', '#E1C16D', '#6F5B9A', '#4E8D8D']}
+/>
+```
+
+#### Scalar Legend
+
+**Example:**
+
+```svelte
+<AreaMap
+    data="grouped_locations"
+    lat=lat
+    long=long
+    value=sales
+    geoId=ZCTA5CE10
+    areaCol=zip_code
+    valueFmt=usd
+/>
+```
+
+#### Custom Colors
+Define scalar legend colors using the `colorPalette` prop, allowing specified colors to create a gradient based on the range of values.
+
+**Example:**
+
+```svelte
+<AreaMap
+    data="grouped_locations"
+    lat=lat
+    long=long
+    value=sales
+    geoId=ZCTA5CE10
+    areaCol=zip_code
+    colorPalette={['#C65D47', '#4A8EBA']}
+    valueFmt=usd
+/>
+```
+
+## Required GeoJSON Data Structure
+The GeoJSON data you pass to the map must be a feature collection. [See here for an example](https://gist.github.com/sgillies/1233327#file-geojson-spec-1-0-L50)
+
+## Map Resources
+
+
+Below are a selection of publically available GeoJSON files that may be useful for mapping. These are from the [Natural Earth Data](https://www.naturalearthdata.com) project, and hosted by [GeoJSON.xyz](https://geojson.xyz).
+
+### Country, State, and City Locations
+
+<DataTable data="useful_geojson_urls" rows=100>
+    <Column id=file/>
+    <Column id=category/>
+    <Column id=scale/>
+    <Column id=summary/>
+    <Column id=size fmt='0.0,," MB"'/>
+    <Column id=url contentType=link title=URL/>
+</DataTable>
+
+<Details title="All GeoJSON Files">
+
+<DataTable data="all_geojson_urls" rows=all compact>
+    <Column id=file/>
+    <Column id=category/>
+    <Column id=scale/>
+    <Column id=summary/>
+    <Column id=size fmt='0.0,," MB"'/>
+    <Column id=url contentType=link title=URL/>
+</DataTable>
+
+</Details>
+
+## Options
+
+### Areas
+
+| Property | Description | Required | Options |
+|----------|-------------|----------|---------|
+| data | Query result, referenced using curly braces | true | query name |
+| geoJsonUrl | Path to source geoJSON data from - can be a URL (see Map Resources) or a file in your project. If the file is in your `static` directory in the root of your project, reference it as `geoJsonUrl="/your_file.geojson"` | true | URL |
+| areaCol | Column in the data that specifies the area each row belongs to. | true | column name |
+| geoId | Property in the GeoJSON that uniquely identifies each feature. | true | geoJSON property name |
+| value | Column that determines the value displayed for each area (used for color scale) | false | column name |
+| valueFmt | Format string for displaying the value. | false | format string |
+| title | Title for the map | false | string |
+| subtitle | Subtitle - appears under the title | false | string |
+| ignoreZoom | Stops map from zooming out to show all data for this layer | false | true, false | false |
+
+### Color Scale
+
+| Property | Description | Options | Default |
+|----------|-------------|---------|---------|
+| colorPalette | Array of colors used for theming the areas based on data | array of colors | - |
+| min | Minimum value to use for the color scale. | number | min of value column |
+| max | Maximum value to use for the color scale. | number | max of value column |
+
+### Legend
+
+| Property | Description | Required | Options | Default |
+|----------|-------------|----------|---------|---------|
+| legend | Turns legend on or off | false | true, false | true |
+| legendType | Appends a categorical or scalar legend to the map | false | categorical, scalar | - |
+| legendPosition | Determines the legend's position on the map, with options provided | false | bottomLeft, topLeft, bottomRight, topRight | bottomLeft |
+
+### Interactivity
+
+| Property | Description | Options |
+|----------|-------------|---------|
+| link | URL to navigate to when a area is clicked. | URL |
+| name | Input name. Can be referenced on your page with `{inputs.my_input_name}` | string |
+
+### Styling
+
+| Property | Description | Options | Default |
+|----------|-------------|---------|---------|
+| color | Color for the areas. Use when you want all areas to be the same color. | CSS color value | - |
+| borderWidth | Width of the border around each area. | pixel value | 0.75 |
+| borderColor | Color of the border around each area. | CSS color value | white |
+| opacity | Opacity of the areas. | number between 0 and 1 | 0.8 |
+
+### Selected State
+
+| Property | Description | Options | Default |
+|----------|-------------|---------|---------|
+| selectedColor | When area is selected: Color for the areas. Use when you want all areas to be the same color. | CSS color value | - |
+| selectedBorderWidth | When area is selected: Width of the border around each area. | pixel value | 0.75 |
+| selectedBorderColor | When area is selected: Color of the border around each area. | CSS color value | white |
+| selectedOpacity | When area is selected: Opacity of the areas. | number between 0 and 1 | 0.8 |
+
+### Tooltips
+
+| Property | Description | Options | Default |
+|----------|-------------|---------|---------|
+| showTooltip | Whether to show tooltips | true, false | true |
+| tooltipType | Determines whether tooltips are activated by hover or click. | hover, click | hover |
+| tooltipClass | CSS class applied to the tooltip content. You can pass Tailwind classes into this prop to custom-style the tooltip | CSS class | - |
+| tooltip | Configuration for tooltips associated with each area. See below example for format | array of objects | - |
+
+#### `tooltip` example:
+
+```javascript
+tooltip="[
+    {id: 'zip_code', fmt: 'id', showColumnName: false, valueClass: 'text-xl font-semibold'",
+    {id: 'sales', fmt: 'eur', fieldClass: 'text-[grey]', valueClass: 'text-[green]'},
+    {id: 'zip_code', showColumnName: false, contentType: 'link', linkLabel: 'Click here', valueClass: 'font-bold mt-1'}
+]}
+```
+
+#### All options available in `tooltip`:
+- `id`: column ID
+- `title`: custom string to use as title of field
+- `fmt`: format to use for value
+- `showColumnName`: whether to show the column name. If `false`, only the value will be shown
+- `contentType`: currently can only be "link"
+- `linkLabel`: text to show for a link when contentType="link"
+- `formatColumnTitle`: whether to automatically uppercase the first letter of the title. Only applies when `title` not passed explicitly
+- `valueClass`: custom Tailwind classes to style the values
+- `fieldClass`: custom Tailwind classes to style the column names
+
+### Base Map
+
+| Property | Description | Options |
+|----------|-------------|---------|
+| basemap | URL template for the basemap tiles. | URL |
+| attribution | Attribution text to display on the map (e.g., "© OpenStreetMap contributors"). | text |
+| title | Optional title displayed above the map. | text |
+| startingLat | Starting latitude for the map center. | latitude coordinate |
+| startingLong | Starting longitude for the map center. | longitude coordinate |
+| startingZoom | Initial zoom level of the map. | number (1 to 18) |
+| height | Height of the map in pixels. | pixel value | 300 |

package/dist/docs/data_apps/components/maps/base-map.md

@@ -0,0 +1,269 @@
+---
+title: Base Map
+description: Combine multiple map layers including areas, points, and bubbles.
+---
+
+Combine multiple map layers including areas, points, and bubbles.
+
+**Example:**
+
+```html
+<BaseMap>
+  <Areas data="la_zip_sales" geoId=ZCTA5CE10 areaCol=zip_code value=sales valueFmt=usd/>
+  <Points data="la_locations" lat=lat long=long color=#179917/>
+</BaseMap>
+```
+
+
+## Overview
+The BaseMap component provides a flexible and extensible way to create maps with multiple layers. This component serves as the foundation for AreaMap, PointMap, and BubbleMap.
+
+Within BaseMap, you can add layers using the following components:
+- `<Areas/>`
+- `<Points/>`
+- `<Bubbles/>`
+
+## Examples
+
+See the pages for [Area Map](/components/maps/area-map), [Point Map](/components/maps/point-map), and [Bubble Map](/components/maps/bubble-map) for examples specific to those layers. The same options can be applied to the layer components within BaseMap.
+
+### Adding Multiple Layers
+
+**Example:**
+
+```svelte
+<BaseMap>
+  <Areas 
+    data="la_zip_sales"
+    areaCol=zip_code
+    geoJsonUrl="path/to/your/geoJSON"
+    geoId=ZCTA5CE10
+    value=sales
+    valueFmt=usd
+  />
+  <Bubbles 
+    data="la_locations"
+    lat=lat
+    long=long
+    size=sales
+    sizeFmt=usd
+    value=sales
+    valueFmt=usd
+    pointName=point_name
+    colorPalette={['yellow','orange','red','darkred']}
+    opacity=0.5
+  />
+</BaseMap>
+```
+
+### Custom Basemap
+You can add a different basemap by passing in a basemap URL. You can find examples here: https://leaflet-extras.github.io/leaflet-providers/preview/
+
+**Example:**
+
+```svelte
+<BaseMap basemap="`https://tile.openstreetmap.org/{z"/{x}/{y}.png`} attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'>
+    <Points 
+        data="la_locations"
+        lat=lat
+        long=long
+        value=sales
+        valueFmt=usd
+        pointName=point_name
+        color=violet
+        borderColor=black
+        borderWidth=2
+    />
+</BaseMap>
+```
+
+### Custom Tooltip
+
+#### `tooltipType=hover`
+
+**Example:**
+
+```svelte
+<BaseMap>
+    <Areas 
+        data="la_zip_sales" 
+        areaCol=zip_code
+        geoJsonUrl='/geo-json/ca_california_zip_codes_geo_1.min.json'
+        geoId=ZCTA5CE10
+        value=sales
+        valueFmt=usd
+        height=250
+        tooltip="[
+            {id: 'zip_code', fmt: 'id', showColumnName: false, valueClass: 'text-xl font-semibold'",
+            {id: 'sales', fmt: 'eur', fieldClass: 'text-[grey]', valueClass: 'text-[green]'},
+            {id: 'zip_code', showColumnName: false, contentType: 'link', linkLabel: 'Click here', valueClass: 'font-bold mt-1'}
+        ]}
+    />
+</BaseMap>
+```
+
+#### With clickable link and `tooltipType=click`
+
+**Example:**
+
+```svelte
+<BaseMap>
+    <Areas 
+        data="la_zip_sales" 
+        areaCol=zip_code
+        geoJsonUrl='/geo-json/ca_california_zip_codes_geo_1.min.json'
+        geoId=ZCTA5CE10
+        value=sales
+        valueFmt=usd
+        height=250
+        tooltipType=click
+        tooltip="[
+            {id: 'zip_code', fmt: 'id', showColumnName: false, valueClass: 'text-xl font-semibold'",
+            {id: 'sales', fmt: 'eur', fieldClass: 'text-[grey]', valueClass: 'text-[green]'},
+            {id: 'link_col', showColumnName: false, contentType: 'link', linkLabel: 'Click here', valueClass: 'font-bold mt-1'}
+        ]}
+    />
+</BaseMap>
+```
+
+## Map Resources
+
+
+Below are a selection of publically available GeoJSON files that may be useful for mapping. These are from the [Natural Earth Data](https://www.naturalearthdata.com) project, and hosted by [GeoJSON.xyz](https://geojson.xyz).
+
+### Country, State, and City Locations
+
+| file | category | scale | summary | size | url |
+|------|----------|-------|---------|------|-----|
+| {useful_geojson_urls.file} | {useful_geojson_urls.category} | {useful_geojson_urls.scale} | {useful_geojson_urls.summary} | {useful_geojson_urls.size} | {useful_geojson_urls.url} |
+
+<details>
+<summary>All GeoJSON Files</summary>
+
+| file | category | scale | summary | size | url |
+|------|----------|-------|---------|------|-----|
+| {all_geojson_urls.file} | {all_geojson_urls.category} | {all_geojson_urls.scale} | {all_geojson_urls.summary} | {all_geojson_urls.size} | {all_geojson_urls.url} |
+
+</details>
+
+## Base Map Options
+
+| Property | Type | Description |
+|----------|------|-------------|
+| basemap | URL | URL template for the basemap tiles. |
+| attribution | text | Attribution text to display on the map (e.g., "© OpenStreetMap contributors"). |
+| title | text | Optional title displayed above the map. |
+| startingLat | latitude coordinate | Starting latitude for the map center. |
+| startingLong | longitude coordinate | Starting longitude for the map center. |
+| startingZoom | number (1 to 18) | Initial zoom level of the map. |
+| height | pixel value (default: 300) | Height of the map in pixels. |
+| title | string | Title for the map |
+| subtitle | string | Subtitle - appears under the title |
+
+## Layer Options
+
+### Areas
+Use the `<Areas/>` component to add an area layer
+
+| Property | Required | Type | Description |
+|----------|----------|------|-------------|
+| data | ✓ | query name | Query result, referenced using curly braces. |
+| geoJsonUrl | ✓ | URL | Path to source geoJSON data from - can be a URL (see [Map Resources](#map-resources)) or a file in your project. If the file is in your `static` directory in the root of your project, reference it as `geoJsonUrl="/your_file.geojson"` |
+| areaCol | ✓ | column name | Column in the data that specifies the area each row belongs to. |
+| geoId | ✓ | geoJSON property name | Property in the GeoJSON that uniquely identifies each feature. |
+| value | | column name | Column that determines the value displayed for each area (used for color scale). |
+| valueFmt | | format string | Format string for displaying the value. |
+| ignoreZoom | | true/false (default: false) | Stops map from zooming out to show all data for this layer |
+
+### Points
+Use the `<Points/>` component to add an area layer
+
+| Property | Required | Type | Description |
+|----------|----------|------|-------------|
+| data | ✓ | query name | Query result, referenced using curly braces. |
+| lat | ✓ | column name | Column containing latitude values. |
+| long | ✓ | column name | Column containing longitude values. |
+| value | | column name | Column that determines the value displayed at each point. |
+| valueFmt | | format string | Format string for displaying the value. |
+| pointName | | column name | Column containing the names/labels of the points - by default, this is shown as the title of the tooltip. |
+| ignoreZoom | | true/false (default: false) | Stops map from zooming out to show all data for this layer |
+
+### Bubbles
+Use the `<Bubbles/>` component to add an area layer
+
+| Property | Required | Type | Description |
+|----------|----------|------|-------------|
+| data | ✓ | query name | Query result, referenced using curly braces. |
+| lat | ✓ | column name | Column containing latitude values. |
+| long | ✓ | column name | Column containing longitude values. |
+| size | ✓ | column name | Column that determines the size displayed for each point. |
+| sizeFmt | | format string | Format string for displaying the size value in tooltips. |
+| maxSize | | number (default: 20) | Maximum size of the bubbles. |
+| value | | column name | Column that determines the value displayed at each point (used for color scale). |
+| valueFmt | | format string | Format string for displaying the value. |
+| pointName | | column name | Column containing the names/labels of the points - by default, this is shown as the title of the tooltip. |
+| paneType | | text | Specifies the type of pane where the bubbles will be rendered. |
+| z | | number | Represents the z-index value for the pane, controlling its stacking order relative to other panes (higher values are on top, e.g., z=2 is above z=1). |
+| ignoreZoom | | true/false (default: false) | Stops map from zooming out to show all data for this layer |
+
+### Common Layer Options
+
+#### Color Scale
+
+| Property | Type | Description |
+|----------|------|-------------|
+| colorPalette | array of colors | Array of colors used for theming the points or areas based on data. |
+| min | number (default: min of value column) | Minimum value to use for the color scale. |
+| max | number (default: max of value column) | Maximum value to use for the color scale. |
+
+#### Interactivity
+
+| Property | Type | Description |
+|----------|------|-------------|
+| link | URL | URL to navigate to when a point or area is clicked. |
+| name | string | Input name. Can be referenced on your page with {inputs.my_input_name}. |
+
+#### Styling
+| Property | Type | Description |
+|----------|------|-------------|
+| color | CSS color value | Color for the points or areas. Use when you want all points or areas to be the same color. |
+| borderWidth | pixel value | Width of the border around each point or area. |
+| borderColor | CSS color value | Color of the border around each point or area. |
+| opacity | number between 0 and 1 | Opacity of the points or areas. |
+
+#### Selected State
+| Property | Type | Description |
+|----------|------|-------------|
+| selectedColor | CSS color value | When point or area is selected: Color for the points or areas. |
+| selectedBorderWidth | pixel value | When point or area is selected: Width of the border around each point or area. |
+| selectedBorderColor | CSS color value | When point or area is selected: Color of the border around each point or area. |
+| selectedOpacity | number between 0 and 1 | When point or area is selected: Opacity of the points or areas. |
+
+#### Tooltips
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| showTooltip | true/false | true | Whether to show tooltips. |
+| tooltipType | hover/click | hover | Determines whether tooltips are activated by hover or click. |
+| tooltipClass | CSS class | | CSS class applied to the tooltip content. You can pass Tailwind classes into this prop to custom-style the tooltip. |
+| tooltip | array of objects | | Configuration for tooltips associated with each area. See below example for format |
+
+#### `tooltip` example:
+
+```javascript
+tooltip="[
+    {id: 'zip_code', fmt: 'id', showColumnName: false, valueClass: 'text-xl font-semibold'",
+    {id: 'sales', fmt: 'eur', fieldClass: 'text-[grey]', valueClass: 'text-[green]'},
+    {id: 'zip_code', showColumnName: false, contentType: 'link', linkLabel: 'Click here', valueClass: 'font-bold mt-1'}
+]}
+```
+
+#### All options available in `tooltip`:
+- `id`: column ID
+- `title`: custom string to use as title of field
+- `fmt`: format to use for value
+- `showColumnName`: whether to show the column name. If `false`, only the value will be shown
+- `contentType`: currently can only be "link"
+- `linkLabel`: text to show for a link when contentType="link"
+- `formatColumnTitle`: whether to automatically uppercase the first letter of the title. Only applies when `title` not passed explicitly
+- `valueClass`: custom Tailwind classes to style the values
+- `fieldClass`: custom Tailwind classes to style the column names