@ca-plant-list/ca-plant-list 0.4.21 → 0.4.23

package/lib/htmltaxon.js

@@ -1,20 +1,13 @@
 import { Config } from "./config.js";
 import { DateUtils } from "./dateutils.js";
+import { ExternalSites } from "./externalsites.js";
 import { HTML } from "./html.js";
 import { Markdown } from "./markdown.js";
 import { RarePlants } from "./rareplants.js";
 import { TextUtils } from "./textutils.js";
 
 /**
- * @typedef {{
-    class?: string;
-    data: (taxon: import("./taxon.js").Taxon) => string;
-    title: string;
-     }} TaxaColDef
- */
-
-/**
- * @type {Record<string,TaxaColDef>}
+ * @type {Record<string,import("./types.js").TaxaColDef>}
  */
 const TAXA_LIST_COLS = {
     CESA: {
@@ -30,7 +23,7 @@ const TAXA_LIST_COLS = {
         data: (t) =>
             HTML.getToolTip(
                 HTML.textElement("span", t.getRPIRankAndThreat()),
-                t.getRPIRankAndThreatTooltip(),
+                HTMLTaxon.getRPIRankAndThreatTooltip(t),
             ),
     },
     FESA: {
@@ -39,49 +32,105 @@ const TAXA_LIST_COLS = {
     },
     SPECIES: {
         title: "Species",
-        data: (t) => t.getHTMLLink(true, true),
+        data: (t) => HTMLTaxon.getHTMLLink(t, true, true),
     },
     SPECIES_BARE: {
         title: "Species",
-        data: (t) => t.getHTMLLink(true, false),
+        data: (t) => HTMLTaxon.getHTMLLink(t, true, false),
     },
 };
 
-/** @type {TaxaColDef[]} */
+/** @type {import("./types.js").TaxaColDef[]} */
 const DEFAULT_TAXA_COLUMNS = [
     TAXA_LIST_COLS.SPECIES,
     TAXA_LIST_COLS.COMMON_NAME,
 ];
 
+/** @type {Object<string,{label:string,href:function(import("./types.js").Taxon,import("./types.js").Config):URL|undefined}>} */
+const OBSLINKS = {
+    calflora: {
+        label: "Calflora",
+        href: (taxon, config) =>
+            ExternalSites.getCalfloraObsLink(taxon, config),
+    },
+    cch: {
+        label: "CCH2",
+        href: (taxon, config) => ExternalSites.getCCH2ObsLink(taxon, config),
+    },
+    inat: {
+        label: "iNaturalist",
+        href: (taxon, config) => ExternalSites.getInatObsLink(taxon, config),
+    },
+};
+
+/** @type {Object<string,{label:string,href:function(import("./types.js").Taxon):URL|undefined}>} */
+const REFLINKS = {
+    calflora: {
+        label: "Calflora",
+        href: (taxon) => ExternalSites.getCalfloraRefLink(taxon),
+    },
+    calscape: {
+        label: "Calscape",
+        href: (taxon) => ExternalSites.getCalscapeLink(taxon),
+    },
+    cch: {
+        label: "CCH2",
+        href: (taxon) => ExternalSites.getCCH2RefLink(taxon),
+    },
+    fna: {
+        label: "Flora of North America",
+        href: (taxon) => ExternalSites.getFNARefLink(taxon),
+    },
+    inat: {
+        label: "iNaturalist",
+        href: (taxon) => ExternalSites.getINatRefLink(taxon),
+    },
+    jepson: {
+        label: "Jepson eFlora",
+        href: (taxon) => ExternalSites.getJepsonRefLink(taxon),
+    },
+    rpi: {
+        label: "CNPS Rare Plant Inventory",
+        href: (taxon) => ExternalSites.getRPIRefLink(taxon),
+    },
+};
+
 class HTMLTaxon {
     /**
      * @param {string[]} links
      * @param {URL|string|undefined} href
      * @param {string} label
+     * @param {string} [suffix=""]
      */
-    static addLink(links, href, label) {
+    static addLink(links, href, label, suffix = "") {
         if (href === undefined) {
             return;
         }
         const link = HTML.getLink(href.toString(), label, {}, true);
-        links.push(link);
+        links.push(link + suffix);
     }
 
     /**
-     * @param {import("./taxon.js").Taxon} taxon
-     * @returns {string|undefined}
+     * @param {string[]} links
+     * @param {import("./types.js").Taxon} taxon
+     * @param {import("./types.js").Config} config
+     * @param {import("./index.js").RefSourceCode} sourceCode
+     * @param {string} [label]
      */
-    static getCalscapeLink(taxon) {
-        const calscapeCN = taxon.getCalscapeCommonName();
-        if (!calscapeCN) {
-            return;
-        }
-        return HTML.getLink(
-            `https://www.calscape.org/${taxon.getCalscapeName().replaceAll(" ", "-")}-()`,
-            "Calscape",
-            {},
-            true,
-        );
+    static addObsLink(links, taxon, config, sourceCode, label) {
+        const source = OBSLINKS[sourceCode];
+        this.addLink(links, source.href(taxon, config), label ?? source.label);
+    }
+
+    /**
+     * @param {string[]} links
+     * @param {import("./types.js").Taxon} taxon
+     * @param {import("./index.js").RefSourceCode} sourceCode
+     * @param {string} [suffix=""]
+     */
+    static addRefLink(links, taxon, sourceCode, suffix = "") {
+        const source = REFLINKS[sourceCode];
+        this.addLink(links, source.href(taxon), source.label, suffix);
     }
 
     /**
@@ -110,7 +159,7 @@ class HTMLTaxon {
     }
 
     /**
-     * @param {import("./taxon.js").Taxon} taxon
+     * @param {import("./types.js").Taxon} taxon
      * @param {string} classNames
      * @param {boolean} [includeColorLink=true]
      */
@@ -151,7 +200,7 @@ class HTMLTaxon {
     }
 
     /**
-     * @param {import("./taxon.js").Taxon} taxon
+     * @param {import("./types.js").Taxon} taxon
      * @returns {string}
      */
     static getFooterHTML(taxon) {
@@ -164,7 +213,38 @@ class HTMLTaxon {
     }
 
     /**
-     * @param {import("./taxon.js").Taxon} taxon
+     * @param {import("./types.js").Taxon} taxon
+     * @param {boolean|string|undefined} href
+     * @param {boolean} includeRPI
+     */
+    static getHTMLLink(taxon, href = true, includeRPI = true) {
+        href = href ? "./" + taxon.getFileName() : undefined;
+        let className = taxon.isNative() ? "native" : "non-native";
+        let isRare = false;
+        if (includeRPI && taxon.isRare()) {
+            isRare = true;
+            className += " rare";
+        }
+        const attributes = { class: className };
+        const link = HTML.wrap(
+            "span",
+            HTML.getLink(href, taxon.getName()),
+            attributes,
+        );
+        if (isRare) {
+            return HTML.getToolTip(
+                link,
+                this.getRPIRankAndThreatTooltip(taxon),
+                {
+                    icon: false,
+                },
+            );
+        }
+        return link;
+    }
+
+    /**
+     * @param {import("./types.js").Taxon} taxon
      */
     static getLink(taxon) {
         return (
@@ -204,8 +284,17 @@ class HTMLTaxon {
     }
 
     /**
-     * @param {import("./taxon.js").Taxon[]} taxa
-     * @param {TaxaColDef[]} [columns]
+     * @param {import("./types.js").Taxon} taxon
+     */
+    static getRPIRankAndThreatTooltip(taxon) {
+        return RarePlants.getRPIRankAndThreatDescriptions(
+            taxon.getRPIRankAndThreat(),
+        ).join("<br>");
+    }
+
+    /**
+     * @param {import("./types.js").Taxon[]} taxa
+     * @param {import("./types.js").TaxaColDef[]} [columns]
      */
     static getTaxaTable(taxa, columns = DEFAULT_TAXA_COLUMNS) {
         let html = "<table><thead>";

package/lib/index.d.ts

@@ -4,7 +4,28 @@ import { Command } from "commander";
 
 export type NativeStatusCode = "N" | "NC" | "U" | "X";
 
-export type TaxonData = {
+type PhotoRights = "CC0" | "CC BY" | "CC BY-NC" | "C" | null;
+
+type RefSourceCode =
+    | "calflora"
+    | "calscape"
+    | "cch"
+    | "fna"
+    | "inat"
+    | "jepson"
+    | "rpi";
+
+type TaxaColDef<T> = {
+    title: string;
+    class?: string;
+    data: (taxon: T) => string | number;
+};
+
+type TaxonomyData = {
+    "jepson id": string;
+};
+
+export type TaxonData = TaxonomyData & {
     bloom_end: string;
     bloom_start: string;
     calrecnum: string;
@@ -14,10 +35,10 @@ export type TaxonData = {
     "common name": string;
     CRPR: string;
     FESA: string;
+    fna: string;
     flower_color: string;
     GRank: string;
     "inat id": string;
-    "jepson id": string;
     life_cycle: string;
     "RPI ID": string;
     SRank: string;
@@ -27,6 +48,14 @@ export type TaxonData = {
 
 // Classes
 
+export class BasePageRenderer {
+    static renderBasePages<T extends Taxon>(
+        outputDir: string,
+        taxa: Taxa<T>,
+        familyCols?: TaxaColDef<T>[],
+    ): void;
+}
+
 export class Config {
     constructor(dataDir: string);
     getConfigValue(
@@ -40,7 +69,10 @@ export class Config {
 }
 
 export class CSV {
-    static parseFile(dir: string, fileName: string): Record<string, string>[];
+    static readFile(
+        fileName: string,
+        delimeter?: string,
+    ): Record<string, string>[];
 }
 
 export class ErrorLog {
@@ -61,11 +93,6 @@ export class Exceptions {
     hasException(name: string, cat: string, subcat: string): boolean;
 }
 
-export class ExternalSites {
-    static getCCH2ObsLink(taxon: Taxon, config: Config): URL | undefined;
-    static getCCH2RefLink(taxon: Taxon): URL | undefined;
-}
-
 export class Family {
     getName(): string;
 }
@@ -78,31 +105,37 @@ export class Files {
     ): Promise<Headers>;
     static mkdir(dir: string): void;
     static rmDir(dir: string): void;
-    static write(fileName: string, data: string, overwrite: boolean): void;
+    static write(fileName: string, data: string, overwrite?: boolean): void;
 }
 
 export class Genera {}
 
-export class Genus {
-    getTaxa(): Taxon[];
+export class Genus<T extends Taxon> {
+    getTaxa(): T[];
 }
 
 export class HTML {
     static arrayToLI(items: string[]): string;
+    static escapeText(text: string): string;
     static getLink(
         href: string | undefined,
         linkText: string,
         attrs?: Record<string, string> | string,
         openInNewWindow?: boolean,
     ): string;
+    static getToolTip(
+        text: string,
+        tooltip: string,
+        options?: { icon: boolean },
+    ): string;
     static textElement(
         elName: string,
-        text: string,
+        text: string | number,
         attrs?: Record<string, string>,
     ): string;
     static wrap(
         elName: string,
-        text: string,
+        text: string | number,
         attrs?: string | Record<string, string> | undefined,
     ): string;
 }
@@ -113,6 +146,18 @@ export class HTMLTaxon {
         href: URL | string | undefined,
         label: string,
     ): void;
+    static addObsLink(
+        links: string[],
+        taxon: Taxon,
+        config: Config,
+        sourceCode: RefSourceCode,
+        label?: string,
+    ): void;
+    static addRefLink(
+        links: string[],
+        taxon: Taxon,
+        sourceCode: RefSourceCode,
+    ): void;
     static getFooterHTML(taxon: Taxon): string;
     static getListSectionHTML(
         list: string[],
@@ -123,11 +168,10 @@ export class HTMLTaxon {
 }
 
 export class Jekyll {
+    static hasInclude(baseDir: string, path: string): boolean;
     static include(fileName: string): string;
 }
 
-type PhotoRights = "CC0" | "CC BY" | "CC BY-NC" | "C" | null;
-
 export class Photo {
     getAttribution(): string;
     getExt(): string;
@@ -141,38 +185,39 @@ export class Program {
     static getProgram(): Command;
 }
 
-export class Taxa {
+export class Taxa<T> {
     constructor(
         inclusionList: Record<string, TaxonData> | true,
         errorLog: ErrorLog,
         showFlowerErrors: boolean,
-        taxonFactory?: (td: TaxonData, g: Genera) => Taxon,
+        taxonFactory?: (td: TaxonData, g: Genera) => T,
         extraTaxa?: TaxonData[],
         extraSynonyms?: Record<string, string>[],
     );
-    getTaxon(name: string): Taxon;
-    getTaxonList(): Taxon[];
+    getTaxon(name: string): T;
+    getTaxonList(): T[];
 }
 
 export class Taxon {
+    constructor(data: TaxonData, genera: Genera);
     getBaseFileName(): string;
     getCalfloraID(): string;
-    getCalfloraTaxonLink(): string;
-    getCESA(): string | undefined;
-    getCNDDBRank(): string | undefined;
+    getCalfloraName(): string;
+    getCESA(): string;
+    getCNDDBRank(): string;
     getCommonNames(): string[];
     getFamily(): Family;
     getFileName(): string;
-    getFESA(): string | undefined;
-    getGenus(): Genus;
+    getFESA(): string;
+    getGenus<T extends Taxon>(): Genus<T>;
     getGenusName(): string;
-    getGlobalRank(): string | undefined;
+    getGlobalRank(): string;
     getINatID(): string;
-    getINatTaxonLink(): string;
+    getINatName(): string;
     getJepsonID(): string;
     getName(): string;
     getPhotos(): Photo[];
+    getRPIRank(): string;
     getRPIRankAndThreat(): string;
-    getRPITaxonLink(): string;
     getSynonyms(): string[];
 }

package/lib/index.js

@@ -4,15 +4,15 @@ import { CSV } from "./csv.js";
 import { ErrorLog } from "./errorlog.js";
 import { Exceptions } from "./exceptions.js";
 import { ExternalSites } from "./externalsites.js";
-import { Families } from "./families.js";
+import { Families } from "./taxonomy/families.js";
 import { Files } from "./files.js";
 import { HTML } from "./html.js";
 import { HTMLTaxon } from "./htmltaxon.js";
 import { Jekyll } from "./jekyll.js";
 import { PlantBook } from "./ebook/plantbook.js";
 import { Program } from "./program.js";
-import { Taxa } from "./taxa.js";
-import { Taxon } from "./taxon.js";
+import { Taxa } from "./taxonomy/taxa.js";
+import { Taxon } from "./taxonomy/taxon.js";
 
 export {
     BasePageRenderer,

package/lib/pagerenderer.js

@@ -22,7 +22,7 @@ class PageRenderer extends BasePageRenderer {
     /**
      * @param {string} outputDir
      * @param {import('./config.js').Config} config
-     * @param {import("./taxa.js").Taxa} taxa
+     * @param {import("./types.js").Taxa} taxa
      */
     static render(outputDir, config, taxa) {
         super.renderBasePages(outputDir, taxa);
@@ -38,13 +38,13 @@ class PageRenderer extends BasePageRenderer {
     /**
      * @param {string} outputDir
      * @param {import('./config.js').Config} config
-     * @param {import("./taxa.js").Taxa} taxa
+     * @param {import("./types.js").Taxa} taxa
      */
     static renderLists(outputDir, config, taxa) {
         /**
          * @param {ListInfo[]} listInfo
          * @param {Object<string,string>} attributes
-         * @param {import("./htmltaxon.js").TaxaColDef[]} [columns]
+         * @param {import("./types.js").TaxaColDef[]} [columns]
          * @returns {string}
          */
         function getListArray(listInfo, attributes = {}, columns) {
@@ -117,7 +117,7 @@ class PageRenderer extends BasePageRenderer {
             return html;
         }
 
-        /** @typedef {{name:string,filename:string,include:function(import("./taxon.js").Taxon):boolean,columns?:import("./htmltaxon.js").TaxaColDef[],listInfo?:ListInfo[]}} ListInfo */
+        /** @typedef {{name:string,filename:string,include:function(import("./types.js").Taxon):boolean,columns?:import("./types.js").TaxaColDef[],listInfo?:ListInfo[]}} ListInfo */
         /** @type {{title:string,listInfo:ListInfo[]}[]} */
         const sections = [
             {
@@ -227,8 +227,8 @@ class PageTaxonList extends GenericPage {
 
     /**
      *
-     * @param {import("./taxon.js").Taxon[]} taxa
-     * @param {import("./htmltaxon.js").TaxaColDef[]|undefined} columns
+     * @param {import("./types.js").Taxon[]} taxa
+     * @param {import("./types.js").TaxaColDef[]|undefined} columns
      */
     render(taxa, columns) {
         let html = this.getDefaultIntro();

package/lib/taxonomy/families.js

@@ -0,0 +1,104 @@
+import { Files } from "../files.js";
+import { Config } from "../config.js";
+import { Taxonomy } from "./taxonomy.js";
+
+/**
+ * @typedef {{id:string,section:string,taxa?:import("../types.js").Taxon[]}} FamilyData
+ */
+
+export class Family extends Taxonomy {
+    #name;
+    #data;
+
+    /**
+     * @param {string} name
+     * @param {FamilyData} data
+     */
+    constructor(name, data) {
+        super({ "jepson id": data.id });
+        this.#name = name;
+        this.#data = data;
+    }
+
+    /**
+     * @param {import("../types.js").Taxon} taxon
+     */
+    addTaxon(taxon) {
+        if (!this.#data.taxa) {
+            this.#data.taxa = [];
+        }
+        this.#data.taxa.push(taxon);
+        Sections.addTaxon(this.getSectionName(), taxon);
+    }
+
+    getBaseFileName() {
+        return this.getName();
+    }
+
+    getFileName(ext = "html") {
+        return this.getBaseFileName() + "." + ext;
+    }
+
+    getName() {
+        return this.#name;
+    }
+
+    getSectionName() {
+        return this.#data.section;
+    }
+
+    getTaxa() {
+        return this.#data.taxa;
+    }
+}
+
+export class Families {
+    #families;
+
+    constructor() {
+        const dataDir = Config.getPackageDir() + "/data";
+
+        this.#families = JSON.parse(Files.read(dataDir + "/families.json"));
+        for (const [k, v] of Object.entries(this.#families)) {
+            this.#families[k] = new Family(k, v);
+        }
+    }
+
+    /**
+     * @returns {Family[]}
+     */
+    getFamilies() {
+        return Object.values(this.#families).sort((a, b) =>
+            a.getName().localeCompare(b.getName()),
+        );
+    }
+
+    /**
+     * @param {string} familyName
+     */
+    getFamily(familyName) {
+        return this.#families[familyName];
+    }
+}
+
+export class Sections {
+    /** @type {Object<string,import("../types.js").Taxon[]>} */
+    static #sections = {};
+
+    /**
+     * @param {string} name
+     * @param {import("../types.js").Taxon} taxon
+     */
+    static addTaxon(name, taxon) {
+        let section = this.#sections[name];
+        if (!section) {
+            section = [];
+            this.#sections[name] = section;
+        }
+        section.push(taxon);
+    }
+
+    static getSections() {
+        return this.#sections;
+    }
+}

package/lib/{taxa.js → taxonomy/taxa.js}

@@ -1,16 +1,16 @@
 import * as fs from "node:fs";
 import path from "node:path";
 
-import { Config } from "./config.js";
-import { CSV } from "./csv.js";
-import { Genera } from "./genera.js";
+import { Config } from "../config.js";
+import { CSV } from "../csv.js";
+import { Genera } from "../genera.js";
 import { Taxon } from "./taxon.js";
 import { Families } from "./families.js";
-import { FlowerColor } from "./flowercolor.js";
-import { TaxaCSV } from "./tools/taxacsv.js";
-import { ErrorLog } from "./errorlog.js";
-import { Program } from "./program.js";
-import { Photo } from "./photo.js";
+import { FlowerColor } from "../flowercolor.js";
+import { TaxaCSV } from "../tools/taxacsv.js";
+import { ErrorLog } from "../errorlog.js";
+import { Program } from "../program.js";
+import { Photo } from "../photo.js";
 
 /**
  * @typedef {{Current: string;Former: string;Type: string;}} SynonymData
@@ -40,11 +40,11 @@ class Taxa {
     #isSubset;
 
     /**
-     * @param {Object<string,import("./index.js").TaxonData>|true} inclusionList
+     * @param {Object<string,import("../index.js").TaxonData>|true} inclusionList
      * @param {ErrorLog} errorLog
      * @param {boolean} showFlowerErrors
-     * @param {function(import("./index.js").TaxonData,Genera):Taxon} taxonFactory
-     * @param {import("./index.js").TaxonData[]} [extraTaxa=[]]
+     * @param {function(import("../index.js").TaxonData,Genera):Taxon} taxonFactory
+     * @param {import("../index.js").TaxonData[]} [extraTaxa=[]]
      * @param {SynonymData[]} [extraSynonyms=[]]
      * @param {boolean} includePhotos
      */
@@ -114,9 +114,9 @@ class Taxa {
      */
     #loadPhotosFromFile(dataDir, filename) {
         if (!fs.existsSync(path.join(dataDir, filename))) return;
-        /** @type {import("./utils/inat-tools.js").InatCsvPhoto[]} */
+        /** @type {import("../utils/inat-tools.js").InatCsvPhoto[]} */
         const csvPhotos = CSV.parseFile(dataDir, filename).map((row) => {
-            /** @type {import("./utils/inat-tools.js").InatLicenseCode} */
+            /** @type {import("../utils/inat-tools.js").InatLicenseCode} */
             let licenseCode = "cc-by";
             if (row.licenseCode === "cc-by-nc-sa") licenseCode = "cc-by-nc-sa";
             else if (row.licenseCode === "cc-by-nc") licenseCode = "cc-by-nc";
@@ -224,7 +224,7 @@ class Taxa {
 
     /**
      * @param {SynonymData[]} synCSV
-     * @param {Object<string,import("./index.js").TaxonData>|boolean} inclusionList
+     * @param {Object<string,import("../index.js").TaxonData>|boolean} inclusionList
      */
     #loadSyns(synCSV, inclusionList) {
         for (const syn of synCSV) {
@@ -245,9 +245,9 @@ class Taxa {
     }
 
     /**
-     * @param {import("./index.js").TaxonData[]} taxaCSV
-     * @param {Object<string,import("./index.js").TaxonData>|true} inclusionList
-     * @param {function(import("./index.js").TaxonData,Genera):Taxon} taxonFactory
+     * @param {import("../index.js").TaxonData[]} taxaCSV
+     * @param {Object<string,import("../index.js").TaxonData>|true} inclusionList
+     * @param {function(import("../index.js").TaxonData,Genera):Taxon} taxonFactory
      * @param {Genera} genera
      * @param {boolean} showFlowerErrors
      */
@@ -255,7 +255,7 @@ class Taxa {
         for (const row of taxaCSV) {
             const name = row["taxon_name"];
 
-            /** @type {import("./index.js").TaxonData|{status?:import("./index.js").NativeStatusCode}} */
+            /** @type {import("../index.js").TaxonData|{status?:import("../index.js").NativeStatusCode}} */
             let taxon_overrides = {};
             if (inclusionList !== true) {
                 taxon_overrides = inclusionList[name];