@buildcanada/charts 0.1.0

package/src/grapher/lineLegend/LineLegendConstants.ts

@@ -0,0 +1,9 @@
+// Minimum vertical space between two legend items
+export const LEGEND_ITEM_MIN_SPACING = 4
+// Horizontal distance from the end of the chart to the start of the marker
+export const MARKER_MARGIN = 4
+// Space between the label and the annotation
+export const ANNOTATION_PADDING = 1
+
+export const DEFAULT_CONNECTOR_LINE_WIDTH = 25
+export const DEFAULT_FONT_WEIGHT = 400

package/src/grapher/lineLegend/LineLegendFilterAlgorithms.ts

@@ -0,0 +1,143 @@
+import * as _ from "lodash-es"
+import {
+    computeCandidateScores,
+    LineLegendFilterAlgorithmContext,
+    pickAsManyAsPossibleWithRetry,
+    pickCandidate,
+    pickCandidateWithMaxDistanceToReferenceCandidate,
+    pickCandidateWithRetry,
+} from "./LineLegendHelpers"
+import { PlacedSeries } from "./LineLegendTypes"
+
+/**
+ * Keep a subset of series that fit within the available height, prioritizing by
+ * importance. Focused series have priority, even if they're less important.
+ *
+ * Note that more important (but longer) series names might be skipped if they don't fit.
+ */
+export function findImportantSeriesThatFitIntoTheAvailableSpace(
+    seriesSortedByImportance: PlacedSeries[],
+    availableHeight: number
+) {
+    let context: LineLegendFilterAlgorithmContext = {
+        candidates: new Set(seriesSortedByImportance),
+        availableHeight,
+        sortedKeepSeries: [],
+        keepSeriesHeight: 0,
+    }
+
+    const [focusedCandidates, nonFocusedCandidates] = _.partition(
+        seriesSortedByImportance,
+        (series) => series.focus?.active
+    )
+
+    const importanceScore = new Map(
+        seriesSortedByImportance.map((series, index) => [
+            series.seriesName,
+            -index, // higher index means lower importance
+        ])
+    )
+
+    const getMostImportantCandidate = (candidates: PlacedSeries[]) =>
+        _.maxBy(candidates, (c) => importanceScore.get(c.seriesName))
+
+    // focused series have priority
+    context = pickAsManyAsPossibleWithRetry({
+        context,
+        candidateSubset: focusedCandidates,
+        getCandidateFromSubset: getMostImportantCandidate,
+    })
+
+    context = pickAsManyAsPossibleWithRetry({
+        context,
+        candidateSubset: nonFocusedCandidates,
+        getCandidateFromSubset: getMostImportantCandidate,
+    })
+
+    return context.sortedKeepSeries
+}
+
+/**
+ * Pick a subset of series that fit within the available height.
+ *
+ * The algorithm tries to pick labels in a 'balanced' way such that they're
+ * spread out as much as possible. Focused series have priority.
+ *
+ * The algorithm works as follows: Given a set of placed labels and a set of
+ * candidates, for each candidate, we find the two closest already placed labels,
+ * one to each side, and calculate a score based on the available space between
+ * the two placed labels (the bigger, the better) and the candidate's distance to
+ * the midpoint (the smaller, the better). We then pick the candidate with the best
+ * score that fits into the available space.
+ */
+export function findSeriesThatFitIntoTheAvailableSpace(
+    series: PlacedSeries[],
+    availableHeight: number
+): PlacedSeries[] {
+    let context: LineLegendFilterAlgorithmContext = {
+        candidates: new Set(series),
+        availableHeight,
+        sortedKeepSeries: [],
+        keepSeriesHeight: 0,
+    }
+
+    const [focusedCandidates, nonFocusedCandidates] = _.partition(
+        series,
+        (series) => series.focus?.active
+    )
+
+    // focused series have priority
+    context = pickAsManyAsPossibleWithRetry({
+        context,
+        candidateSubset: focusedCandidates,
+    })
+
+    // we initially need to pick at least two candidates
+    const numPickedCandidates = context.sortedKeepSeries.length
+    if (numPickedCandidates === 0) {
+        // pick two candidates with maximal distance to each other.
+        // by convention we pick the max candidate first, but we could also
+        // start by picking the min cadidate
+        const maxCandidate = _.maxBy(nonFocusedCandidates, (c) => c.midY)
+        if (maxCandidate) {
+            context = pickCandidate(context, maxCandidate)
+
+            context = pickCandidateWithMaxDistanceToReferenceCandidate({
+                context,
+                candidateSubset: nonFocusedCandidates,
+                referenceCandidate: context.sortedKeepSeries[0],
+            })
+        }
+    } else if (numPickedCandidates === 1) {
+        // pick the candidate that is furthest away from the focused label
+        context = pickCandidateWithMaxDistanceToReferenceCandidate({
+            context,
+            candidateSubset: nonFocusedCandidates,
+            referenceCandidate: context.sortedKeepSeries[0],
+        })
+    }
+
+    // pick candidates based on a scoring system
+    while (
+        context.candidates.size > 0 &&
+        context.keepSeriesHeight <= availableHeight
+    ) {
+        const candidates = Array.from(context.candidates)
+        const scoreMap = computeCandidateScores(
+            candidates,
+            context.sortedKeepSeries
+        )
+
+        // pick the candidate with the highest score
+        const getBestCandidate = (candidates: PlacedSeries[]) =>
+            _.maxBy(candidates, (c) => scoreMap.get(c.seriesName))
+
+        context = pickCandidateWithRetry({
+            context,
+            candidateSubset: candidates,
+            getCandidateFromSubset: getBestCandidate,
+        })
+    }
+
+    return context.sortedKeepSeries
+}

package/src/grapher/lineLegend/LineLegendHelpers.ts

@@ -0,0 +1,253 @@
+import * as _ from "lodash-es"
+import { SeriesName } from "../../utils/index.js"
+import { PlacedSeries } from "./LineLegendTypes"
+import { LEGEND_ITEM_MIN_SPACING } from "./LineLegendConstants"
+import * as R from "remeda"
+
+type Bracket = [number, number]
+
+export interface LineLegendFilterAlgorithmContext {
+    candidates: Set<PlacedSeries> // remaining candidates to be considered for placement
+    availableHeight: number
+    sortedKeepSeries: PlacedSeries[] // series that have been picked to be labelled, sorted by their y position
+    keepSeriesHeight: number // total height of the picked series
+}
+
+interface PickFromCandidateSubsetParams {
+    context: LineLegendFilterAlgorithmContext
+    candidateSubset: PlacedSeries[]
+    getCandidateFromSubset?: (
+        candidateSubset: PlacedSeries[]
+    ) => PlacedSeries | undefined
+}
+
+const dist = (c1: PlacedSeries, c2: PlacedSeries) => Math.abs(c1.midY - c2.midY)
+
+function getNewHeight(currentHeight: number, candidate: PlacedSeries): number {
+    // if the candidate is the first one, don't add padding
+    const padding = currentHeight === 0 ? 0 : LEGEND_ITEM_MIN_SPACING
+    return currentHeight + candidate.bounds.height + padding
+}
+
+/**
+ * Given a sorted list of brackets, like [[0, 10], [10, 20], [20, 30]],
+ * find the bracket that contains the given number n.
+ */
+function findBracket(
+    sortedBrackets: Bracket[],
+    n: number
+): [number | undefined, number | undefined] {
+    if (sortedBrackets.length === 0) return [undefined, undefined]
+
+    const firstBracketValue = sortedBrackets[0][0]
+    const lastBracketValue = R.last(sortedBrackets)![1]
+
+    if (n < firstBracketValue) return [undefined, firstBracketValue]
+    if (n >= lastBracketValue) return [lastBracketValue, undefined]
+
+    for (const bracket of sortedBrackets) {
+        if (n >= bracket[0] && n < bracket[1]) return bracket
+    }
+
+    return [undefined, undefined]
+}
+
+/**
+ * Add a candidate to the list of picked series and update the context accordingly.
+ */
+export function pickCandidate(
+    context: LineLegendFilterAlgorithmContext,
+    candidate: PlacedSeries
+): LineLegendFilterAlgorithmContext {
+    let { candidates, sortedKeepSeries, keepSeriesHeight } = context
+
+    // insert into sortedKeepSeries at the right position
+    const insertIndex = R.sortedIndexBy(
+        context.sortedKeepSeries,
+        candidate,
+        (s) => s.midY
+    )
+    sortedKeepSeries.splice(insertIndex, 0, candidate)
+
+    // update keepSeriesHeight
+    keepSeriesHeight = getNewHeight(keepSeriesHeight, candidate)
+
+    // delete from candidates
+    candidates.delete(candidate)
+
+    return { ...context, candidates, sortedKeepSeries, keepSeriesHeight }
+}
+
+/**
+ * Remove a candidate from the list of candidates to be considered for placement.
+ */
+function dismissCandidate(
+    context: LineLegendFilterAlgorithmContext,
+    candidate: PlacedSeries
+) {
+    const { candidates } = context
+    candidates.delete(candidate)
+    return { ...context, candidates }
+}
+
+/**
+ * Pick from a subset of candidates until one of the following conditions is met:
+ * - no candidates are left or the maximum number of candidates to pick is reached
+ * - no more candidates fit into the available space
+ *
+ * The order of candidates to consider for placement is determined by the
+ * `getCandidateFromSubset` function. The function should return the next candidate
+ * to consider. If the function returns `undefined`, the algorithm stops.
+ *
+ * If no custom function is provided, the algorithm picks candidates starting from
+ * the end (!) of the given list.
+ */
+function pickFromCandidateSubsetWithRetry(
+    params: PickFromCandidateSubsetParams & { maxCandidatesToPick?: number }
+): LineLegendFilterAlgorithmContext {
+    let {
+        context,
+        candidateSubset,
+        getCandidateFromSubset,
+        maxCandidatesToPick,
+    } = params
+
+    if (candidateSubset.length === 0 || maxCandidatesToPick === 0)
+        return context
+
+    const remainingCandidates = [...candidateSubset]
+    let numPicked = 0
+
+    // if a custom function to get a candidate is provided, use it
+    // otherwise, pop the last candidate
+    const getCandidate = (): PlacedSeries | undefined => {
+        if (getCandidateFromSubset) {
+            const candidate = getCandidateFromSubset(remainingCandidates)
+            if (candidate) {
+                const index = remainingCandidates.indexOf(candidate)
+                remainingCandidates.splice(index, 1)
+            }
+            return candidate
+        }
+
+        return remainingCandidates.pop()
+    }
+
+    while (remainingCandidates.length > 0) {
+        const candidate = getCandidate()
+        if (!candidate) break
+
+        // sanity check if this is a valid candidate
+        if (!context.candidates.has(candidate)) continue
+
+        // either pick or dismiss the candidate
+        const newHeight = getNewHeight(context.keepSeriesHeight, candidate)
+        if (newHeight <= context.availableHeight) {
+            context = pickCandidate(context, candidate)
+            numPicked++
+        } else {
+            context = dismissCandidate(context, candidate)
+        }
+
+        // stop if we picked enough candidates
+        if (numPicked === maxCandidatesToPick) break
+    }
+
+    return context
+}
+
+/**
+ * Pick as many candidates as possible from a given subset.
+ *
+ * The order of candidates to consider for placement is determined by the
+ * `getCandidateFromSubset` function. The function should return the next candidate
+ * to consider. If the function returns `undefined`, the algorithm stops.
+ *
+ * If no custom function is provided, the algorithm picks candidates starting from
+ * the end (!) of the given list.
+ */
+export function pickAsManyAsPossibleWithRetry(
+    params: PickFromCandidateSubsetParams
+): LineLegendFilterAlgorithmContext {
+    return pickFromCandidateSubsetWithRetry(params)
+}
+
+/**
+ * Pick a fixed number of candidates from a give subset.
+ *
+ * The order of candidates to consider for placement is determined by the
+ * `getCandidateFromSubset` function. The function should return the next candidate
+ * to consider. If the function returns `undefined`, the algorithm stops.
+ *
+ * If no custom function is provided, the algorithm picks candidates starting from
+ * the end (!) of the given list.
+ */
+export function pickCandidateWithRetry(
+    params: PickFromCandidateSubsetParams
+): LineLegendFilterAlgorithmContext {
+    return pickFromCandidateSubsetWithRetry({
+        ...params,
+        maxCandidatesToPick: 1,
+    })
+}
+
+export function pickCandidateWithMaxDistanceToReferenceCandidate(params: {
+    context: LineLegendFilterAlgorithmContext
+    candidateSubset: PlacedSeries[]
+    referenceCandidate: PlacedSeries
+}): LineLegendFilterAlgorithmContext {
+    const { context, candidateSubset, referenceCandidate } = params
+
+    const getMaxDistCandidate = (candidates: PlacedSeries[]) =>
+        _.maxBy(candidates, (c) => dist(c, referenceCandidate))
+
+    return pickCandidateWithRetry({
+        context,
+        candidateSubset,
+        getCandidateFromSubset: getMaxDistCandidate,
+    })
+}
+
+/**
+ * Compute a score for each candidate based on how large the space between the
+ * neighboring labels is and how far it is from the mid point of the neighboring
+ * labels.
+ */
+export function computeCandidateScores(
+    candidates: PlacedSeries[],
+    sortedKeepSeries: PlacedSeries[]
+): Map<SeriesName, number> {
+    const scoreMap = new Map<SeriesName, number>()
+
+    const sortedBrackets = sortedKeepSeries
+        .slice(0, -1)
+        .map((s, i) => [s.midY, sortedKeepSeries[i + 1].midY])
+        .filter((bracket) => bracket[0] !== bracket[1]) as Bracket[]
+
+    // score each candidate based on how well it fits into the available space
+    for (const candidate of candidates) {
+        // find the bracket that the candidate is contained in
+        const [start, end] = findBracket(sortedBrackets, candidate.midY)
+
+        // if no bracket is found, return the worst possible score
+        if (end === undefined || start === undefined) {
+            scoreMap.set(candidate.seriesName, 0)
+            continue
+        }
+
+        // score the candidate based on how far it is from the
+        // middle of the bracket and how large the bracket is
+        const length = end - start
+        const midPoint = start + length / 2
+        const distanceFromMidPoint = Math.abs(candidate.midY - midPoint)
+        const score = length - distanceFromMidPoint
+
+        scoreMap.set(candidate.seriesName, score)
+    }
+
+    return scoreMap
+}
+
+export function getSeriesKey(series: PlacedSeries, index: number): string {
+    return `${series.seriesName}-${index}`
+}

package/src/grapher/lineLegend/LineLegendTypes.ts

@@ -0,0 +1,32 @@
+import { MarkdownTextWrap, TextWrap } from "../../components/index.js"
+import { Bounds } from "../../utils/index.js"
+import { ChartSeries } from "../chart/ChartInterface"
+import { InteractionState } from "../interaction/InteractionState"
+
+export interface LineLabelSeries extends ChartSeries {
+    label: string
+    yValue: number
+    annotation?: string
+    formattedValue?: string
+    placeFormattedValueInNewLine?: boolean
+    yRange?: [number, number]
+    hover?: InteractionState
+    focus?: InteractionState
+}
+
+export interface SizedSeries extends LineLabelSeries {
+    textWrap: TextWrap | MarkdownTextWrap
+    annotationTextWrap?: TextWrap
+    width: number
+    height: number
+    fontWeight?: number
+}
+
+export interface PlacedSeries extends SizedSeries {
+    origBounds: Bounds
+    bounds: Bounds
+    repositions: number
+    level: number
+    totalLevels: number
+    midY: number
+}