@buildcanada/charts 0.1.0

package/src/types/domainTypes/CoreTableTypes.ts

@@ -0,0 +1,305 @@
+import { OwidOrigin } from "../OwidOrigin.js"
+import {
+    OwidProcessingLevel,
+    OwidVariablePresentation,
+} from "../OwidVariable.js"
+import { OwidVariableDisplayConfigInterface } from "../OwidVariableDisplayConfigInterface.js"
+import {
+    Color,
+    ColumnSlug,
+    PrimitiveType,
+    Time,
+    ToleranceStrategy,
+    Year,
+} from "../grapherTypes/GrapherTypes.js"
+import { Integer } from "./Various.js"
+
+export type TableSlug = string // a url friendly name for a table
+export type ColumnSlugs = string // slugs cannot have spaces, so this is a space delimited array of ColumnSlugs
+
+export enum SortOrder {
+    asc = "asc",
+    desc = "desc",
+}
+
+/**
+ * A concrete point in time (year or date). It's always supposed to be a finite number, but we
+ * cannot enforce this in TypeScript.
+ */
+export type TimeRange = [Time, Time]
+
+export type ValueRange = [number, number]
+
+export type TimeTolerance = Integer
+
+export interface CoreRow {
+    [columnSlug: string]: any
+}
+
+export enum InputType {
+    Delimited = "Delimited",
+    RowStore = "RowStore",
+    ColumnStore = "ColumnStore",
+    Matrix = "Matrix",
+}
+
+export enum TransformType {
+    // Table level ops
+    LoadFromDelimited = "LoadFromDelimited",
+    LoadFromRowStore = "LoadFromRowStore",
+    LoadFromColumnStore = "LoadFromColumnStore",
+    LoadFromMatrix = "LoadFromMatrix",
+    Concat = "Concat",
+    Noop = "Noop", // for when we notice that we can skip a transform
+
+    // Row ops
+    FilterRows = "FilterRows",
+    SortRows = "SortRows",
+    UpdateRows = "UpdateRows", // replace values in a row. For example: to prep columns for log scale, or testing messy runtime data scenarios.
+
+    // Column ops
+    FilterColumns = "FilterColumns",
+    AppendColumns = "AppendColumns", // This will run column transform fns.
+    UpdateColumnDefs = "UpdateColumnDefs", // do not use for updates that add a column transform fn.
+    UpdateColumnDefsAndApply = "UpdateColumnDefsAndApply", // use this for updates that add a column transform fn.
+    RenameColumns = "RenameColumns",
+    CombineColumns = "CombineColumns",
+}
+
+export enum JsTypes {
+    string = "string",
+    boolean = "boolean",
+    number = "number",
+}
+
+export abstract class ErrorValue {
+    toString(): string {
+        return ""
+    }
+    toErrorString(): string {
+        return this.constructor.name
+    }
+}
+
+export type CsvString = string
+
+export type CoreValueType = PrimitiveType | ErrorValue
+
+/**
+ * An Object Literal of Column Slugs and Primitives of the same type:
+ * {
+ *  score: [1, 2, 3],
+ *  year: [2000, 2001]
+ * }
+ */
+export type CoreColumnStore = {
+    [columnSlug: string]: CoreValueType[]
+}
+
+export type CoreTableInputOption =
+    | CoreRow[]
+    | CoreColumnStore
+    | CsvString
+    | CoreMatrix
+
+// Every row will be checked against each column/value(s) pair.
+export interface CoreQuery {
+    [columnSlug: string]: PrimitiveType | PrimitiveType[]
+}
+
+type CoreVector = any[]
+
+/**
+ * This is just an array of arrays where the first array is the header and the rest are rows. An example is:
+ * [["country", "gdp"],
+ * ["usa", 123],
+ * ["can", 456]]
+ * Having this type is just to provide a common unique name for the basic structure used by HandsOnTable
+ * and some other popular JS data libraries.
+ */
+export type CoreMatrix = CoreVector[]
+
+export enum OwidTableSlugs {
+    entityName = "entityName",
+    entityColor = "entityColor",
+    entityId = "entityId",
+    entityCode = "entityCode",
+    time = "time",
+    day = "day",
+    year = "year",
+    date = "date",
+}
+
+enum OwidTableNames {
+    Entity = "Entity",
+    Code = "Code",
+}
+
+export type EntityName = string
+export type EntityCode = string
+export type EntityId = number
+
+export interface Entity {
+    entityName: EntityName
+    entityId?: EntityId
+    entityCode?: EntityCode
+}
+
+export enum ColumnTypeNames {
+    NumberOrString = "NumberOrString",
+    Numeric = "Numeric",
+    String = "String",
+    Region = "Region",
+    SeriesAnnotation = "SeriesAnnotation",
+    Categorical = "Categorical",
+    Ordinal = "Ordinal",
+    Continent = "Continent",
+    EntityName = "EntityName",
+    EntityId = "EntityId",
+    EntityCode = "EntityCode",
+    Boolean = "Boolean",
+    Currency = "Currency",
+    Percentage = "Percentage",
+    RelativePercentage = "RelativePercentage",
+    DecimalPercentage = "DecimalPercentage",
+    Integer = "Integer",
+    PercentChangeOverTime = "PercentChangeOverTime",
+    Ratio = "Ratio",
+    Year = "Year",
+    Day = "Day",
+    Date = "Date",
+    Color = "Color",
+    Population = "Population",
+    PopulationDensity = "PopulationDensity",
+    Age = "Age",
+    Quarter = "Quarter",
+}
+
+export interface ColumnColorScale {
+    // Color scales
+    colorScaleScheme?: string
+    colorScaleInvert?: boolean
+    colorScaleBinningStrategy?: string
+    colorScaleNumericMinValue?: number
+    colorScaleNumericBins?: string
+    colorScaleCategoricalBins?: string
+    colorScaleNoDataLabel?: string
+    colorScaleLegendDescription?: string
+}
+
+export interface CoreColumnDef extends ColumnColorScale {
+    // Core
+    slug: ColumnSlug
+    type?: ColumnTypeNames
+
+    // Computational
+    transform?: string // Code that maps to a CoreTable transform
+    transformHasRun?: boolean // If true, the transform has been applied
+    tolerance?: number // If set, some charts can use this for an interpolation strategy.
+    toleranceStrategy?: ToleranceStrategy // Tolerance strategy to use for interpolation
+    skipParsing?: boolean // If set, the values will never run through the type parser
+
+    // Column information used for display only
+    name?: string // The display name for the column
+    description?: string
+    descriptionShort?: string
+    descriptionProcessing?: string
+    descriptionKey?: string[]
+    descriptionFromProducer?: string
+    note?: string // Any internal notes the author wants to record for display in admin interfaces
+
+    // Sorted values (in case of ordinal data)
+    sort?: string[]
+
+    // Color
+    color?: Color // A column can have a fixed color for use in charts where the columns are series
+
+    // Source information used for display only
+    sourceName?: string
+    sourceLink?: string
+    dataPublishedBy?: string
+    dataPublisherSource?: string
+    retrievedDate?: string
+    additionalInfo?: string
+    timespan?: string
+
+    // Metadata v2
+    origins?: OwidOrigin[]
+    presentation?: OwidVariablePresentation
+    updatePeriodDays?: number
+
+    // Dataset information
+    datasetId?: number
+    datasetName?: string
+
+    // Informational only
+    targetTime?: number
+
+    // For developer internal use only.
+    values?: CoreValueType[]
+    generator?: () => number // A function for generating synthetic data for testing
+    growthRateGenerator?: () => number // A function for generating synthetic data for testing. Can probably combine with the above.
+
+    // DEPRECATED
+    unit?: string // DEPRECATED: use an existing column type or create a new one instead.
+    shortUnit?: string // DEPRECATED: use an existing column type or create a new one instead.
+    display?: OwidVariableDisplayConfigInterface // DEPRECATED: use an existing column type or create a new one instead, or migrate any properties you need onto this interface.
+}
+
+// Todo: coverage, datasetId, and datasetName can just be on source, right? or should we flatten source onto this?
+export interface OwidColumnDef extends CoreColumnDef {
+    owidVariableId?: number
+    coverage?: string
+    datasetId?: number
+    datasetName?: string
+    isDailyMeasurement?: boolean // todo: remove after mysql time refactor
+    annotationsColumnSlug?: ColumnSlug
+    nonRedistributable?: boolean
+    skipParsing?: boolean
+    catalogPath?: string
+    owidProcessingLevel?: OwidProcessingLevel
+    owidSchemaVersion?: number
+    shortName?: string
+}
+
+export const OwidEntityNameColumnDef = {
+    name: OwidTableNames.Entity,
+    slug: OwidTableSlugs.entityName,
+    type: ColumnTypeNames.EntityName,
+}
+
+export const OwidEntityIdColumnDef = {
+    slug: OwidTableSlugs.entityId,
+    type: ColumnTypeNames.EntityId,
+}
+
+export const OwidEntityCodeColumnDef = {
+    name: OwidTableNames.Code,
+    slug: OwidTableSlugs.entityCode,
+    type: ColumnTypeNames.EntityCode,
+}
+
+export const StandardOwidColumnDefs: OwidColumnDef[] = [
+    OwidEntityNameColumnDef,
+    OwidEntityIdColumnDef,
+    OwidEntityCodeColumnDef,
+]
+
+// This is a row with the additional columns specific to our OWID data model
+export interface OwidRow extends CoreRow {
+    entityName: EntityName
+    time: Time
+    entityCode?: EntityCode
+    entityId?: EntityId
+    year?: Year
+    day?: Integer
+    date?: string
+}
+
+export interface OwidVariableRow<ValueType extends PrimitiveType> {
+    entityName: EntityName
+    time: Time
+    value: ValueType
+    originalTime: Time
+    originalValue?: ValueType
+}

package/src/types/domainTypes/DeployStatus.ts

@@ -0,0 +1,23 @@
+export enum DeployStatus {
+    queued = "queued",
+    pending = "pending",
+    // done = "done"
+}
+
+export interface DeployChange {
+    timeISOString?: string
+    authorName?: string
+    authorEmail?: string
+    message?: string
+    slug?: string
+}
+
+export interface Deploy {
+    status: DeployStatus
+    changes: DeployChange[]
+}
+
+export interface DeployMetadata {
+    title: string
+    changesSlackMentions: string[]
+}

package/src/types/domainTypes/Layout.ts

@@ -0,0 +1,34 @@
+export enum Position {
+    top = "top",
+    right = "right",
+    bottom = "bottom",
+    left = "left",
+}
+
+export type PositionMap<Value> = {
+    [key in Position]?: Value
+}
+
+export enum HorizontalAlign {
+    left = "left",
+    center = "center",
+    right = "right",
+}
+
+export enum VerticalAlign {
+    top = "top",
+    middle = "middle",
+    bottom = "bottom",
+}
+
+export enum AxisAlign {
+    start = "start",
+    middle = "middle",
+    end = "end",
+}
+
+export interface GridParameters {
+    rows: number
+    columns: number
+    count: number
+}

package/src/types/domainTypes/Posts.ts

@@ -0,0 +1,34 @@
+import { OwidGdocType } from "../gdocTypes/Gdoc.js"
+import { WP_PostType } from "../wordpressTypes/WordpressTypes.js"
+import { RelatedChart } from "../grapherTypes/GrapherTypes.js"
+import { TocHeading } from "./Toc.js"
+
+export interface FormattedPost extends FullPost {
+    stickyNavLinks?: { text: string; target: string }[]
+    byline?: string
+    html: string
+    footnotes: string[]
+    tocHeadings: TocHeading[]
+    pageDesc: string
+}
+
+export interface IndexPost {
+    title: string
+    slug: string
+    type?: WP_PostType | OwidGdocType
+    date: Date
+    modifiedDate: Date
+    authors: string[]
+    excerpt?: string
+    imageUrl?: string
+}
+
+export interface FullPost extends IndexPost {
+    id: number
+    path: string
+    content: string
+    thumbnailUrl?: string
+    imageId?: number
+    postId?: number
+    relatedCharts?: RelatedChart[]
+}

package/src/types/domainTypes/Search.ts

@@ -0,0 +1,299 @@
+import type {
+    SearchResponse,
+    BaseHit,
+    Hit,
+    HitHighlightResult,
+} from "instantsearch.js"
+import { OwidGdocType } from "../gdocTypes/Gdoc.js"
+import { GrapherTabName } from "../grapherTypes/GrapherTypes.js"
+import * as z from "zod/mini"
+
+export const PagesIndexRecordSchema = z.object({
+    objectID: z.string(),
+    importance: z.number(),
+    type: z.enum(OwidGdocType),
+    slug: z.string(),
+    title: z.string(),
+    content: z.string(),
+    views_7d: z.number(),
+    score: z.number(),
+    excerpt: z.optional(z.string()),
+    excerptLong: z.optional(z.array(z.string())),
+    authors: z.optional(z.array(z.string())),
+    date: z.optional(z.string()),
+    modifiedDate: z.optional(z.string()),
+    tags: z.optional(z.array(z.string())),
+    thumbnailUrl: z.string(),
+})
+
+export type PageRecord = z.infer<typeof PagesIndexRecordSchema>
+
+export const PagesIndexRecordsResponseSchema = z.object({
+    records: z.array(PagesIndexRecordSchema),
+    count: z.number(),
+    message: z.optional(z.string()),
+})
+
+export type PagesIndexRecordsResponse = z.infer<
+    typeof PagesIndexRecordsResponseSchema
+>
+
+export type IPageHit = PageRecord & Hit<BaseHit>
+
+export enum ChartRecordType {
+    Chart = "chart",
+    ExplorerView = "explorerView",
+    MultiDimView = "multiDimView",
+}
+
+export enum ExplorerType {
+    Grapher = "grapher",
+    Indicator = "indicator",
+    Csv = "csv",
+}
+
+export interface ChartRecord {
+    type: ChartRecordType
+    objectID: string
+    chartId: number
+    chartConfigId?: string
+    slug: string
+    queryParams?: string
+    title: string
+    subtitle: string | undefined
+    variantName: string
+    availableTabs: GrapherTabName[]
+    keyChartForTags: string[]
+    tags: string[]
+    availableEntities: string[]
+    /**
+     * Only present for income group-specific FMs: availableEntities before it gets filtered down.
+     * Without this, searching for charts with data for "Uganda" OR "United States" would return
+     * the FM version of the chart that only has Uganda in its available entities, and thus we
+     * wouldn't plot the data for the US, even though the chart has data for the US.
+     */
+    originalAvailableEntities?: string[]
+    /**
+     * Also only set for FMs: used so that we can filter out income group-specific FMs on a plain data catalog view.
+     */
+    isIncomeGroupSpecificFM: boolean
+    publishedAt: string
+    updatedAt: string
+    numDimensions: number
+    titleLength: number
+    numRelatedArticles: number
+    views_7d: number
+    score: number
+    // we set attributeForDistinct on this, so we can use it to deduplicate
+    // when we have multiple records for the same chart (e.g. with featured metrics)
+    id: string
+}
+
+export type IChartHit = Hit<BaseHit> & ChartRecord
+
+export enum SearchIndexName {
+    Charts = "charts",
+    Pages = "pages",
+    ExplorerViewsMdimViewsAndCharts = "explorer-views-and-charts",
+}
+
+export type SearchCategoryFilter = SearchIndexName | "all"
+
+export const searchCategoryFilters: [string, SearchCategoryFilter][] = [
+    ["All", "all"],
+    ["Research & Writing", SearchIndexName.Pages],
+    ["Charts", SearchIndexName.ExplorerViewsMdimViewsAndCharts],
+]
+
+interface BaseSearchChartHit {
+    title: string
+    slug: string
+    availableEntities: string[]
+    originalAvailableEntities?: string[]
+    objectID: string
+    variantName?: string
+    subtitle?: string
+    availableTabs: GrapherTabName[]
+    __position: number
+    _highlightResult?: HitHighlightResult
+    _snippetResult?: HitHighlightResult
+}
+
+type SearchChartViewHit = BaseSearchChartHit & {
+    type: ChartRecordType.Chart
+}
+
+type SearchExplorerViewHit = BaseSearchChartHit & {
+    type: ChartRecordType.ExplorerView
+    explorerType: ExplorerType
+    queryParams: string
+}
+
+type SearchMultiDimViewHit = BaseSearchChartHit & {
+    type: ChartRecordType.MultiDimView
+    queryParams: string
+    chartConfigId: string
+}
+
+/**
+ * This is the type for the hits that we get back from algolia when we search
+ * response.results[0].hits is an array of these
+ */
+export type SearchChartHit =
+    | SearchChartViewHit
+    | SearchExplorerViewHit
+    | SearchMultiDimViewHit
+
+export interface SearchChartHitComponentProps {
+    hit: SearchChartHit
+    selectedRegionNames?: string[] | undefined
+    // Search uses a global onClick handler to track analytics
+    // But the data catalog passes a function to this component explicitly
+    onClick: (vizType: string | null) => void
+}
+
+export type SearchChartHitComponentVariant = "large" | "medium" | "small"
+
+// SearchResponse adds the extra fields from Algolia: page, nbHits, etc
+export type SearchChartsResponse = SearchResponse<SearchChartHit>
+
+export type SearchDataTopicsResponse = {
+    title: string
+    charts: SearchResponse<SearchChartHit>
+}
+
+export type ScoredFilter = Filter & {
+    name: string
+    score: number
+}
+
+export type ScoredFilterPositioned = ScoredFilter & {
+    positions: number[]
+}
+
+export type DataInsightHit = {
+    title: string
+    thumbnailUrl: string
+    date: string
+    slug: string
+    type: OwidGdocType.DataInsight
+    objectID: string
+    __position: number
+}
+
+export type SearchDataInsightResponse = SearchResponse<DataInsightHit>
+
+export type FlatArticleHit = {
+    title: string
+    thumbnailUrl: string
+    date: string
+    slug: string
+    type: OwidGdocType.Article | OwidGdocType.AboutPage
+    content: string
+    authors: string[]
+    objectID: string
+    __position: number
+}
+
+export type StackedArticleHit = {
+    title: string
+    thumbnailUrl: string
+    slug: string
+    type: OwidGdocType.Article | OwidGdocType.AboutPage
+    content: string
+    objectID: string
+    __position: number
+}
+
+export type SearchStackedArticleResponse = SearchResponse<StackedArticleHit>
+export type SearchFlatArticleResponse = SearchResponse<FlatArticleHit>
+
+export type TopicPageHit = {
+    title: string
+    type: OwidGdocType.TopicPage | OwidGdocType.LinearTopicPage
+    slug: string
+    excerpt: string
+    excerptLong?: string[]
+    objectID: string
+    __position: number
+}
+
+export type SearchTopicPageResponse = SearchResponse<TopicPageHit>
+
+export type SearchWritingTopicsResponse = {
+    title: string
+    articles: SearchStackedArticleResponse
+    topicPages: SearchTopicPageResponse
+    totalCount: number
+}
+
+export enum FilterType {
+    COUNTRY = "country",
+    TOPIC = "topic",
+    QUERY = "query",
+}
+
+export enum SearchResultType {
+    ALL = "all",
+    DATA = "data",
+    WRITING = "writing",
+}
+
+export type Filter = {
+    type: FilterType
+    name: string
+}
+
+export enum SearchUrlParam {
+    COUNTRY = "countries",
+    TOPIC = "topics",
+    QUERY = "q",
+    REQUIRE_ALL_COUNTRIES = "requireAllCountries",
+    RESULT_TYPE = "resultType",
+}
+
+export type SearchState = Readonly<{
+    query: string
+    filters: Filter[]
+    requireAllCountries: boolean
+    resultType: SearchResultType
+}>
+
+export interface SearchActions {
+    setQuery: (query: string) => void
+    addCountry: (country: string) => void
+    addCountryAndSetQuery: (country: string, query: string) => void
+    removeCountry: (country: string) => void
+    setTopic: (topic: string) => void
+    setTopicAndClearQuery: (topic: string) => void
+    removeTopic: (topic: string) => void
+    addFilter: (filter: Filter) => void
+    removeFilter: (filter: Filter) => void
+    toggleRequireAllCountries: () => void
+    setResultType: (resultType: SearchResultType) => void
+    replaceQueryWithFilter: (filter: ScoredFilterPositioned) => void
+    reset: () => void
+}
+
+export enum SearchTopicType {
+    Topic = "topic",
+    Area = "area",
+}
+
+export interface TemplateConfig {
+    resultType: SearchResultType
+    topicType: SearchTopicType | null
+    hasCountry: boolean
+    hasQuery: boolean
+}
+
+export type SearchFacetFilters = (string | string[])[]
+
+export type SynonymMap = Map<string, string[]>
+
+export interface WordPositioned {
+    word: string
+    position: number
+}
+
+export type Ngram = WordPositioned[]

package/src/types/domainTypes/Site.ts

@@ -0,0 +1,8 @@
+export interface BreadcrumbItem {
+    label: string
+    href?: string
+}
+
+export interface KeyValueProps {
+    [key: string]: string | boolean | undefined
+}