@buildcanada/charts 0.1.0

package/src/explorer/ColumnGrammar.ts

@@ -0,0 +1,217 @@
+import { AvailableTransforms } from "../core-table/index.js"
+import {
+    automaticBinningStrategies,
+    ColorSchemeName,
+    ColumnTypeNames,
+} from "../types/index.js"
+import { ToleranceStrategy } from "../utils/index.js"
+import {
+    BooleanCellDef,
+    ColumnCellDef,
+    EnumCellDef,
+    EtlPathCellDef,
+    Grammar,
+    IntegerCellDef,
+    NumericCellDef,
+    SlugDeclarationCellDef,
+    StringCellDef,
+    UrlCellDef,
+} from "./gridLang/GridLangConstants.js"
+
+export const ColumnGrammar: Grammar<ColumnCellDef> = {
+    variableId: {
+        ...IntegerCellDef,
+        keyword: "variableId",
+        description: "Numerical variable ID",
+    },
+    catalogPath: {
+        ...EtlPathCellDef,
+        keyword: "catalogPath",
+        description: "Catalog path to the etl indicator",
+    },
+    slug: {
+        ...SlugDeclarationCellDef,
+        keyword: "slug",
+    },
+    name: {
+        ...StringCellDef,
+        keyword: "name",
+        description:
+            "This is the name that may appear on the y or x axis of a chart",
+    },
+    type: {
+        ...StringCellDef,
+        keyword: "type",
+        description: `The column type reveals how to interpret the data, whether as a string or number for example, and how to display it, like whether to show a % or $.`,
+        terminalOptions: Object.values(ColumnTypeNames).map((keyword) => ({
+            keyword,
+            description: "",
+            cssClass: "",
+        })),
+    },
+    transform: {
+        ...StringCellDef,
+        keyword: "transform",
+        description: `An advanced option. Available transforms are: ${AvailableTransforms.join(
+            ", "
+        )}`,
+    },
+    tolerance: {
+        ...IntegerCellDef,
+        keyword: "tolerance",
+        description:
+            "Set this to interpolate missing values as long as they are within this range of an actual value.",
+    },
+    toleranceStrategy: {
+        ...EnumCellDef,
+        keyword: "toleranceStrategy",
+        terminalOptions: Object.values(ToleranceStrategy).map((strategy) => ({
+            keyword: strategy,
+            description: "",
+            cssClass: "",
+        })),
+        description: "The tolerance strategy to use",
+    },
+    description: {
+        ...StringCellDef,
+        keyword: "description",
+        description: "Describe the column",
+    },
+    unit: {
+        ...StringCellDef,
+        keyword: "unit",
+        description: "Unit of measurement",
+    },
+    shortUnit: {
+        ...StringCellDef,
+        keyword: "shortUnit",
+        description: "Short (axis) unit",
+    },
+    notes: {
+        ...StringCellDef,
+        keyword: "notes",
+        description: "Any internal notes.",
+    },
+    annotationsColumnSlug: {
+        ...StringCellDef,
+        keyword: "annotationsColumnSlug",
+        description:
+            "Column that contains the annotations for this column, if any.",
+    },
+    sourceName: {
+        ...StringCellDef,
+        keyword: "sourceName",
+        description:
+            "Source name displayed on charts using this dataset. For academic papers, the name of the source should be 'Authors (year)' e.g. Arroyo-Abad and Lindert (2016). For institutional projects or reports, the name should be 'Institution, Project (year or vintage)' e.g. U.S. Bureau of Labor Statistics, Consumer Expenditure Survey (2015 release). For data that we have modified extensively, the name should be 'Our World in Data based on Author (year)' e.g. Our World in Data based on Atkinson (2002) and Sen (2000).",
+    },
+    sourceLink: {
+        ...UrlCellDef,
+        keyword: "sourceLink",
+        description:
+            "Link to the publication from which we retrieved this data",
+    },
+    dataPublishedBy: {
+        ...StringCellDef,
+        keyword: "dataPublishedBy",
+        description:
+            "For academic papers this should be a complete reference. For institutional projects, detail the project or report. For data we have modified extensively, list OWID as the publishers and provide the name of the person in charge of the calculation.",
+    },
+    dataPublisherSource: {
+        ...StringCellDef,
+        keyword: "dataPublisherSource",
+        description:
+            "Basic indication of how the publisher collected this data e.g. surveys data. Anything longer than a line should go in the dataset description.",
+    },
+    retrievedDate: {
+        ...StringCellDef,
+        keyword: "retrievedDate",
+        description: "Date when this data was obtained by us",
+    },
+    additionalInfo: {
+        ...StringCellDef,
+        keyword: "additionalInfo",
+        description:
+            "Describe the dataset and the methodology used in its construction. This can be as long and detailed as you like.",
+    },
+    nonRedistributable: {
+        ...BooleanCellDef,
+        keyword: "nonRedistributable",
+        description: "Disable data download in chart?",
+    },
+    color: {
+        ...StringCellDef,
+        keyword: "color",
+        description: "Default color for column",
+    },
+    colorScaleScheme: {
+        ...EnumCellDef,
+        keyword: "colorScaleScheme",
+        terminalOptions: Object.values(ColorSchemeName).map((keyword) => ({
+            keyword,
+            description: "",
+            cssClass: "",
+        })),
+        description: "The color scheme to use",
+    },
+    colorScaleInvert: {
+        ...BooleanCellDef,
+        keyword: "colorScaleInvert",
+        description: "Invert the color scale?",
+    },
+    colorScaleBinningStrategy: {
+        ...EnumCellDef,
+        keyword: "colorScaleBinningStrategy",
+        terminalOptions: automaticBinningStrategies.map((keyword) => ({
+            keyword,
+            description: "",
+            cssClass: "",
+        })),
+        description: "The binning strategy to use",
+    },
+    colorScaleNoDataLabel: {
+        ...StringCellDef,
+        keyword: "colorScaleNoDataLabel",
+        description: "Custom label for the 'No data' bin",
+    },
+    colorScaleLegendDescription: {
+        ...StringCellDef,
+        keyword: "colorScaleLegendDescription",
+        description: "Legend title",
+    },
+    colorScaleNumericMinValue: {
+        ...NumericCellDef,
+        keyword: "colorScaleNumericMinValue",
+        description:
+            "Minimum value of the first bin (leaving blank will infer the minimum from the data)",
+    },
+    colorScaleNumericBins: {
+        ...StringCellDef,
+        keyword: "colorScaleNumericBins",
+        description: [
+            "Custom numeric bins",
+            "  Format: [binMax],[color],[label]; [binMax],[color],[label]; ...",
+            "  Example: 0.1,#ccc,example label; 0.2,,; 0.3,,prev has no label",
+        ].join("\n"),
+    },
+    colorScaleCategoricalBins: {
+        ...StringCellDef,
+        keyword: "colorScaleCategoricalBins",
+        description: [
+            "Custom categorical bins",
+            "  Format: [data value],[color],[label]; [data value],[color],[label]; ...",
+            "  Example: one,#ccc,uno; two,,dos",
+        ].join("\n"),
+    },
+    isProjection: {
+        ...BooleanCellDef,
+        keyword: "isProjection",
+        description: "Is the time series a forward projection?",
+        display: true,
+    },
+    plotMarkersOnlyInLineChart: {
+        ...BooleanCellDef,
+        keyword: "plotMarkersOnlyInLineChart",
+        description: "Should data points be connected by a line?",
+        display: true,
+    },
+} as const

package/src/explorer/Explorer.sample.ts

@@ -0,0 +1,212 @@
+import { DimensionProperty } from "../utils/index.js"
+import { GRAPHER_TAB_CONFIG_OPTIONS } from "../types/index.js"
+import {
+    GrapherProgrammaticInterface,
+    legacyToOwidTableAndDimensionsWithMandatorySlug,
+} from "../grapher/index.js"
+import { Explorer, ExplorerProps } from "./Explorer.js"
+
+const SampleExplorerOfGraphersProgram = `explorerTitle	CO₂ Data Explorer
+isPublished	false
+explorerSubtitle	Download the complete <i>Our World in Data</i> <a href="https://github.com/owid/co2-data">CO₂ and GHG Emissions Dataset</a>.
+subNavId	co2
+time	earliest..latest
+selection	China	United States	India	United Kingdom	World
+Gas Radio	CO₂
+Accounting Radio	Production-based
+subNavCurrentId	co2-data-explorer
+graphers
+	grapherId	Gas Radio	Accounting Radio	Fuel Dropdown	Count Dropdown	Relative to world total Checkbox	hasMapTab
+	488	CO₂	Production-based	Total	Per country	false	true
+	3219	CO₂	Production-based	Total	Per country	Share of global emissions	false
+	486	CO₂	Production-based	Total	Per capita	false
+	485	CO₂	Production-based	Total	Cumulative	false	false
+	3218	CO₂	Production-based	Total	Cumulative	Share of global emissions	false
+	4267	CO₂	Production-based	Total	Per MWh of energy	false
+	530	CO₂	Production-based	Total	Per $ of GDP	false
+	3621	CO₂	Consumption-based		Per country	false
+	3488	CO₂	Consumption-based		Per capita	false
+	4331	CO₂	Consumption-based		Per $ of GDP	false
+	696	CO₂	Consumption-based		Share of emissions embedded in trade	false
+	4250	CO₂	Production-based	Coal	Per country	false
+	4251	CO₂	Production-based	Oil	Per country	false
+	4253	CO₂	Production-based	Gas	Per country	false
+	4255	CO₂	Production-based	Cement	Per country	false
+	4332	CO₂	Production-based	Flaring	Per country	false
+	4249	CO₂	Production-based	Coal	Per capita	false
+	4252	CO₂	Production-based	Oil	Per capita	false
+	4254	CO₂	Production-based	Gas	Per capita	false
+	4256	CO₂	Production-based	Cement	Per capita	false
+	4333	CO₂	Production-based	Flaring	Per capita	false
+	4147	All GHGs (CO₂eq)	Production-based		Per country	false
+	4239	All GHGs (CO₂eq)	Production-based		Per capita	false
+	4222	Methane	Production-based		Per country	false
+	4243	Methane	Production-based		Per capita	false
+	4224	Nitrous oxide	Production-based		Per country	false
+	4244	Nitrous oxide	Production-based		Per capita	false`
+
+// Generate realistic CO2 per capita emissions data (tonnes per person)
+// Based on approximate real-world trends from OWID CO2 data
+function generateCO2PerCapitaData() {
+    const startYear = 1990
+    const endYear = 2024
+    const years: number[] = []
+    const entities: number[] = []
+    const values: number[] = []
+
+    // Entity IDs matching the selection: China, United States, India, United Kingdom, World
+    const entityData = [
+        {
+            id: 1,
+            name: "China",
+            code: "CHN",
+            // CO2 per capita rose from ~2 to ~8 tonnes
+            baseValue: 2.1,
+            trend: (year: number) => 2.1 + (year - 1990) * 0.18,
+        },
+        {
+            id: 2,
+            name: "United States",
+            code: "USA",
+            // CO2 per capita declined from ~20 to ~14 tonnes
+            baseValue: 19.5,
+            trend: (year: number) =>
+                19.5 - (year - 1990) * 0.15 + Math.sin(year * 0.5) * 0.3,
+        },
+        {
+            id: 3,
+            name: "India",
+            code: "IND",
+            // CO2 per capita rose from ~0.7 to ~2 tonnes
+            baseValue: 0.7,
+            trend: (year: number) => 0.7 + (year - 1990) * 0.04,
+        },
+        {
+            id: 4,
+            name: "United Kingdom",
+            code: "GBR",
+            // CO2 per capita declined from ~10 to ~5 tonnes
+            baseValue: 10.2,
+            trend: (year: number) =>
+                10.2 - (year - 1990) * 0.15 + Math.sin(year * 0.3) * 0.2,
+        },
+        {
+            id: 5,
+            name: "World",
+            code: "OWID_WRL",
+            // Global average rose from ~4 to ~4.7 tonnes
+            baseValue: 4.0,
+            trend: (year: number) =>
+                4.0 + (year - 1990) * 0.02 + Math.sin(year * 0.2) * 0.1,
+        },
+    ]
+
+    // Generate data for each year and entity
+    for (let year = startYear; year <= endYear; year++) {
+        for (const entity of entityData) {
+            years.push(year)
+            entities.push(entity.id)
+            // Add some realistic variation
+            const baseValue = entity.trend(year)
+            const noise = (Math.sin(year * entity.id) * 0.1 + 1) * baseValue
+            values.push(Math.round(noise * 100) / 100)
+        }
+    }
+
+    const yearValues: { id: number }[] = []
+    for (let year = startYear; year <= endYear; year++) {
+        yearValues.push({ id: year })
+    }
+
+    return {
+        data: { years, entities, values },
+        metadata: {
+            id: 142609,
+            display: { yearIsDay: false },
+            dimensions: {
+                entities: {
+                    values: entityData.map((e) => ({
+                        name: e.name,
+                        code: e.code,
+                        id: e.id,
+                    })),
+                },
+                years: { values: yearValues },
+            },
+        },
+    }
+}
+
+export const SampleExplorerOfGraphers = (props?: Partial<ExplorerProps>) => {
+    const title = "CO₂ emissions per capita"
+    const co2Data = generateCO2PerCapitaData()
+    const owidDataset = new Map([[142609, co2Data]])
+    const dimensions = [
+        {
+            variableId: 142609,
+            property: DimensionProperty.y,
+        },
+    ]
+    const first: GrapherProgrammaticInterface = {
+        id: 488,
+        title,
+        dimensions,
+        tab: GRAPHER_TAB_CONFIG_OPTIONS.chart,
+    }
+    first.table = legacyToOwidTableAndDimensionsWithMandatorySlug(
+        owidDataset,
+        dimensions,
+        {}
+    )
+    const grapherConfigs: GrapherProgrammaticInterface[] = [
+        first,
+        {
+            ...first,
+            id: 4147,
+            title: "All GHGs per capita",
+        },
+    ]
+    return new Explorer({
+        slug: "test-slug",
+        program: SampleExplorerOfGraphersProgram,
+        grapherConfigs,
+        adminBaseUrl: "",
+        bakedBaseUrl: "",
+        bakedGrapherUrl: "",
+        dataApiUrl: "",
+        ...props,
+    })
+}
+
+const SampleInlineDataExplorerProgram = `explorerTitle	Sample Explorer
+selection	Argentina
+graphers
+	Test Radio	xSlug	ySlugs	colorSlug	sizeSlug	type
+	Scatter	x	y	color	size	ScatterPlot
+	Line		y			LineChart
+
+columns
+	slug	type	name
+	Country	EntityName	Country
+	Quarter	Quarter	Quarter
+	x	Numeric	x
+	y	Numeric	y
+	color	Numeric	color
+	size	Numeric	size
+
+table
+	Country	Year	x	y	color	size
+	Argentina	2020	1	1	1	1
+	Argentina	2021	1	1	1	1`
+
+export const SampleInlineDataExplorer = (props?: Partial<ExplorerProps>) => {
+    return new Explorer({
+        slug: "test-slug-inline-data",
+        program: SampleInlineDataExplorerProgram,
+        adminBaseUrl: "",
+        bakedBaseUrl: "",
+        bakedGrapherUrl: "",
+        dataApiUrl: "",
+        ...props,
+    })
+}

package/src/explorer/Explorer.scss

@@ -0,0 +1,148 @@
+$placeholder-height: 800px;
+$chart-border-radius: 2px;
+$explorer-grid-gap: 10px;
+$explorer-min-width-first-col: 200px;
+$explorer-padding: 0.5rem;
+
+#ExplorerContainer {
+    min-height: $placeholder-height;
+    width: 100%;
+    position: relative;
+    padding: $explorer-padding;
+
+    .admin-only-locally-edited-checkbox {
+        position: absolute;
+        right: 5px;
+    }
+}
+
+html.IsInIframe #ExplorerContainer {
+    height: 100vh;
+    min-height: auto !important;
+    max-height: none;
+    // leave some padding for shadows
+    padding: 3px;
+
+    .admin-only-locally-edited-checkbox {
+        display: none;
+    }
+}
+
+.ExplorerHeaderBox {
+    padding: 8px;
+    min-width: $explorer-min-width-first-col;
+    background: white;
+    border-radius: $chart-border-radius;
+    box-shadow: $light-shadow;
+    display: flex;
+    flex-direction: column;
+    justify-content: space-around;
+
+    .ExplorerTitle {
+        font-size: clamp(16px, 1.5vw, 19px);
+        line-height: clamp(18px, 1.7vw, 23px);
+        font-weight: bold;
+        font-family: $sans-serif-font-stack;
+    }
+
+    .ExplorerSubtitle {
+        color: #7a899e;
+        font-size: 13px;
+    }
+    .ExplorerDownloadLink {
+        font-size: 13px;
+        @include owid-link-60;
+    }
+}
+
+.explorerContentContainer {
+    // liberale approximation of ExplorerShell._isMobile()
+    @media (max-width: 849px) {
+        @include wrapper-x-spacing;
+    }
+
+    @media (min-width: 850px) {
+        max-width: $max-width-data-explorer;
+        margin: 0 auto;
+        display: grid;
+        grid-template-columns: 1fr 4fr;
+        column-gap: $explorer-grid-gap;
+        padding: $explorer-padding;
+
+        .sidebar {
+            min-width: $explorer-min-width-first-col;
+        }
+    }
+}
+
+html.IsInIframe .Explorer,
+.Explorer.is-embed {
+    height: 100%;
+    min-height: auto !important;
+    max-height: none;
+    min-width: auto !important;
+    max-width: none;
+    padding: 0;
+}
+
+html.IsInIframe .ExplorerFigure,
+.is-embed .ExplorerFigure {
+    min-height: auto !important;
+    max-height: none;
+}
+
+.Explorer {
+    margin: 0 auto;
+    padding-top: $explorer-grid-gap;
+    width: 100%;
+    max-width: $max-width-data-explorer;
+    height: 90vh;
+    max-height: 900px;
+    min-height: 480px;
+    display: grid;
+    grid-template-columns: 1fr 4fr;
+    grid-template-rows: 1fr 9fr;
+    grid-row-gap: $explorer-grid-gap;
+    grid-column-gap: $explorer-grid-gap;
+
+    &.HideControls {
+        display: block;
+
+        .ExplorerFigure {
+            height: 100%;
+        }
+    }
+
+    .mobile-button {
+        color: #fff;
+        background-color: #3f9eff;
+        text-align: center;
+        padding: 0.375rem 1rem;
+        line-height: 1.5;
+        border-radius: 0.25rem;
+    }
+
+    .ExplorerFigure {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        position: relative;
+        min-height: 600px;
+
+        // Remove chart from layout calculation.
+        // Since grid/flex layouts size to their contents, having the chart dictate that leads to
+        // a very slow adaptations to resizing.
+        .GrapherComponent {
+            position: absolute;
+        }
+    }
+
+    &.mobile-explorer {
+        grid-template-columns: auto;
+        grid-template-rows: 0fr 0fr 0fr 1fr;
+
+        .ExplorerFigure {
+            min-height: 540px;
+        }
+    }
+}