@tidepool/viz 1.38.0 → 1.39.0

package/docs/misc/CommonProps.md

@@ -1,31 +0,0 @@
-## Common props in Tidepool data visualization code
-
-Several of the pieces of [the state common to most, if not all, of Tidepool's data visualization views](../FeatureOverview.md#shared-state) are most often encountered in the code as props passed to React components. This page provides a quick reference describing the canonical forms of these pieces of state since they occur and are used (for example: as a parameter in a utility function) **very** frequently.
-
-- [`bgPrefs`](#bgPrefs)
-- [`timePrefs`](#timePrefs)
-
-### `bgPrefs`
-
-`bgPrefs` is an object with two properties: `bgUnits` and `bgBounds`. Sometimes these component properties are passed around on their own, and sometimes `bgPrefs` is passed around as a whole. (As we increase our commitment to support for mmol/L as well as mg/dL blood glucose units, it will probably be necessary to access both `bgUnits` and `bgBounds` simultaneously most of the time, so it is probably a good idea to just get used to passing around `bgPrefs` as a whole.)
-
-`bgUnits` is a String value that can be either `mg/dL` or `mmol/L`. To avoid typos and capitalization errors, we export a constant for each of these strings from src/utils/constants.js; use them with `import { MGDL_UNITS, MMOLL_UNITS } from 'path/to/utils/constants'`.
-
-`bgBounds` is an Object with five numerical fields:
-- `veryLowThreshold` encodes the threshold (logic is <) for encoding a blood glucose value as "very low"
-- (a value >= `veryLowThreshold` and < `targetLowerBound` is "low")
-- `targetLowerBound` encodes the lower bound for the user's target blood glucose range; logic is >= the threshold is "target"
-- `targetUpperBound` encodes the upper bound for the user's target blood glucose range; logic is <= the threshold is "target"
-- (a value > `targetUpperBound` and <= `veryHighThreshold` is "high")
-- `veryHighThreshold` encodes the threshold (logic is >) for encoding a blood glucose value as "very high"
-- `clampThreshold` encodes the value at which we clamp the blood glucose scale (logic is >); read about clamping scales in [the d3-scale documentation](https://github.com/d3/d3-scale#continuous_clamp 'd3-scale: clamp()')
-
-The function `classifyBgValue` exported from the blood glucose utilities in `src/utils/bloodglucose.js` will return the classification for any blood glucose value given the `value` and the `bgBounds`. (See also [all the API documentation for blood glucose utility functions](../../src/utils/apidocs/bloodglucose.md).)
-
-### `timePrefs`
-
-`timePrefs` is an object with two properties: `timezoneAware` and `timezoneName`. The `timezoneAware` property is a simple Boolean indicating whether or not the user wants to view data in timezone-aware mode; `timezoneAware` defaults to `true`. Because the extraction of a named timezone depends in part on the value of `timezoneAware`[^a], `timePrefs` should **always** be passed around as an entire object, and the utility function `getTimezoneFromTimePrefs` exported from the datetime utilities in `src/utils/datetime.js` should be used to extract the timezone String when required. (See also [all the API documentation for datetime utility functions](../../src/utils/apidocs/datetime.md).)
-
-`timezoneName` is a String timezone that the [Moment.js](https://momentjs.com/ 'Moment.js') datetime utility library recognizes. Moment.js in turn recognizes all timezones from the [IANA Time Zone Database](https://www.iana.org/time-zones 'IANA Time Zone Database).
-
-[^a]: In brief, if `timezoneAware` is `false`, then `UTC` is used for the timezone String in all circumstances and methods where a timezoe String is required.

package/docs/misc/Docs.md

@@ -1,40 +0,0 @@
-## Working on viz docs
-
-This repository's docs are set up like all of Tidepool's front-end and docs repos. For details on this setup, see the [general guidance for docs setup & workflow](http://developer.tidepool.io/docs/docs/workflow.html 'Tidepool docs setup & workflow').
-
-### Setup
-
-To summarize briefly, the steps you will need to have done in order to use the `npm` scripts configured for docs work in the repository are:
-
-- clone a second copy of this repository as a subdirectory `web/`; you can do this from your `viz/` directory with `git clone git@github.com:tidepool-org/viz.git web`
-- switch to the `gh-pages` branch in the embedded clone and delete the `master` branch
-
-```bash
-$ cd web/
-$ git checkout gh-pages
-$ git branch -d master
-```
-
-### Regenerating
-
-We generate Markdown documentation for the utilities in `src/utils/` from the [JSDoc comments](http://usejsdoc.org/ 'JSDoc') included with all exports and/or functions. The [README](../../src/utils/README.md) in `src/utils/` documents how to regenerate these Markdown files; this regeneration should be performed whenever you've added or updated a utility functon and/or the JSDoc for that utility.
-
-### Publishing
-
-To publish revised docs and/or Storybooks, run the following from the root of the `viz/` directory:
-
-For updating just docs (including the `adidocs/` in `src/utils/`) by building the static [GitBook](https://www.gitbook.com/ 'GitBook') site that we publish to GitHub Pages:
-
-```bash
-$ npm run build-docs
-```
-
-Then `cd web/` and review the unstaged changes. Stage & commit the changes you want to make. Finally, "publish" to GitHub pages by pushing to the upstream `gh-pages` branch.
-
-For updating the Storybooks (again from the root of `viz/`:
-
-```bash
-$ npm run build-storybooks
-```
-
-Again navigate into the embedded `web/` directory to review, stage, commit, and push the changes upstream.

package/docs/misc/README.md

@@ -1,5 +0,0 @@
-## Miscellaneous documents
-
-+ [common props](./CommonProps.md)
-+ [this repo's documentation](./Docs.md)
-+ [time rendering modes](./TimeRenderingModes.md)

package/docs/misc/TimeRenderingModes.md

@@ -1,35 +0,0 @@
-## Time rendering modes
-
-Tidepool supports two rendering "modes" for diabetes device data & notes visualized via the code in this repository (as well as legacy [tideline](https://github.com/tidepool-org/tideline 'GitHub: @tidepool-org/tideline') code): the default timezone-aware rendering and timezone-naïve rendering. This document explains and demonstrates the difference(s) between these and the utility of each.
-
-### Background: `time` and `deviceTime`
-
-Two of the time-related fields in the [Tidepool data model for diabetes device data](http://developer.tidepool.io/data-model/device-data/common.html 'Tidepool data model docs: common fields') are important to understand as background to the discussion presented in this document; these are [`time`](http://developer.tidepool.io/data-model/device-data/common.html#time 'Tidepool data model docs: time') and [`deviceTime`](http://developer.tidepool.io/data-model/device-data/common.html#devicetime 'Tidepool data model docs: deviceTime').
-
-`deviceTime` is what it sounds like: the display time on the diabetes device at the time the event occurred. For almost every current Tidepool data source, this is *the* (only) time value that we extract directly from a device's memory.[^a] In the base case, this should be an accurate representation of the clock time for the user—that is, localized to the timezone the user is currently in or was in at the time of the event, assuming the user updates the device display time when switching timezones. Of course, since the display time settings on diabetes devices are subject to manual user control, user error can occur, occasionally with drastic results. We have seen cases where users have accidentally set the display time on their device to the wrong a.m. or p.m. (resulting in `deviceTime`s that are off by exactly twelve hours), to the wrong month, and—more often than one might expect!—to the wrong *year*.
-
-[Bootstrapping to UTC (BtUTC)](http://developer.tidepool.io/chrome-uploader/docs/BootstrappingToUTC.html) is the algorithm we have developed to correct for these types of user errors (as well as the more common challenge of handling the switch between Daylight Saving time and standard time) by inferring the UTC time for each event so that we can plot all the data from a user's many diabetes devices on the same scale with all the data properly aligned. This is the value stored in the `time` field.
-
-### Timezone-aware rendering
-
-The default rendering mode is timezone-aware. This means that all events are rendered on a UTC time scale using the `time` value to determine the placement along this scale. Whenever a time-related value needs to be surfaced to the user, we apply a timezone to this `time` value and surface the result, as this is our best guess at the corresponding local display time for the user (the exception is if the user was traveling in a different timezone for a span of data). Currently (as of November, 2016) we use the `timezone` from the user's most recent [upload metadata](http://developer.tidepool.io/data-model/device-data/types/upload.html#timezone 'Tidepool data model docs: upload.timezone') as the timezone to be applied to the `time` values across the entire history of the user's diabetes device data. This *does* adjust as expected for Daylight Saving time, but does *not* adjust for travel across timezones if the user changed their device display time when switching timezones. In the future, instead of pulling the display timezone from the most recent upload metadata we plan to support a "default timezone for data display" along with other display settings for each user persisted to Tidepool's servers, including preferred blood glucose units (mg/dL or mmol/L) and a user-defined target range for blood glucose values.
-
-Features of timezone-aware rendering:
-
-- no gaps or overlaps in data
-- all data aligns *except* BGM data in cases of user error setting the BGM time or travel across timezones (because no BGM is currently bootstrap-able)
-
-### Timezone-naïve rendering
-
-A second rendering mode is available (currently, as of November, 2016) by adding a query parameter to the URL: `?timezone=None` (any string that does not correspond to an actual [IANA timezone](https://www.iana.org/time-zones 'IANA: Time Zone Database') may take the place of `None` here as long as it is not a falsey value in JavaScript such as `null`). This rendering mode also renders the events on the same UTC time scale but using the `deviceTime` *as if it were a true UTC value*. In order to "spoof" a true UTC value from a `deviceTime`, we simply add the string suffix `Z` denoting UTC or "Zulu" time to the value—that is, a `deviceTime` of `2016-03-15T12:00:00` with no timezone offset information becomes the UTC string `2016-03-15T12:00:00Z`. (The technical reason for performing this string transformation is demonstrated below.)
-
-To date, timezone-naïve mode has been most valuable as a debugging tool when investigating data quality issues reported by users. For users whose situations fall into edge cases that BtUTC does not handle, timezone-naïve rendering may also be the *only* method available to see all diabetes device data aligned.
-
-Features of timezone-naïve rendering:
-
-- gaps and overlaps appear in the data whenever the user has made a significant (i.e., non-["clock drift"](http://developer.tidepool.io/chrome-uploader/docs/BootstrappingToUTC.html#adjustments-for-clock-drift 'BtUTC documentation: Adjustments for clock drift')) change to the display time
-- all data aligns as long as there were no user error(s) setting one or more device display times and the user consistently updated device display time across *all* devices when switching timezones and entering/exiting Daylight Saving time (if applicable)
-
-* * * * *
-
-[^a]: The exception is Dexcom G5 data imported from HealthKit through one of Tidepool's iOS applications; in this case, we have *no* `deviceTime`, only a true UTC timestamp—our `time` field—extracted from the iOS HealthKit data model.

package/docs/views/README.md

@@ -1,6 +0,0 @@
-## per-view documentation
-
-Following Tidepool's general [documentation guidelines](http://developer.tidepool.io/docs/docs/guidelines.html 'Tidepool Developer Portal: Docs Guideslines'), included here is documentation regarding the implementation of each major data "view" implemented in this repository for inclusion in Tidepool's web application blip.
-
-- [Device Settings view](../../src/components/settings/README.md)
-- [Trends view](./Trends.md)

package/docs/views/Trends.md

@@ -1,130 +0,0 @@
-## Trends view
-
-Table of contents:
-
-- [user experience](#user-experience)
-- [architecture](#architecture)
-    + [component hierarchy](#component-hierarchy)
-- [layout](#layout)
-- [tech debt](#tech-debt)
-
-### 👱🏾 User experience
-
-There are two versions of the Trends view, one for displaying trend information based on fingerstick blood glucose data and the other for displaying trend information based on CGM data. The BGM version was developed first, and the CGM version is a more recent addition. A 14-day span of data is the default for this view, although the user can toggle to 7 days or 28 days using selectors displayed in the upper left corner of the display. (In the upper right of the display, the user can toggle days of the week such as Monday, Tuesday, etc. or weekdays vs. weekends off and on.) Both the CGM and CGM versions group all data in the selected span of time by time of day in an effort to show how blood glucose varies for the PwD by time of day. On the BGM version where the data is quite sparse, the data is grouped into three-hour "bins," and on the CGM version thirty-minute bins are used.
-
-**CGM Trends as of March, 2017**
-
-![CGM Trends](./images/cgm_trends.png)
-
-**BGM Trends as of March, 2017**
-
-![BGM Trends](./images/bgm_trends.png)
-
-Like on the Daily view, hovering over various items in the display will produce a tooltip with more information. In addition, hovering on a segment of a time slice on the CGM version will expose all of the CGM daily sensor traces that intersect with that segment after a short delay (i.e., the pointer must remain on the same segment for a threshold of milliseconds before the exposure of traces is triggered).
-
-**BGM Date Line Hover**
-
-![BGM Date Line Hover](./images/bgm_trends_date_line_hover.png)
-
-**BGM Individual `smbg` Hover**
-
-![BGM Individual `smbg` Hover](./images/bgm_trends_smbg_hover.png)
-
-**BGM Range Box Hover**
-
-![BGM Range Box Hover](./images/bgm_trends_range_hover.png)
-
-**CGM Segment Hover**
-
-![CGM Segment Hover](./images/cgm_trends_segment_hover.gif)
-
-**CGM Segment Hover + Hold**
-
-![CGM Segment Hover + Hold](./images/cgm_trends_segment_hover_hold.png)
-
-**CGM Segment Hover + Hold on `cbg`**
-
-![CGM Segment Hover + Hold on `cbg`](./images/cgm_trends_segment_hover_hold_cbg.png)
-
-### 🏛️ Architecture
-
-Currently only the data visualization itself for the BGM and CGM versions of the Trends view are implemented in this repository: code in blip is still being used for the 7, 14, and 28 days domain size selectors, the day of the week selectors, and of course the visualization sub-header that provides navigation between the views and along the datetime dimension. This makes the interface(s) between the blip and viz code a bit messier than they should be.
-
-![Trends view locations of code for elements](./images/trends_code_locations.png)
-
-#### Component hierarchy
-
-**CGM Trends**
-
-```
-└── PatientData
-    └── Trends
-        ├── TidelineHeader
-        ├── TrendsSubNav
-        ├── <div className="patient-data-content">
-        │   ├── <div id="tidelineContainer">
-        │   │   └── TrendsContainer
-        │   │       └── TrendsSVGContainer (wrapped in DimensionsHOC)
-        │   │           ├── Background
-        │   │           ├── XAxisLabels
-        │   │           ├── XAxisTicks
-        │   │           ├── YAxisLabels
-        │   │           ├── <g id="cbgTrends">
-        │   │           │   ├── CBGSlicesContainer
-        │   │           │   │   └── <g id="cbgSlices">{48 CBGSliceAnimated, each wrapped in WithDefault HOC}</g>
-        │   │           │   └── CBGDateTracesAnimationContainer
-        │   │           │       └── ReactTransitionGroupPlus
-        │   │           │           └── <g id="cbgDateTraces">{n CBGDateTraceAnimated where n is number of exposed CGM sensor traces}</g>
-        │   │           └── TargetRangeLines
-        │   ├── CBGDateTraceLabel
-        │   └── FocusedRangeLabels
-        └── TidelineFooter
-```
-
-**BGM Trends**
-
-```
-└── PatientData
-    └── Trends
-        ├── TidelineHeader
-        ├── TrendsSubNav
-        ├── <div className="patient-data-content">
-        │   ├── <div id="tidelineContainer">
-        │   │   └── TrendsContainer
-        │   │       └── TrendsSVGContainer (wrapped in DimensionsHOC)
-        │   │           ├── Background
-        │   │           ├── XAxisLabels
-        │   │           ├── XAxisTicks
-        │   │           ├── YAxisLabels
-        │   │           ├── <g id="smbgTrends">
-        │   │           │   ├── SMBGRangeAvgContainer (for range behind smbgs)
-        │   │           │   │   └── <g className="smbgAggContainer">{up to 8 SMBGRangeAnimated (per default 3-hr binning), each wrapped in WithDefault}</g>
-        │   │           │   ├── SMBGsByDateContainer
-        │   │           │   │   └── <g id="smbgsByDateContainer">{up to n each of SMBGDateLineAnimated and SMBGDatePointsAnimated where n is # of days in view}</g>
-        │   │           │   │       └── <g id="">
-        │   │           │   └── SMBGRangeAvgContainer (for avg in front of smbgs)
-        │   │           │   │   └── <g className="smbgAggContainer">{up to 8 SMBGMeanAnimated (per default 3-hr binning), each wrapped in WithDefault}</g>
-        │   │           └── TargetRangeLines
-        │   └── FocusedRangeLabels
-        └── TidelineFooter
-```
-
-### 📐 Layout
-
-The variables involved in the layout of the data display inside the Trends view—that is, the code for Trends view contained in this repository—are as follows, all originating in the `TrendsSVGContainer`:
-
-- `containerHeight` and `containerWidth` are the dimensions of the `<div id="tidelineContainer">` that the data portion of every view is rendered within. These are provided on `TrendsSVGContainer` as props via the `Dimensions` higher-order component (HOC) that wraps the SVG container. This `Dimensions` HOC is an external dependency from the [`react-dimensions`](https://github.com/digidem/react-dimensions 'GitHub: react-dimensions').
-- The `MARGINS` (a constant of `top`, `bottom`, `left`, and `right` properties) are the space outside the data display area (gray box) that provide padding around the data display area and space for the x- and y-axis ticks and labels.
-- The `BUMPERS` (a constant of `top` and `bottom` properties) are the internal padding in the data display area.
-
-Altogether, in diagram form (though **not to scale**):
-
-![Trends layout](./images/tidelineContainer@2x.png 'Trends layout')
-
-### 💣 Tech Debt
-
-- When you hover a date line on the smbg side of Trends, instead of properly pulling the line to the top we just render a second version of the line on top.
-
-### 🚀 The Future
-
-At present the `<div id="tidelineContainer">` is given a fixed size via blip's styling, but as we introduce responsiveness in blip, we will be able to leverage the behavior of the `Dimensions` HOC to make the dataviz responsive. `Dimensions` will update the `containerHeight` and `containerWidth` props on `TrendsSVGContainer` on window resize, and then by implementing a `componentWillReceiveProps` on `TrendsSVGContainer` we will be able to adjust the dimensions of the rendered SVG and the ranges of the x and y scales created with D3 to respond to the new viewport size.

package/postcss.config.js

@@ -1,6 +0,0 @@
-const calc = require('postcss-calc');
-const cssVariables = require('postcss-custom-properties');
-
-module.exports = {
-  plugins: [calc, cssVariables],
-};