Skip to content

Commit

Permalink
docs: review and improve references (#110)
Browse files Browse the repository at this point in the history
  • Loading branch information
@AdriSolid
AdriSolid committed Mar 10, 2021
1 parent 2fda4ba commit 28f5b83
Show file tree
Hide file tree
Showing 7 changed files with 116 additions and 150 deletions.
2 changes: 1 addition & 1 deletion DEVELOPERS.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Developers

This is a monorepo, made with lerna and yarn workspaces.
This is a monorepo, made with lerna and yarn workspaces. We recommend node version >=14.X

Clone and execute
```
Expand Down
53 changes: 16 additions & 37 deletions packages/react-api/reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,6 @@

Set of functions that allow to work with CARTO APIs.

## buildQueryFilters ⇒ <code>string</code>

Returns a SQL query applying a set of filters.

**Returns**: <code>string</code> - SQL query

| Param | Type | Description |
| ------- | ------------------- | ------------------------- |
| data | <code>string</code> | Dataset name or SQL query |
| filters | <code>Object</code> | Filters to be applied |

## executeSQL ⇒ <code>Object</code>

Executes a SQL query against [CARTO SQL API](https://carto.com/developers/sql-api/)
Expand All @@ -29,32 +18,6 @@ Executes a SQL query against [CARTO SQL API](https://carto.com/developers/sql-ap
| opts | <code>Object</code> | Additional options for the HTTP request |
| opts.format | <code>string</code> | Output format (i.e. geojson) |

## getUserDatasets ⇒ <code>Object</code>

Get the lists of datasets for the user by performing a request to CARTO datasets API

**Returns**: <code>Object</code> - List of datasets

| Param | Type | Description |
| ----------------------------- | ------------------- | --------------------------------------- |
| credentials | <code>Object</code> | CARTO user credentials |
| credentials.username | <code>string</code> | CARTO username |
| credentials.apiKey | <code>string</code> | CARTO API Key |
| credentials.serverUrlTemplate | <code>string</code> | CARTO server URL template |
| opts | <code>Object</code> | Additional options for the HTTP request |
| opts.format | <code>string</code> | Output format (i.e. geojson) |

## buildFeatureFilter ⇒ <code>number|boolean</code>

Returns a number (0-1) or a boolean checking wether a feature should be rendered by widgets and displayed on the map

**Returns**: <code>number|boolean</code> - Feature that passes the filter

| Param | Type | Default | Description |
| ------- | ------------------- | --------- | ------------------------------------ |
| filters | <code>Object</code> | {} | Filters to be applied |
| type | <code>string</code> | 'boolean' | Output type: number (0-1) or boolean |

## useCartoLayerProps ⇒ <code>Object</code>

Returns required default props for layers. It manages filtering and viewport changes.
Expand All @@ -68,3 +31,19 @@ Returns required default props for layers. It manages filtering and viewport cha
| props.extensions | <code>[Object]</code> | Bonus features to add to the core deck.gl layers |
| props.updateTriggers | <code>Object</code> | Tells deck.gl exactly which attributes need to change, and when |
| props.updateTriggers.getFilterValue | <code>Object</code> | Updating `getFilterValue` accessor when new filters come |

## SourceTypes

Enum for the different types of @deck.gl/carto sources

**Kind**: global enum
**Read only**: true

<dl>
<dt><a href="#SQL">SQL</a></dt>
<dd><p>sql</p>
</dd>
<dt><a href="#BIGQUERY">BIGQUERY</a></dt>
<dd><p>bigquery</p>
</dd>
</dl>
70 changes: 70 additions & 0 deletions packages/react-core/reference.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# Core

## aggregationFunctions ⇒ <code>Object</code>

Contains aggregation functions for widgets and layers, see [AggregationTypes](#aggregationtypes)

**Returns**: <code>Object</code> - Aggregation functions

## groupValuesByColumn ⇒ <code>Array</code>

Makes groups from features based in a operation

**Returns**: <code>Array</code> - Grouped values

| Param | Type | Default | Description |
| ------- | ------------------- | --------- | ------------------------------------ |
| data | <code>Array</code> | | Features for calculations |
| valuesColumn | <code>string</code> | | Quantitative column for grouping |
| keysColumn | <code>string</code> | | Qualitative column for grouping |
| operation | <code>string</code> | | Operation for groups calculations, see [AggregationTypes](#aggregationtypes) |

## histogram ⇒ <code>Array</code>

Makes an array of numeric values as histogram data from features

**Returns**: <code>Array</code> - Histogram data

| Param | Type | Default | Description |
| ------- | ------------------- | --------- | ------------------------------------ |
| features | <code>Array</code> | | Features for calculations |
| columnName | <code>string</code> | | Qualitative column for grouping |
| ticks | <code>Array</code> | | Array of numeric intervals |
| operation | <code>string</code> | | Operation for groups calculations, see [AggregationTypes](#aggregationtypes) |

## viewportFeatures ⇒ <code>Array</code>

Handles all tiles features and returns the current viewport ones

**Returns**: <code>Array</code> - Features in viewport

| Param | Type | Default | Description |
| ------- | ------------------- | --------- | ------------------------------------ |
| tiles | <code>Array</code> | | deck.gl tiles |
| viewport | <code>Array</code> | | Viewport bounds |
| uniqueIdProperty | <code>string</code> | | Unique feature id property |

## AggregationTypes

Enum for the different types of aggregations available for widgets

**Kind**: global enum
**Read only**: true

<dl>
<dt><a href="#COUNT">COUNT</a></dt>
<dd><p>Count</p>
</dd>
<dt><a href="#AVG">AVG</a></dt>
<dd><p>Average</p>
</dd>
<dt><a href="#MIN">MIN</a></dt>
<dd><p>Minimum</p>
</dd>
<dt><a href="#MAX">MAX</a></dt>
<dd><p>Maximum</p>
</dd>
<dt><a href="#SUM">SUM</a></dt>
<dd><p>Sum</p>
</dd>
</dl>
44 changes: 0 additions & 44 deletions packages/react-core/src/filters/FilterQueryBuilder.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,47 +50,3 @@ export const filtersToSQL = (filters = {}) => {

return result.length ? `WHERE (${result.join(') AND (')})` : '';
};

/* export const viewportToSQL = (viewport) => {
const bboxes = getBoundingBoxes(viewport);
const queries = bboxes.map((bbox) => {
return `ST_Intersects(
the_geom_webmercator,
ST_Transform(ST_MakeEnvelope(${bbox.join(',')}, 4326), 3857)
)`;
});
return queries.join(' OR ');
};
function getBoundingBoxes([west, south, east, north]) {
var bboxes = [];
if (east - west >= 360) {
bboxes.push([-180, south, 180, north]);
} else if (west >= -180 && east <= 180) {
bboxes.push([west, south, east, north]);
} else {
bboxes.push([west, south, 180, north]);
// here we assume west,east have been adjusted => west >= -180 => east > 180
bboxes.push([-180, south, east - 360, north]);
}
return bboxes;
} */

/**
* Returns a SQL query applying a set of filters
*
* @param { string } data - Dataset name or SQL query
* @param { Object } filters - Filters to be applied
* @returns { string } - SQL query
*/
/* export const buildQueryFilters = ({ data, filters }) => {
return `
SELECT *
FROM (${data}) as q
${filtersToSQL(filters)}
`;
}; */
25 changes: 25 additions & 0 deletions packages/react-redux/reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,31 @@ Action to remove the viewport features to a specific source
| ---------- | ------------------- | ----------------------------------------------------- |
| {sourceId} | <code>string</code> | id of the source to remove the viewport features from |

### setWidgetLoadingState

Action to set the widget loading state to a specific one

| Param | Type | Description |
| ---------- | ------------------- | ----------------- |
| {widgetId} | <code>string</code> | id of the widget |
| {isLoading} | <code>boolean</code> | loading state |

### removeWidgetLoadingState

Action to remove a specific widget loading state

| Param | Type | Description |
| ---------- | ------------------- | ----------------- |
| {widgetId} | <code>string</code> | id of the widget |

### setAllWidgetsLoadingStates

Action to set the all the widgets loading state at once

| Param | Type | Description |
| ---------- | ------------------- | ----------------- |
| {areLoading} | <code>boolean</code> | loading state |

## OAuth Slice

### createOauthCartoSlice
Expand Down
45 changes: 4 additions & 41 deletions packages/react-widgets/reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Renders a `<CategoryWidget />` component
| [props.formatter] | [<code>formatterCallback</code>](#formatterCallback) | | Function to format each value returned. |
| [props.viewportFilter] | <code>boolean</code> | <code>true</code> | Defines whether filter by the viewport or globally. |
| [props.onError] | [<code>errorCallback</code>](#errorCallback) | | Function to handle error messages from the widget. |
| [props.wrapperProps] | <code>Object</code> | | Extra props to pass to [WrapperWidgetUI](https://storybook-react.carto.com/?path=/docs/widgets-wrapperwidgetui--default) |

## FormulaWidget

Expand All @@ -32,6 +33,7 @@ Renders a `<FormulaWidget />` component
| [props.formatter] | [<code>formatterCallback</code>](#formatterCallback) | | Function to format each value returned. |
| [props.viewportFilter] | <code>boolean</code> | <code>true</code> | Defines whether filter by the viewport or globally. |
| [props.onError] | [<code>errorCallback</code>](#errorCallback) | | Function to handle error messages from the widget. |
| [props.wrapperProps] | <code>Object</code> | | Extra props to pass to [WrapperWidgetUI](https://storybook-react.carto.com/?path=/docs/widgets-wrapperwidgetui--default)

## GeocoderWidget

Expand Down Expand Up @@ -61,6 +63,7 @@ Renders a `<HistogramWidget />` component
| [props.formatter] | [<code>formatterCallback</code>](#formatterCallback) | | Function to format tooltip and Y axis values. |
| [props.viewportFilter] | <code>boolean</code> | <code>true</code> | Defines whether filter by the viewport or globally. |
| [props.onError] | [<code>errorCallback</code>](#errorCallback) | | Function to handle error messages from the widget. |
| [props.wrapperProps] | <code>Object</code> | | Extra props to pass to [WrapperWidgetUI](https://storybook-react.carto.com/?path=/docs/widgets-wrapperwidgetui--default)

## PieWidget

Expand All @@ -80,44 +83,4 @@ Renders a `<PieWidget />` component
| [props.viewportFilter] | <code>boolean</code> | <code>true</code> | Defines whether filter by the viewport or not. |
| props.height | <code>string</code> | <code>300px</code> | Height of the chart in CSS format. |
| [props.onError] | [<code>errorCallback</code>](#errorCallback) | | Function to handle error messages from the widget. |

## AggregationTypes

Enum for the different types of aggregations available for widgets

**Kind**: global enum
**Read only**: true

<dl>
<dt><a href="#COUNT">COUNT</a></dt>
<dd><p>Count</p>
</dd>
<dt><a href="#AVG">AVG</a></dt>
<dd><p>Average</p>
</dd>
<dt><a href="#MIN">MIN</a></dt>
<dd><p>Minimum</p>
</dd>
<dt><a href="#MAX">MAX</a></dt>
<dd><p>Maximum</p>
</dd>
<dt><a href="#SUM">SUM</a></dt>
<dd><p>Sum</p>
</dd>
</dl>

## SourceTypes

Enum for the different types of @deck.gl/carto sources

**Kind**: global enum
**Read only**: true

<dl>
<dt><a href="#SQL">SQL</a></dt>
<dd><p>sql</p>
</dd>
<dt><a href="#BIGQUERY">BIGQUERY</a></dt>
<dd><p>bigquery</p>
</dd>
</dl>
| [props.wrapperProps] | <code>Object</code> | | Extra props to pass to [WrapperWidgetUI](https://storybook-react.carto.com/?path=/docs/widgets-wrapperwidgetui--default) |
27 changes: 0 additions & 27 deletions packages/react-widgets/src/index.js
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,3 @@
/**
* @typedef {Object} FormattedValue
* @property {string} value - The formatted value
* @property {string} prefix - The prefix to apply to the value
* @property {string} suffix - The suffix to apply to the value
*/

/**
* @typedef {Object} ErrorObject
* @property {string} name - The error name
* @property {string} message - The error message
*/

/**
* Formatter function to apply on a widget value
*
* @callback formatterCallback
* @param {number} value - Number to format
* @returns {(string|FormattedValue)} - String with the whole formatted value or a FormattedValue object containing the value and optional an optional prefix or suffix
*/

/**
* Error handler
* @callback errorCallback
* @param {ErrorObject} error - Error object to handle
*/

export { default as CategoryWidget } from './widgets/CategoryWidget';
export { default as FormulaWidget } from './widgets/FormulaWidget';
export { default as GeocoderWidget } from './widgets/GeocoderWidget';
Expand Down

0 comments on commit 28f5b83

Please sign in to comment.