@buildcanada/charts 0.1.0

package/src/grapher/controls/entityPicker/EntityPickerConstants.ts

@@ -0,0 +1,23 @@
+import { ColumnSlug } from "../../../utils/index.js"
+import { GrapherAnalytics } from "../../core/GrapherAnalytics"
+import { OwidTable } from "../../../core-table/index.js"
+import { CoreColumnDef, EntityName, SortOrder } from "../../../types/index.js"
+import { MapConfig } from "../../mapCharts/MapConfig"
+
+export interface EntityPickerManager {
+    entityPickerMetric?: ColumnSlug
+    entityPickerSort?: SortOrder
+    setEntityPicker?: (options: {
+        metric: string | undefined
+        sort?: SortOrder
+    }) => void
+    requiredColumnSlugs?: ColumnSlug[] // If this param is provided, and an entity does not have a value for 1+, it will show as unavailable.
+    entityPickerColumnDefs?: CoreColumnDef[]
+    entityPickerTable?: OwidTable
+    entityPickerTableIsLoading?: boolean
+    grapherTable?: OwidTable
+    entityType?: string
+    analytics?: GrapherAnalytics
+    availableEntityNames?: EntityName[]
+    mapConfig?: MapConfig
+}

package/src/grapher/controls/globalEntitySelector/GlobalEntitySelector.scss

@@ -0,0 +1,129 @@
+.global-entity-control-container {
+    position: sticky;
+    top: 5px;
+    z-index: $zindex-global-entity-select;
+
+    @include xxlg-down {
+        margin-left: 128px; // space for ToC "Contents" button
+    }
+}
+
+.global-entity-control {
+    margin-top: 1rem;
+    padding: 0.65em;
+    border-radius: 8px;
+    background-color: #fff;
+    box-shadow:
+        0 15px 40px rgba(0, 0, 0, 0.1),
+        0 8px 15px rgba(0, 0, 0, 0.08),
+        0 1px 3px 1px rgba(0, 0, 0, 0.08);
+
+    display: flex;
+    align-items: center;
+
+    &.is-narrow {
+        // must be 1rem to avoid auto-zoom
+        font-size: 1rem;
+        padding: 0.5em;
+    }
+
+    .select-dropdown-container {
+        width: 15%;
+        min-width: 16em;
+        max-width: 19em;
+        margin-right: 0.75em;
+    }
+
+    .selected-items-container {
+        flex: 1;
+        overflow-y: auto;
+        overflow-x: visible;
+    }
+
+    .selected-items {
+        display: flex;
+        align-content: center;
+    }
+
+    .selected-item {
+        display: flex;
+        align-items: stretch;
+        border-radius: 100px;
+        padding: 0;
+        margin-right: 0.375em;
+        user-select: none;
+        white-space: nowrap;
+        // enough to avoid clipping box-shadow
+        margin-left: 2px;
+        margin-top: 2px;
+        margin-bottom: 2px;
+
+        background-color: #3360a9;
+        color: #fff;
+
+        .label {
+            font-weight: 700;
+            padding: 0.2em 0.8em;
+        }
+
+        &.removable .label {
+            padding-right: 0.3em;
+        }
+
+        .remove-icon {
+            flex: 0;
+            font-size: 15px;
+            display: flex;
+            align-items: center;
+            padding-right: 0.85em;
+            padding-left: 0.3em;
+            cursor: pointer;
+            opacity: 0.5;
+
+            &:hover {
+                opacity: 1;
+            }
+        }
+    }
+
+    .empty {
+        text-align: center;
+        color: $blue-40;
+    }
+
+    .narrow-summary {
+        flex: 1;
+        min-width: 0;
+    }
+
+    .narrow-summary-selected-items {
+        overflow: hidden;
+        white-space: nowrap;
+        text-overflow: ellipsis;
+        color: rgba(0, 0, 0, 0.5);
+        padding-left: 0.25em;
+    }
+
+    .narrow-summary-selected-item {
+        font-weight: 700;
+        color: #3360a9;
+    }
+
+    .narrow-actions {
+        flex: 0;
+        display: flex;
+        align-items: center;
+        margin-left: 0.5em;
+        min-height: 2.25em; // roughly enough space for <select> not to cause a height change
+    }
+
+    .button {
+        border-radius: 100px;
+        background-color: #3360a9;
+        color: white;
+        font-weight: 700;
+        padding: 0.5em 0.8em;
+        border: none;
+        white-space: nowrap;
+    }
+}

package/src/grapher/controls/globalEntitySelector/GlobalEntitySelector.tsx

@@ -0,0 +1,463 @@
+import * as _ from "lodash-es"
+import * as React from "react"
+import ReactDOM from "react-dom/client"
+import {
+    action,
+    observable,
+    IReactionDisposer,
+    reaction,
+    computed,
+    makeObservable,
+} from "mobx"
+import { observer } from "mobx-react"
+import Select, {
+    components,
+    CSSObjectWithLabel,
+    GroupBase,
+    OptionProps,
+    Props,
+} from "react-select"
+import classnames from "classnames"
+import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"
+import { faTimes } from "@fortawesome/free-solid-svg-icons"
+import {
+    countries,
+    getUserCountryInformation,
+    getWindowUrl,
+    setWindowUrl,
+    lazy,
+    RegionType,
+} from "../../../utils/index.js"
+import { GrapherAnalytics } from "../../core/GrapherAnalytics"
+import { WORLD_ENTITY_NAME } from "../../core/GrapherConstants"
+import { GLOBAL_ENTITY_SELECTOR_ELEMENT } from "./GlobalEntitySelectorConstants"
+import { SelectionArray } from "../../selection/SelectionArray"
+import { EntityName } from "../../../types/index.js"
+import { setSelectedEntityNamesParam } from "../../core/EntityUrlBuilder"
+
+enum GlobalEntitySelectionModes {
+    none = "none",
+    // Possibly might need the `add` state in the future to
+    // add country from geolocation without clearing others.
+    // One thing to figure out is what its behaviour should
+    // be for single-entity charts.
+
+    // add = "add",
+    override = "override",
+}
+
+interface DropdownEntity {
+    label: string
+    value: string
+}
+
+const getAllEntitiesSortedWithWorld = lazy(() =>
+    _.sortBy(countries, (c) => c.name)
+        // Add 'World'
+        .concat([
+            {
+                name: WORLD_ENTITY_NAME,
+                code: "OWID_WRL",
+                slug: "world",
+                regionType: RegionType.Other,
+            },
+        ])
+)
+
+const Option = (
+    props: OptionProps<DropdownEntity, true, any>
+): React.ReactElement => {
+    return (
+        <div>
+            <components.Option {...props}>
+                <input type="checkbox" checked={props.isSelected} readOnly />{" "}
+                <label>{props.label}</label>
+            </components.Option>
+        </div>
+    )
+}
+
+const SelectOptions: Props<DropdownEntity, true, any> = {
+    components: {
+        IndicatorSeparator: null,
+        Option,
+    },
+    menuPlacement: "bottom",
+    isClearable: false,
+    isMulti: true,
+    backspaceRemovesValue: false,
+    blurInputOnSelect: false,
+    closeMenuOnSelect: false,
+    controlShouldRenderValue: false,
+    hideSelectedOptions: false,
+    placeholder: "Add a country to all charts...",
+    styles: {
+        placeholder: (base: CSSObjectWithLabel): CSSObjectWithLabel => ({
+            ...base,
+            whiteSpace: "nowrap",
+        }),
+        valueContainer: (base: CSSObjectWithLabel): CSSObjectWithLabel => ({
+            ...base,
+            paddingTop: 0,
+            paddingBottom: 0,
+        }),
+        control: (base: CSSObjectWithLabel): CSSObjectWithLabel => ({
+            ...base,
+            minHeight: "initial",
+        }),
+        dropdownIndicator: (base: CSSObjectWithLabel): CSSObjectWithLabel => ({
+            ...base,
+            padding: "0 5px",
+        }),
+    },
+}
+
+function SelectedItems(props: {
+    selectedEntityNames: EntityName[]
+    emptyLabel: string
+    canRemove?: boolean
+    onRemove?: (item: EntityName) => void
+}): React.ReactElement {
+    const canRemove = (props.canRemove ?? true) && props.onRemove !== undefined
+    const onRemove = props.onRemove || _.noop
+    const isEmpty = props.selectedEntityNames.length === 0
+    return (
+        <div className="selected-items-container">
+            {isEmpty ? (
+                <div className="empty">{props.emptyLabel}</div>
+            ) : (
+                <div className="selected-items">
+                    {props.selectedEntityNames.map((entityName) => (
+                        <div
+                            key={entityName}
+                            className={classnames("selected-item", {
+                                removable: canRemove,
+                            })}
+                        >
+                            <div className="label">{entityName}</div>
+                            {canRemove && (
+                                <div
+                                    className="remove-icon"
+                                    onClick={(): void => onRemove(entityName)}
+                                >
+                                    <FontAwesomeIcon icon={faTimes} />
+                                </div>
+                            )}
+                        </div>
+                    ))}
+                </div>
+            )}
+        </div>
+    )
+}
+
+interface GlobalEntitySelectorProps {
+    selection: SelectionArray
+    graphersAndExplorersToUpdate?: Set<SelectionArray>
+    environment?: string
+}
+
+@observer
+export class GlobalEntitySelector extends React.Component<GlobalEntitySelectorProps> {
+    refContainer = React.createRef<HTMLDivElement>()
+    disposers: IReactionDisposer[] = []
+
+    mode = GlobalEntitySelectionModes.none
+
+    private isNarrow = true
+    private isOpen = false
+    private localEntityName: EntityName | undefined
+
+    selection = this.props.selection
+
+    private optionGroups: GroupBase<DropdownEntity>[] = []
+
+    constructor(props: GlobalEntitySelectorProps) {
+        super(props)
+
+        makeObservable<
+            GlobalEntitySelector,
+            | "isNarrow"
+            | "isOpen"
+            | "localEntityName"
+            | "optionGroups"
+            | "onResizeThrottled"
+        >(this, {
+            mode: observable,
+            isNarrow: observable,
+            isOpen: observable,
+            localEntityName: observable,
+            optionGroups: observable.ref,
+            onResizeThrottled: action.bound,
+        })
+    }
+
+    override componentDidMount(): void {
+        this.onResize()
+        window.addEventListener("resize", this.onResizeThrottled)
+        this.disposers.push(
+            reaction(
+                () => this.isOpen,
+                () => this.prepareOptionGroups()
+            )
+        )
+        void this.populateLocalEntity()
+    }
+
+    override componentWillUnmount(): void {
+        window.removeEventListener("resize", this.onResizeThrottled)
+        this.disposers.forEach((dispose): void => dispose())
+    }
+
+    private onResizeThrottled = _.throttle(this.onResize, 200)
+    @action.bound private onResize(): void {
+        const container = this.refContainer.current
+        if (container) this.isNarrow = container.offsetWidth <= 640
+    }
+
+    @action.bound async populateLocalEntity(): Promise<void> {
+        try {
+            const localCountryCode = await getUserCountryInformation()
+            if (!localCountryCode) return
+
+            const country = getAllEntitiesSortedWithWorld().find(
+                (entity): boolean => entity.code === localCountryCode.code
+            )
+            if (country) this.localEntityName = country.name
+        } catch {
+            // ignore
+        }
+    }
+
+    @action.bound private prepareOptionGroups(): GroupBase<DropdownEntity>[] {
+        let optionGroups: GroupBase<DropdownEntity>[] = []
+        // We want to include the local country, but not if it's already selected, it adds
+        // unnecessary duplication.
+        if (
+            this.localEntityName &&
+            !this.selection.selectedSet.has(this.localEntityName)
+        ) {
+            optionGroups = optionGroups.concat([
+                {
+                    label: "Suggestions",
+                    options: [entityNameToOption(this.localEntityName)],
+                },
+            ])
+        }
+        if (this.selection.hasSelection) {
+            optionGroups = optionGroups.concat([
+                {
+                    label: "Selected",
+                    options:
+                        this.selection.selectedEntityNames.map(
+                            entityNameToOption
+                        ),
+                },
+            ])
+        }
+        optionGroups = optionGroups.concat([
+            {
+                label: "All countries",
+                options: getAllEntitiesSortedWithWorld()
+                    .map((entity) => entity.name)
+                    .map(entityNameToOption),
+            },
+        ])
+        this.optionGroups = optionGroups
+        return optionGroups
+    }
+
+    private analytics = new GrapherAnalytics(
+        this.props.environment ?? "development"
+    )
+
+    @action.bound private updateURL(): void {
+        setWindowUrl(
+            setSelectedEntityNamesParam(
+                getWindowUrl(),
+                this.selection.selectedEntityNames
+            )
+        )
+    }
+
+    @action.bound updateSelection(newSelectedEntities: string[]): void {
+        this.selection.setSelectedEntities(newSelectedEntities)
+        this.updateAllGraphersAndExplorersOnPage()
+        this.updateURL()
+    }
+
+    @action.bound private onChange(options: readonly DropdownEntity[]): void {
+        this.updateSelection(
+            options.map((option: DropdownEntity) => option.label)
+        )
+
+        this.analytics.logGlobalEntitySelector(
+            "change",
+            this.selection.selectedEntityNames.join(",")
+        )
+    }
+
+    @action.bound private updateAllGraphersAndExplorersOnPage(): void {
+        if (!this.props.graphersAndExplorersToUpdate) return
+        Array.from(this.props.graphersAndExplorersToUpdate.values()).forEach(
+            (value) => {
+                value.setSelectedEntities(this.selection.selectedEntityNames)
+            }
+        )
+    }
+
+    @action.bound private onRemove(option: EntityName): void {
+        this.selection.toggleSelection(option)
+        this.updateAllGraphersAndExplorersOnPage()
+        this.updateURL()
+    }
+
+    @action.bound private onMenuOpen(): void {
+        this.isOpen = true
+    }
+
+    @action.bound private onMenuClose(): void {
+        this.isOpen = false
+    }
+
+    @action.bound private onButtonOpen(
+        event: React.MouseEvent<HTMLButtonElement>
+    ): void {
+        this.analytics.logGlobalEntitySelector(
+            "open",
+            event.currentTarget.innerText
+        )
+        this.onMenuOpen()
+    }
+
+    @action.bound private onButtonClose(
+        event: React.MouseEvent<HTMLButtonElement>
+    ): void {
+        this.analytics.logGlobalEntitySelector(
+            "close",
+            event.currentTarget.innerText
+        )
+        this.onMenuClose()
+    }
+
+    @computed private get selectedOptions(): DropdownEntity[] {
+        return this.selection.selectedEntityNames.map(entityNameToOption)
+    }
+
+    private renderNarrow(): React.ReactElement {
+        return (
+            <>
+                <div
+                    className={classnames("narrow-summary", {
+                        "narrow-summary-selected-items": !this.isOpen,
+                    })}
+                >
+                    {this.isOpen ? (
+                        <Select
+                            {...SelectOptions}
+                            options={this.optionGroups}
+                            value={this.selectedOptions}
+                            onChange={this.onChange}
+                            menuIsOpen={this.isOpen}
+                            autoFocus={true}
+                        />
+                    ) : (
+                        <div>
+                            {!this.selection.hasSelection
+                                ? "None selected"
+                                : this.selection.selectedEntityNames
+                                      .map((entityName) => (
+                                          <span
+                                              className="narrow-summary-selected-item"
+                                              key={entityName}
+                                          >
+                                              {entityName}
+                                          </span>
+                                      ))
+                                      .reduce(
+                                          (acc, item) =>
+                                              acc.length === 0
+                                                  ? [item]
+                                                  : [...acc, ", ", item],
+                                          [] as (React.ReactElement | string)[]
+                                      )}
+                        </div>
+                    )}
+                </div>
+                <div className="narrow-actions">
+                    {this.isOpen ? (
+                        <button className="button" onClick={this.onButtonClose}>
+                            Done
+                        </button>
+                    ) : (
+                        <button className="button" onClick={this.onButtonOpen}>
+                            {!this.selection.hasSelection
+                                ? "Select countries"
+                                : "Edit"}
+                        </button>
+                    )}
+                </div>
+            </>
+        )
+    }
+
+    private renderWide(): React.ReactElement {
+        return (
+            <>
+                <div className="select-dropdown-container">
+                    <Select
+                        {...SelectOptions}
+                        options={this.optionGroups}
+                        onChange={this.onChange}
+                        value={this.selectedOptions}
+                        onMenuOpen={this.onMenuOpen}
+                        onMenuClose={this.onMenuClose}
+                    />
+                </div>
+                <SelectedItems
+                    selectedEntityNames={this.selection.selectedEntityNames}
+                    onRemove={this.onRemove}
+                    emptyLabel="Select countries to show on all charts"
+                />
+            </>
+        )
+    }
+
+    override render(): React.ReactElement {
+        return (
+            <div
+                className={classnames("global-entity-control", {
+                    "is-narrow": this.isNarrow,
+                    "is-wide": !this.isNarrow,
+                })}
+                ref={this.refContainer}
+                onClick={
+                    this.isNarrow && !this.isOpen ? this.onMenuOpen : undefined
+                }
+            >
+                {this.isNarrow ? this.renderNarrow() : this.renderWide()}
+            </div>
+        )
+    }
+}
+
+export const hydrateGlobalEntitySelectorIfAny = (
+    selection: SelectionArray,
+    graphersAndExplorersToUpdate: Set<SelectionArray>
+): void => {
+    const element = document.querySelector(GLOBAL_ENTITY_SELECTOR_ELEMENT)
+    if (!element) return
+
+    ReactDOM.hydrateRoot(
+        element,
+        <GlobalEntitySelector
+            selection={selection}
+            graphersAndExplorersToUpdate={graphersAndExplorersToUpdate}
+        />
+    )
+}
+
+const entityNameToOption = (label: EntityName): DropdownEntity => ({
+    label,
+    value: label,
+})

package/src/grapher/controls/globalEntitySelector/GlobalEntitySelectorConstants.ts

@@ -0,0 +1,3 @@
+export const GLOBAL_ENTITY_SELECTOR_DATA_ATTR = "data-global-entity-control"
+export const GLOBAL_ENTITY_SELECTOR_ELEMENT = `*[${GLOBAL_ENTITY_SELECTOR_DATA_ATTR}]`
+export const GLOBAL_ENTITY_SELECTOR_DEFAULT_COUNTRY = "data-default-country" // Authors can set this attr in their blog posts

package/src/grapher/controls/globalEntitySelector/readme.md

@@ -0,0 +1,17 @@
+# Global Entity Control
+
+This component allows users to change the Entity Selection across all the Graphers on a single HTML page.
+
+## Context
+
+We have a number of Wordpress blog posts that embeds multiple Graphers. If a user wants to see a seleciton like "Canada and France" across all the Graphers on that post, they can use the Global Entity Control to do it, if the author has put one on that page.
+
+## Testing
+
+Visit the test page at http://localhost:3030/multiEmbedderTest
+
+## How to use
+
+1. Put multiple Graphers in one HTML page.
+2. Put a `<div data-global-entity-control />` tag in the page.
+3. Now when the page loads, our hydrate function will hydrate the component.

package/src/grapher/controls/settings/AbsRelToggle.tsx

@@ -0,0 +1,64 @@
+import * as React from "react"
+import { computed, action, makeObservable } from "mobx"
+import { observer } from "mobx-react"
+import {
+    GRAPHER_CHART_TYPES,
+    GrapherChartType,
+    StackMode,
+} from "../../../types/index.js"
+import { LabeledSwitch } from "../../../components/index.js"
+
+const { LineChart, ScatterPlot, SlopeChart } = GRAPHER_CHART_TYPES
+
+export interface AbsRelToggleManager {
+    stackMode?: StackMode
+    relativeToggleLabel?: string
+    activeChartType?: GrapherChartType
+}
+
+@observer
+export class AbsRelToggle extends React.Component<{
+    manager: AbsRelToggleManager
+}> {
+    constructor(props: { manager: AbsRelToggleManager }) {
+        super(props)
+        makeObservable(this)
+    }
+
+    @action.bound onToggle(): void {
+        this.manager.stackMode = this.isRelativeMode
+            ? StackMode.absolute
+            : StackMode.relative
+    }
+
+    @computed get isRelativeMode(): boolean {
+        return this.manager.stackMode === StackMode.relative
+    }
+
+    @computed get manager(): AbsRelToggleManager {
+        return this.props.manager
+    }
+
+    @computed get tooltip(): string {
+        const { activeChartType } = this.manager
+        return activeChartType === ScatterPlot
+            ? "Show the percentage change per year over the the selected time range."
+            : activeChartType === LineChart || activeChartType === SlopeChart
+              ? "Show proportional changes over time or actual values in their original units."
+              : "Show values as their share of the total or as actual values in their original units."
+    }
+
+    override render(): React.ReactElement {
+        const label =
+            this.manager.relativeToggleLabel ?? "Display relative values"
+        return (
+            <LabeledSwitch
+                label={label}
+                value={this.isRelativeMode}
+                tooltip={this.tooltip}
+                onToggle={this.onToggle}
+                tracking="chart_abs_rel_toggle"
+            />
+        )
+    }
+}