@buildcanada/charts 0.1.0

package/src/grapher/tooltip/Tooltip.tsx

@@ -0,0 +1,294 @@
+import * as React from "react"
+import { computed, action, makeObservable } from "mobx"
+import { observer } from "mobx-react"
+import { faInfoCircle } from "@fortawesome/free-solid-svg-icons"
+import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"
+import classnames from "classnames"
+import { match } from "ts-pattern"
+import {
+    Bounds,
+    GrapherTooltipAnchor,
+    stripOuterParentheses,
+} from "../../utils/index.js"
+import {
+    TooltipProps,
+    TooltipManager,
+    TooltipContainerProps,
+    TooltipContext,
+    TooltipFooterIcon,
+} from "./TooltipProps"
+import { SignificanceIcon } from "./TooltipContents.js"
+
+export * from "./TooltipContents.js"
+export { TooltipState } from "./TooltipState.js"
+
+export class TooltipCard extends React.Component<
+    TooltipProps & TooltipContainerProps
+> {
+    private base = React.createRef<HTMLDivElement>()
+    private bounds: Bounds | undefined = undefined
+
+    private updateBounds(): void {
+        if (this.base.current) {
+            this.bounds = Bounds.fromElement(this.base.current)
+        }
+    }
+
+    private get tooltipStyle(): React.CSSProperties {
+        const { bounds } = this
+        const {
+            containerBounds,
+            anchor,
+            x = 0,
+            y = 0,
+            offsetX = 0,
+            offsetY = 0,
+        } = this.props
+        const isPinnedToBottom = anchor === GrapherTooltipAnchor.bottom
+
+        const style = { ...this.props.style }
+
+        // if container dimensions are given, we make sure the tooltip
+        // is positioned within the container bounds
+        if (
+            containerBounds?.width &&
+            containerBounds.height &&
+            !isPinnedToBottom
+        ) {
+            let adjustedOffsetY = offsetY
+            let adjustedOffsetX = offsetX
+
+            if (this.props.offsetYDirection === "upward") {
+                adjustedOffsetY = -offsetY - (bounds?.height ?? 0)
+            }
+
+            if (
+                this.props.offsetXDirection === "left" &&
+                x > (bounds?.width ?? 0)
+            ) {
+                adjustedOffsetX = -offsetX - (bounds?.width ?? 0)
+            }
+
+            // Ensure tooltip remains inside chart
+            let left = x + adjustedOffsetX
+            let top = y + adjustedOffsetY
+            if (bounds) {
+                if (left + bounds.width > containerBounds?.width)
+                    left -= bounds.width + 2 * adjustedOffsetX // flip left
+                if (top + bounds.height * 0.75 > containerBounds.height)
+                    top -= bounds.height + 2 * adjustedOffsetY // flip upwards eventually...
+                if (top + bounds.height > containerBounds.height)
+                    top = containerBounds.height - bounds.height // ...but first pin at bottom
+
+                if (left < 0) left = 0 // pin on left
+                if (top < 0) top = 0 // pin at top
+            }
+
+            style.position = "absolute"
+            style.left = left
+            style.top = top
+        }
+
+        // ignore the given width and max-width if the tooltip position is fixed
+        // since we want to use the full width of the screen in that case
+        if (isPinnedToBottom && (style.width || style.maxWidth)) {
+            style.width = style.maxWidth = undefined
+        }
+
+        return style
+    }
+
+    override componentDidMount(): void {
+        this.updateBounds()
+    }
+
+    override componentDidUpdate(): void {
+        this.updateBounds()
+    }
+
+    override render(): React.ReactElement {
+        let {
+            id,
+            title,
+            titleAnnotation,
+            subtitle,
+            subtitleFormat,
+            footer,
+            dissolve,
+            children,
+            anchor,
+        } = this.props
+        const isPinnedToBottom = anchor === GrapherTooltipAnchor.bottom
+
+        // add a preposition to unit-based subtitles
+        const hasHeader = title !== undefined || subtitle !== undefined
+        if (!!subtitle && subtitleFormat === "unit") {
+            const unit = subtitle.toString()
+            const preposition = !unit.match(/^(per|in|\() /i) ? "in " : ""
+            subtitle = preposition + stripOuterParentheses(unit)
+        }
+
+        // flag the year in the header and add note in footer (if necessary)
+        const timeNotice = !!subtitle && subtitleFormat === "notice"
+
+        // style the box differently if just displaying title/subtitle
+        const plain = hasHeader && !children
+
+        // skip transition delay if requested
+        const immediate = dissolve === "immediate"
+
+        return (
+            <TooltipContext.Provider value={{ anchor }}>
+                <div
+                    className={classnames("tooltip-container", {
+                        "fixed-bottom": isPinnedToBottom,
+                    })}
+                >
+                    <div
+                        ref={this.base}
+                        id={id?.toString()}
+                        role="tooltip"
+                        className={classnames("Tooltip", {
+                            plain,
+                            dissolve,
+                            immediate,
+                        })}
+                        style={this.tooltipStyle}
+                    >
+                        {hasHeader && (
+                            <div className="frontmatter">
+                                {title && (
+                                    <div className="title">
+                                        {title}{" "}
+                                        <span className="annotation">
+                                            {titleAnnotation}
+                                        </span>
+                                    </div>
+                                )}
+                                {subtitle && (
+                                    <div className="subtitle">
+                                        {timeNotice && (
+                                            <TooltipIcon
+                                                icon={TooltipFooterIcon.Notice}
+                                            />
+                                        )}
+                                        <span>{subtitle}</span>
+                                    </div>
+                                )}
+                            </div>
+                        )}
+                        <div className="content-and-endmatter">
+                            {children && (
+                                <div className="content">{children}</div>
+                            )}
+                            {footer && footer.length > 0 && (
+                                <div
+                                    className={classnames("endmatter", {
+                                        "multiple-lines": footer.length > 1,
+                                    })}
+                                >
+                                    {footer?.map(({ icon, text }) => (
+                                        <div
+                                            key={text}
+                                            className={classnames("line", {
+                                                "icon-sig":
+                                                    icon ===
+                                                    TooltipFooterIcon.Significance,
+                                                "no-icon":
+                                                    icon ===
+                                                    TooltipFooterIcon.None,
+                                            })}
+                                        >
+                                            <TooltipIcon icon={icon} />
+                                            <p>{text}</p>
+                                        </div>
+                                    ))}
+                                </div>
+                            )}
+                        </div>
+                    </div>
+                </div>
+            </TooltipContext.Provider>
+        )
+    }
+}
+
+interface ManagedTooltipContainerProps extends TooltipContainerProps {
+    tooltipManager: TooltipManager
+}
+
+@observer
+export class TooltipContainer extends React.Component<ManagedTooltipContainerProps> {
+    constructor(props: ManagedTooltipContainerProps) {
+        super(props)
+        makeObservable(this)
+    }
+
+    @computed private get tooltip(): TooltipProps | undefined {
+        const { tooltip } = this.props.tooltipManager
+        return tooltip?.get()
+    }
+
+    override render(): React.ReactElement | null {
+        const { props, tooltip } = this
+        if (!tooltip) return null
+        return <TooltipCard {...props} {...tooltip} />
+    }
+}
+
+interface ManagedTooltipProps extends TooltipProps {
+    tooltipManager: TooltipManager
+}
+
+@observer
+export class Tooltip extends React.Component<ManagedTooltipProps> {
+    constructor(props: ManagedTooltipProps) {
+        super(props)
+        makeObservable(this)
+    }
+
+    override componentDidMount(): void {
+        this.connectTooltipToContainer()
+    }
+
+    @action.bound private connectTooltipToContainer(): void {
+        this.props.tooltipManager.tooltip?.set(this.props)
+    }
+
+    @action.bound private removeToolTipFromContainer(): void {
+        this.props.tooltipManager.tooltip?.set(undefined)
+    }
+
+    override componentDidUpdate(): void {
+        this.connectTooltipToContainer()
+    }
+
+    override componentWillUnmount(): void {
+        this.removeToolTipFromContainer()
+    }
+
+    override render(): null {
+        return null
+    }
+}
+
+function TooltipIcon({
+    icon,
+}: {
+    icon: TooltipFooterIcon
+}): React.ReactElement | null {
+    return match(icon)
+        .with(TooltipFooterIcon.Notice, () => (
+            <FontAwesomeIcon className="icon" icon={faInfoCircle} />
+        ))
+        .with(TooltipFooterIcon.Stripes, () => (
+            <div className="stripes icon"></div>
+        ))
+        .with(TooltipFooterIcon.Significance, () => (
+            <div className="icon">
+                <SignificanceIcon />
+            </div>
+        ))
+        .with(TooltipFooterIcon.None, () => null)
+        .exhaustive()
+}

package/src/grapher/tooltip/TooltipContents.tsx

@@ -0,0 +1,383 @@
+import * as _ from "lodash-es"
+import * as React from "react"
+import classnames from "classnames"
+import { NO_DATA_LABEL } from "../color/ColorScale.js"
+import { FontAwesomeIcon } from "@fortawesome/react-fontawesome"
+import { faInfoCircle, faS } from "@fortawesome/free-solid-svg-icons"
+import { formatInlineList, GrapherTooltipAnchor } from "../../utils/index.js"
+import { GrapherTrendArrow } from "../../components/index.js"
+import {
+    TooltipValueProps,
+    TooltipValueRangeProps,
+    TooltipContext,
+    TooltipTableProps,
+    TooltipVariableProps,
+} from "./TooltipProps"
+import { makeAxisLabel } from "../chart/ChartUtils.js"
+import * as R from "remeda"
+import { CoreColumn } from "../../core-table/index.js"
+
+type TooltipValue = number | string | undefined
+
+export const NO_DATA_COLOR = "#999"
+
+export function TooltipValue({
+    label,
+    unit,
+    value,
+    color,
+    originalTime,
+    isProjection,
+    labelVariant = "label+unit",
+    isRoundedToSignificantFigures,
+    showSignificanceSuperscript,
+}: TooltipValueProps): React.ReactElement {
+    const displayValue = value || NO_DATA_LABEL
+    const displayColor = displayValue === NO_DATA_LABEL ? NO_DATA_COLOR : color
+
+    const showSuperscript =
+        showSignificanceSuperscript && isRoundedToSignificantFigures
+    const superscript = showSuperscript ? (
+        <SignificanceIcon asSuperscript={true} />
+    ) : null
+
+    return (
+        <Variable
+            label={label}
+            unit={unit}
+            color={displayColor}
+            isProjection={isProjection}
+            originalTimes={originalTime ? [originalTime] : undefined}
+            labelVariant={labelVariant}
+        >
+            <span>
+                {displayValue}
+                {superscript}
+            </span>
+        </Variable>
+    )
+}
+
+export function TooltipValueRange({
+    label,
+    unit,
+    values,
+    colors,
+    originalTimes,
+    trend,
+    labelVariant = "label+unit",
+    isRoundedToSignificantFigures,
+    showSignificanceSuperscript,
+}: TooltipValueRangeProps): React.ReactElement | null {
+    const [firstTerm, lastTerm] = values
+
+    if (firstTerm === undefined && lastTerm === undefined) return null
+
+    const showSuperscript =
+        showSignificanceSuperscript && isRoundedToSignificantFigures
+    const superscript = showSuperscript ? (
+        <SignificanceIcon asSuperscript={true} />
+    ) : null
+
+    return (
+        <Variable
+            label={label}
+            unit={unit}
+            originalTimes={originalTimes}
+            labelVariant={labelVariant}
+        >
+            <span className="range">
+                <span className="term">
+                    <span style={{ color: colors?.[0] }}>{firstTerm}</span>
+                    {!lastTerm && superscript}
+                </span>
+                {trend && (
+                    <GrapherTrendArrow direction={trend} isColored={!colors} />
+                )}
+                {lastTerm && (
+                    <span className="term">
+                        <span style={{ color: colors?.[1] }}>{lastTerm}</span>
+                        {superscript}
+                    </span>
+                )}
+            </span>
+        </Variable>
+    )
+}
+
+function Variable({
+    label,
+    unit,
+    children,
+    color,
+    originalTimes,
+    isProjection,
+    labelVariant = "label+unit",
+}: TooltipVariableProps): React.ReactElement {
+    const { mainLabel: columnName, unit: formattedUnit } = makeAxisLabel({
+        label: label || "",
+        displayUnit: unit,
+    })
+
+    const displayOriginalTimes =
+        _.uniq((originalTimes ?? []).filter((t) => t !== undefined)).join(
+            "\u2013"
+        ) || null
+
+    return (
+        <div
+            className={classnames("variable", {
+                "variable--no-name": labelVariant === "unit-only",
+            })}
+        >
+            <div className="definition">
+                {columnName && <span className="name">{columnName}</span>}
+                {formattedUnit && formattedUnit.length > 1 && (
+                    <span className="unit">{formattedUnit}</span>
+                )}
+                {isProjection && (
+                    <span className="projection">projected data</span>
+                )}
+            </div>
+            <div className="values" style={{ color }}>
+                {children}
+                {displayOriginalTimes && (
+                    <span className="time-notice">
+                        <FontAwesomeIcon icon={faInfoCircle} />
+                        {displayOriginalTimes}
+                    </span>
+                )}
+            </div>
+        </div>
+    )
+}
+
+export function TooltipTable({
+    columns,
+    rows,
+    totals = [],
+}: TooltipTableProps): React.ReactElement | null {
+    const context = React.useContext(TooltipContext)
+    const focal = rows.some((row) => row.focused)
+    const swatched = rows.some((row) => row.swatch)
+
+    const tooEmpty =
+        rows.length < 2 ||
+        totals.every((value) => value === undefined) ||
+        rows.some(({ values }) => values.every((value) => value === undefined))
+    const tooTrivial = R.zip(columns, totals).every(
+        ([column, total]) => !!column?.formatValue(total).match(/^100(\.0+)?%/)
+    )
+    const showTotals = totals && !(tooEmpty || tooTrivial)
+
+    // if the tooltip is pinned to the bottom, show the total at the top,
+    // so that it's always visible even if the tooltip is scrollable
+    const showTotalsAtTop = context?.anchor === GrapherTooltipAnchor.bottom
+
+    const totalsCells = R.zip(columns, totals).map(([column, total]) => (
+        <td key={column?.label} className="series-value">
+            {column && total !== undefined ? column.formatValue(total) : null}
+        </td>
+    ))
+
+    return (
+        <table className={classnames("series-list", { focal, swatched })}>
+            {columns.length > 1 && (
+                <thead>
+                    <tr>
+                        <td className="series-color"></td>
+                        <td className="series-name"></td>
+                        {columns.map((column) => (
+                            <td className="series-value" key={column.label}>
+                                {column.label}
+                            </td>
+                        ))}
+                    </tr>
+                </thead>
+            )}
+            <tbody>
+                {showTotals && showTotalsAtTop && (
+                    <>
+                        <tr className="total--top">
+                            <td className="series-color"></td>
+                            <td className="series-name">Total</td>
+                            {totalsCells}
+                        </tr>
+                        <tr className="spacer"></tr>
+                    </>
+                )}
+                {rows.map((row) => {
+                    const {
+                        name,
+                        focused,
+                        blurred,
+                        striped,
+                        annotation,
+                        values,
+                        originalTime,
+                        swatch = {},
+                    } = row
+                    const {
+                        color: swatchColor = "transparent",
+                        opacity: swatchOpacity = 1,
+                    } = swatch
+
+                    const [_m, seriesName, seriesParenthetical] =
+                        name.trim().match(/^(.*?)(\([^()]*\))?$/) ?? []
+
+                    return (
+                        <tr
+                            key={name}
+                            className={classnames({
+                                focused,
+                                blurred,
+                                striped,
+                            })}
+                        >
+                            <td className="series-color">
+                                <div
+                                    className="swatch"
+                                    style={{
+                                        backgroundColor: swatchColor,
+                                        opacity: swatchOpacity,
+                                    }}
+                                />
+                            </td>
+                            <td className="series-name">
+                                {seriesName}
+                                {seriesParenthetical && (
+                                    <span className="parenthetical">
+                                        {seriesParenthetical}
+                                    </span>
+                                )}
+                                {annotation && (
+                                    <span className="annotation">
+                                        {annotation}
+                                    </span>
+                                )}
+                            </td>
+                            {R.zip(columns, values).map(([column, value]) => {
+                                const missing = value === undefined
+                                return column ? (
+                                    <td
+                                        key={column.label}
+                                        className={classnames("series-value", {
+                                            missing,
+                                        })}
+                                    >
+                                        {!missing && column.formatValue(value)}
+                                    </td>
+                                ) : null
+                            })}
+                            {originalTime && (
+                                <td className="time-notice">
+                                    <FontAwesomeIcon icon={faInfoCircle} />{" "}
+                                    {originalTime}
+                                </td>
+                            )}
+                        </tr>
+                    )
+                })}
+                {showTotals && !showTotalsAtTop && (
+                    <>
+                        <tr className="spacer"></tr>
+                        <tr className="total">
+                            <td className="series-color"></td>
+                            <td className="series-name">Total</td>
+                            {totalsCells}
+                        </tr>
+                    </>
+                )}
+            </tbody>
+        </table>
+    )
+}
+
+export function SignificanceIcon({
+    asSuperscript = false,
+}: {
+    asSuperscript?: boolean
+}): React.ReactElement {
+    return (
+        <div
+            className={classnames("icon-circled-s", {
+                "as-superscript": asSuperscript,
+            })}
+        >
+            <div className="circle" />
+            <FontAwesomeIcon icon={faS} />
+        </div>
+    )
+}
+
+export function makeTooltipToleranceNotice(
+    targetYear: string,
+    { plural }: { plural: boolean } = { plural: false }
+): string {
+    const dataPoint = plural ? "data points" : "data point"
+    return `Data not available for ${targetYear}. Showing closest available ${dataPoint} instead`
+}
+
+export function makeTooltipRoundingNotice(
+    numSignificantFigures: number[],
+    { plural }: { plural: boolean } = { plural: true }
+): string {
+    const uniqueNumSigFigs = _.uniq(numSignificantFigures)
+    const formattedNumSigFigs = formatInlineList(
+        _.sortBy(uniqueNumSigFigs),
+        "or"
+    )
+
+    const values = plural ? "Values" : "Value"
+    const are = plural ? "are" : "is"
+    const figures = formattedNumSigFigs === "1" ? "figure" : "figures"
+    return `${values} ${are} rounded to ${formattedNumSigFigs} significant ${figures}`
+}
+
+export function toTooltipTableColumns(
+    columns: CoreColumn | CoreColumn[]
+): TooltipTableProps["columns"] {
+    const columnsArray = Array.isArray(columns) ? columns : [columns]
+
+    return columnsArray.map((column) => ({
+        label: column.displayName,
+        formatValue: (value) =>
+            column.formatValueShort(value, { trailingZeroes: true }),
+    }))
+}
+
+export function formatTooltipRangeValues(
+    values: TooltipValue[],
+    column: CoreColumn
+): [string, string] {
+    const formatTooltipValueShort = (value: TooltipValue): string =>
+        formatTooltipValue(value, (value) => column.formatValueShort(value))
+    const formatTooltipValueShortWithAbbreviations = (
+        value: TooltipValue
+    ): string =>
+        formatTooltipValue(value, (value) =>
+            column.formatValueShortWithAbbreviations(value)
+        )
+
+    const [firstValue, lastValue] = values.map((v) =>
+        formatTooltipValueShort(v)
+    )
+
+    const [firstTerm, lastTerm] =
+        // TODO: would be nicer to actually measure the typeset text but we would need to
+        // add Lato's metrics to the `string-pixel-width` module to use Bounds.forText
+        _.sum([firstValue?.length, lastValue?.length]) > 20
+            ? values.map((v) => formatTooltipValueShortWithAbbreviations(v))
+            : [firstValue, lastValue]
+
+    return [firstTerm, lastTerm]
+}
+
+function formatTooltipValue(
+    value: TooltipValue,
+    formatValue: (value: number) => string
+): string {
+    if (value === undefined) return NO_DATA_LABEL
+    if (typeof value === "string") return value
+    return formatValue(value)
+}