@ca-plant-list/ca-plant-list 0.3.6 → 0.4.0

package/lib/exceptions.js

@@ -2,55 +2,71 @@ import { Config } from "./config.js";
 import { Files } from "./files.js";
 
 class Exceptions {
-
+    /** @type {Object<string,Object<string,Object<string,{}>>>} */
     #exceptions = {};
 
-    constructor( dir ) {
-
-        function readConfig( fileName ) {
-            return JSON.parse( Files.read( fileName ) );
+    /**
+     * @param {string} dir
+     */
+    constructor(dir) {
+        /**
+         * @param {string} fileName
+         */
+        function readConfig(fileName) {
+            return JSON.parse(Files.read(fileName));
         }
 
         // Read default configuration.
-        this.#exceptions = readConfig( Config.getPackageDir() + "/data/exceptions.json" );
+        this.#exceptions = readConfig(
+            Config.getPackageDir() + "/data/exceptions.json"
+        );
 
         // Add/overwrite with local configuration.
-        const localExceptions = readConfig( dir + "/exceptions.json" );
-        for ( const [ k, v ] of Object.entries( localExceptions ) ) {
-            this.#exceptions[ k ] = v;
+        const localExceptions = readConfig(dir + "/exceptions.json");
+        for (const [k, v] of Object.entries(localExceptions)) {
+            this.#exceptions[k] = v;
             // Tag as a local exception so we can distinguish between global and local.
             v.local = true;
         }
-
     }
 
     getExceptions() {
-        return Object.entries( this.#exceptions );
+        return Object.entries(this.#exceptions);
     }
 
-    getValue( name, cat, subcat, defaultValue ) {
-        const taxonData = this.#exceptions[ name ];
-        if ( taxonData ) {
-            const catData = taxonData[ cat ];
-            if ( catData ) {
-                const val = catData[ subcat ];
-                return ( val === undefined ) ? defaultValue : val;
+    /**
+     * @param {string} name
+     * @param {string} cat
+     * @param {string} subcat
+     * @param {string} defaultValue
+     */
+    getValue(name, cat, subcat, defaultValue) {
+        const taxonData = this.#exceptions[name];
+        if (taxonData) {
+            const catData = taxonData[cat];
+            if (catData) {
+                const val = catData[subcat];
+                return val === undefined ? defaultValue : val;
             }
         }
         return defaultValue;
     }
 
-    hasException( name, cat, subcat ) {
-        const taxonData = this.#exceptions[ name ];
-        if ( taxonData ) {
-            const catData = taxonData[ cat ];
-            if ( catData ) {
-                return catData[ subcat ] !== undefined;
+    /**
+     * @param {string} name
+     * @param {string} cat
+     * @param {string} subcat
+     */
+    hasException(name, cat, subcat) {
+        const taxonData = this.#exceptions[name];
+        if (taxonData) {
+            const catData = taxonData[cat];
+            if (catData) {
+                return catData[subcat] !== undefined;
             }
         }
         return false;
     }
-
 }
 
-export { Exceptions };
+export { Exceptions };

package/lib/externalsites.js

@@ -1,4 +1,7 @@
 class ExternalSites {
+    /**
+     * @param {InatObsOptions} options
+     */
     static getInatObsLink(options) {
         const url = new URL(
             "https://www.inaturalist.org/observations?subview=map"
@@ -9,10 +12,14 @@ class ExternalSites {
                 case "coords": {
                     const delta = 0.1;
                     const params = url.searchParams;
-                    params.set("nelat", v[1] + delta);
-                    params.set("swlat", v[1] - delta);
-                    params.set("nelng", v[0] + delta);
-                    params.set("swlng", v[0] - delta);
+                    /** @type {number} */
+                    const lat = v[1];
+                    /** @type {number} */
+                    const lng = v[0];
+                    params.set("nelat", (lat + delta).toString());
+                    params.set("swlat", (lat - delta).toString());
+                    params.set("nelng", (lng + delta).toString());
+                    params.set("swlng", (lng - delta).toString());
                     break;
                 }
                 case "created_d1":

package/lib/families.js

@@ -1,11 +1,9 @@
 import { GenericPage } from "./genericpage.js";
 import { HTML } from "./html.js";
 import { Jepson } from "./jepson.js";
-import { Taxa } from "./taxa.js";
 import { Files } from "./files.js";
 import { Config } from "./config.js";
-// eslint-disable-next-line no-unused-vars
-import { Taxon } from "./index.js";
+import { HTMLTaxon } from "./htmltaxon.js";
 
 class Family {
     #name;
@@ -83,7 +81,7 @@ class Families {
 
     /**
      * @param {string} outputDir
-     * @param {import("./index.js").TaxaCol[]} taxaColumns
+     * @param {TaxaCol[]} taxaColumns
      */
     renderPages(outputDir, taxaColumns) {
         new PageFamilyList(outputDir, this.#families).render(taxaColumns);
@@ -111,7 +109,7 @@ class PageFamilyList extends GenericPage {
     }
 
     /**
-     * @param {import("./index.js").TaxaCol[]} taxaColumns
+     * @param {TaxaCol[]} taxaColumns
      */
     render(taxaColumns) {
         let html = this.getDefaultIntro();
@@ -178,8 +176,7 @@ class PageFamily extends GenericPage {
     }
 
     /**
-     *
-     * @param {import("./index.js").TaxaCol[]} columns
+     * @param {TaxaCol[]} columns
      */
     render(columns) {
         let html = this.getDefaultIntro();
@@ -190,7 +187,7 @@ class PageFamily extends GenericPage {
             { class: "section" }
         );
 
-        html += Taxa.getHTMLTable(this.#family.getTaxa(), columns);
+        html += HTMLTaxon.getTaxaTable(this.#family.getTaxa(), columns);
 
         this.writeFile(html);
     }
@@ -209,17 +206,20 @@ class PageSection extends GenericPage {
         this.#taxa = taxa;
     }
 
+    /**
+     * @param {TaxaCol[]} [columns]
+     */
     render(columns) {
         let html = this.getDefaultIntro();
 
-        html += Taxa.getHTMLTable(this.#taxa, columns);
+        html += HTMLTaxon.getTaxaTable(this.#taxa, columns);
 
         this.writeFile(html);
     }
 }
 
 class Sections {
-    /** @type {Object<string,Taxon[]} */
+    /** @type {Object<string,Taxon[]>} */
     static #sections = {};
 
     /**

package/lib/flowercolor.js

@@ -0,0 +1,42 @@
+import { TextUtils } from "./textutils.js";
+
+class FlowerColor {
+    #colorName;
+    #colorCode;
+    /** @type {Taxon[]} */
+    #taxa = [];
+
+    /**
+     * @param {string} colorName
+     * @param {string} [colorCode]
+     */
+    constructor(colorName, colorCode) {
+        this.#colorName = colorName;
+        this.#colorCode = colorCode ? colorCode : colorName;
+    }
+
+    /**
+     * @param {Taxon} taxon
+     */
+    addTaxon(taxon) {
+        this.#taxa.push(taxon);
+    }
+
+    getColorCode() {
+        return this.#colorCode;
+    }
+
+    getColorName(uc = false) {
+        return uc ? TextUtils.ucFirst(this.#colorName) : this.#colorName;
+    }
+
+    getFileName() {
+        return "list_fc_" + this.#colorName + ".html";
+    }
+
+    getTaxa() {
+        return this.#taxa;
+    }
+}
+
+export { FlowerColor };

package/lib/genera.js

@@ -1,8 +1,5 @@
 import { Config } from "./config.js";
-import { Families } from "./families.js";
 import { Files } from "./files.js";
-// eslint-disable-next-line no-unused-vars
-import { Taxon } from "./taxon.js";
 
 class Genera {
     #families;
@@ -24,21 +21,17 @@ class Genera {
         const genusName = taxon.getGenusName();
         const genusData = this.#genera[genusName];
         if (!genusData) {
-            console.log(taxon.getName() + " genus not found");
-            return;
+            throw new Error(taxon.getName() + " genus not found");
         }
 
-        if (genusData.taxa === undefined) {
+        if (genusData.familyObj === undefined) {
+            // Initialize genus data.
+            genusData.familyObj = this.#families.getFamily(genusData.family);
             genusData.taxa = [];
         }
-        genusData.taxa.push(taxon);
+        genusData.familyObj.addTaxon(taxon);
 
-        const family = this.getFamily(genusName);
-        if (!family) {
-            console.log(taxon.getName() + " family not found");
-            return;
-        }
-        family.addTaxon(taxon);
+        genusData.taxa.push(taxon);
     }
 
     /**
@@ -47,25 +40,22 @@ class Genera {
     getGenus(genusName) {
         return new Genus(this.#genera[genusName]);
     }
-
-    /**
-     * @param {string} genusName
-     */
-    getFamily(genusName) {
-        const genus = this.#genera[genusName];
-        if (genus) {
-            return this.#families.getFamily(genus.family);
-        }
-    }
 }
 
 class Genus {
     #data;
 
+    /**
+     * @param {{family:string,familyObj:Family,taxa:Taxon[]}} data
+     */
     constructor(data) {
         this.#data = data;
     }
 
+    getFamily() {
+        return this.#data.familyObj;
+    }
+
     getTaxa() {
         return this.#data.taxa.sort((a, b) =>
             a.getName().localeCompare(b.getName())

package/lib/genericpage.js

@@ -1,14 +1,22 @@
-import { Config, Files, HTML, Jekyll } from "@ca-plant-list/ca-plant-list";
+import { Config } from "./config.js";
+import { Files } from "./files.js";
+import { HTML } from "./html.js";
+import { Jekyll } from "./jekyll.js";
 import { Markdown } from "./markdown.js";
 
 class GenericPage {
-
     #outputDir;
     #title;
     #baseFileName;
     #js;
 
-    constructor( outputDir, title, baseFileName, js ) {
+    /**
+     * @param {string} outputDir
+     * @param {string} title
+     * @param {string} baseFileName
+     * @param {string} [js]
+     */
+    constructor(outputDir, title, baseFileName, js) {
         this.#outputDir = outputDir;
         this.#title = title;
         this.#baseFileName = baseFileName;
@@ -25,31 +33,41 @@ class GenericPage {
     }
 
     getFrontMatter() {
-        return "---\n"
-            + "title: \"" + this.#title + "\"\n"
-            + ( this.#js ? ( "js: " + this.#js + "\n" ) : "" )
-            + "---\n";
+        return (
+            "---\n" +
+            'title: "' +
+            this.#title +
+            '"\n' +
+            (this.#js ? "js: " + this.#js + "\n" : "") +
+            "---\n"
+        );
     }
 
     getMarkdown() {
         // Include site-specific markdown.
-        let html = this.#getMarkdown( "intros" );
+        let html = this.#getMarkdown("intros");
 
         // Include package markdown.
-        const mdPath = Config.getPackageDir() + "/data/text/" + this.#baseFileName + ".md";
-        if ( Files.exists( mdPath ) ) {
-            html += HTML.wrap( "div", Markdown.fileToHTML( mdPath ), { class: "section" } );
+        const mdPath =
+            Config.getPackageDir() + "/data/text/" + this.#baseFileName + ".md";
+        if (Files.exists(mdPath)) {
+            html += HTML.wrap("div", Markdown.fileToHTML(mdPath), {
+                class: "section",
+            });
         }
 
         return html;
     }
 
-    #getMarkdown( path ) {
+    /**
+     * @param {string} path
+     */
+    #getMarkdown(path) {
         const textPath = path + "/" + this.#baseFileName + ".md";
-        if ( !Jekyll.hasInclude( this.#outputDir, textPath ) ) {
+        if (!Jekyll.hasInclude(this.#outputDir, textPath)) {
             return "";
         }
-        return HTML.wrap( "div", Jekyll.include( textPath ), { class: "section" } );
+        return HTML.wrap("div", Jekyll.include(textPath), { class: "section" });
     }
 
     getOutputDir() {
@@ -60,10 +78,12 @@ class GenericPage {
         return this.#title;
     }
 
-    writeFile( html ) {
-        Files.write( this.#outputDir + "/" + this.#baseFileName + ".html", html );
+    /**
+     * @param {string} html
+     */
+    writeFile(html) {
+        Files.write(this.#outputDir + "/" + this.#baseFileName + ".html", html);
     }
-
 }
 
-export { GenericPage };
+export { GenericPage };

package/lib/html.js

@@ -1,11 +1,3 @@
-/**
- * @deprecated
- */
-export const HTML_OPTIONS = {
-    OPEN_NEW: 1,
-    NO_ESCAPE: 2,
-};
-
 /** HTML utility functions. */
 export class HTML {
     /**
@@ -35,19 +27,6 @@ export class HTML {
             .replaceAll(">", ">");
     }
 
-    /**
-     * @deprecated
-     */
-    static getElement(elName, text, attributes = {}, options = 0) {
-        let html = "<" + elName;
-        html += this.renderAttributes(attributes);
-        if (!(options & HTML_OPTIONS.NO_ESCAPE)) {
-            text = this.escapeText(text);
-        }
-        html += ">" + text + "</" + elName + ">";
-        return html;
-    }
-
     /**
      * @param {string} elName
      * @param {string} text
@@ -71,7 +50,7 @@ export class HTML {
      * Generate HTML for an &lt;a> element.
      * @param {string|undefined} href
      * @param {string} linkText
-     * @param {Object} [attributes]
+     * @param {string|Object<string,string>} [attributes]
      * @param {boolean} [openInNewWindow] true if the link should open in a new window.
      * @returns {string} an HTML &lt;a> element.
      */
@@ -92,7 +71,7 @@ export class HTML {
      * @param {string} text - The text or HTML that should trigger the tooltip on hover.
      * @param {string} tooltip - The tooltip text or HTML.
      * @param {Object} options
-     * @param {boolean} options.icon [true] display an icon after the text
+     * @param {boolean} [options.icon] [true] display an icon after the text
      * @returns {string} A &lt;span> element to be used as a Bootstrap tooltip.
      */
     static getToolTip(text, tooltip, options = {}) {
@@ -103,6 +82,10 @@ export class HTML {
         return func("span", text, { "data-bs-html": "true", title: tooltip });
     }
 
+    /**
+     * @param {string} n
+     * @param {string} v
+     */
     static renderAttribute(n, v) {
         return " " + n + '="' + this.escapeAttribute(v) + '"';
     }
@@ -121,6 +104,11 @@ export class HTML {
         return html;
     }
 
+    /**
+     * @param {string} elName
+     * @param {string} text
+     * @param {Object<string,string>} attributes
+     */
     static textElement(elName, text, attributes = {}) {
         return HTML.#getElement(elName, text, attributes, true);
     }

package/lib/htmltaxon.js

@@ -1,15 +1,83 @@
 import { DateUtils } from "./dateutils.js";
 import { HTML } from "./html.js";
-// eslint-disable-next-line no-unused-vars
-import { Taxon } from "./taxon.js";
+import { RarePlants } from "./rareplants.js";
 import { TextUtils } from "./textutils.js";
 
+/**
+ * @type {Object<string,{title:string,data:function (Taxon):string}>}
+ */
+const TAXA_LIST_COLS = {
+    CESA: {
+        title: "California",
+        data: (t) => RarePlants.getCESADescription(t.getCESA()),
+    },
+    COMMON_NAME: {
+        title: "Common Name",
+        data: (t) => t.getCommonNames().join(", "),
+    },
+    CNPS_RANK: {
+        title: "CNPS Rank",
+        data: (t) =>
+            HTML.getToolTip(
+                HTML.textElement("span", t.getRPIRankAndThreat()),
+                t.getRPIRankAndThreatTooltip()
+            ),
+    },
+    FESA: {
+        title: "Federal",
+        data: (t) => RarePlants.getFESADescription(t.getFESA()),
+    },
+    SPECIES: {
+        title: "Species",
+        data: (t) => t.getHTMLLink(true, true),
+    },
+    SPECIES_BARE: {
+        title: "Species",
+        data: (t) => t.getHTMLLink(true, false),
+    },
+};
+
+const DEFAULT_TAXA_COLUMNS = [
+    TAXA_LIST_COLS.SPECIES,
+    TAXA_LIST_COLS.COMMON_NAME,
+];
+
 class HTMLTaxon {
+    /**
+     * @param {string[]|undefined} colors
+     */
+    static getFlowerColors(colors, includeColorLink = true) {
+        let html = "";
+        if (colors) {
+            for (const color of colors) {
+                const img = HTML.textElement("img", "", {
+                    src: "./i/f-" + color + ".svg",
+                    alt: color + " flowers",
+                    title: color,
+                    class: "flr-color",
+                });
+                if (includeColorLink) {
+                    html += HTML.wrap("a", img, {
+                        href: "./list_fc_" + color + ".html",
+                    });
+                } else {
+                    html += img;
+                }
+            }
+        }
+        return html;
+    }
+
     /**
      * @param {Taxon} taxon
      * @param {string} classNames
+     * @param {boolean} [includeColorLink=true]
      */
-    static getFlowerInfo(taxon, classNames = "section") {
+    static getFlowerInfo(
+        taxon,
+        classNames = "section",
+        includeColorLink = true
+    ) {
         const lifeCycle = taxon.getLifeCycle();
         const colors = taxon.getFlowerColors();
         const monthStart = taxon.getBloomStart();
@@ -24,16 +92,7 @@ class HTMLTaxon {
 
         if (colors || monthStart) {
             let html = "Flowers: ";
-            if (colors) {
-                for (const color of colors) {
-                    html += HTML.textElement("img", "", {
-                        src: "./i/f-" + color + ".svg",
-                        alt: color + " flowers",
-                        title: color,
-                        class: "flr-color",
-                    });
-                }
-            }
+            html += this.getFlowerColors(colors, includeColorLink);
             if (monthStart && monthEnd) {
                 html += HTML.wrap(
                     "span",
@@ -47,6 +106,47 @@ class HTMLTaxon {
         }
         return HTML.wrap("div", parts.join(""), { class: classNames });
     }
+
+    /**
+     * @param {Taxon} taxon
+     */
+    static getLink(taxon) {
+        return (
+            HTML.getLink(taxon.getFileName(), taxon.getName()) +
+            this.getFlowerColors(taxon.getFlowerColors())
+        );
+    }
+
+    /**
+     * @param {Taxon[]} taxa
+     * @param {TaxaCol[]} [columns]
+     */
+    static getTaxaTable(taxa, columns = DEFAULT_TAXA_COLUMNS) {
+        let html = "<table><thead>";
+        for (const col of columns) {
+            const className = col.class;
+            const atts = className !== undefined ? className : {};
+            html += HTML.textElement("th", col.title, atts);
+        }
+        html += "</thead>";
+        html += "<tbody>";
+
+        for (const taxon of taxa) {
+            html += "<tr>";
+            for (const col of columns) {
+                const data = col.data(taxon);
+                const className = col.class;
+                const atts = className !== undefined ? className : {};
+                html += HTML.wrap("td", data, atts);
+            }
+            html += "</tr>";
+        }
+
+        html += "</tbody>";
+        html += "</table>";
+
+        return html;
+    }
 }
 
-export { HTMLTaxon };
+export { HTMLTaxon, TAXA_LIST_COLS };

package/lib/index.d.ts

@@ -0,0 +1,54 @@
+import { Command } from "commander";
+
+export class Config {
+    constructor(dataDir: string);
+    getConfigValue(
+        prefix: string,
+        name: string,
+        subcategory?: string,
+        defaultValue?: string
+    ): string;
+    getCountyCodes(): string[];
+    getLabel(name: string, dflt: string): string;
+}
+
+export class CSV {
+    static parseFile(dir: string, fileName: string);
+}
+
+export class ErrorLog {
+    constructor(fileName: string, echo?: boolean);
+    log(...msg: string[]);
+    write(): void;
+}
+
+export class Exceptions {
+    constructor(dataDir: string);
+    hasException(name: string, cat: string, subcat: string);
+}
+
+export class Files {
+    static exists(fileName: string): boolean;
+    static async fetch(url: string | URL, targetFileName: string | undefined);
+    static mkdir(dir: string);
+    static rmDir(dir: string);
+    static write(fileName: string, data: string, overwrite: boolean);
+}
+
+export class Program {
+    static getIncludeList(dataDir: string): string[];
+    static getProgram(): Command;
+}
+
+export class Taxa {
+    constructor(
+        inclusionList: Object<string, TaxonData> | true,
+        errorLog: ErrorLog,
+        showFlowerErrors: boolean,
+        taxonFactory?: (td: TaxonData, g: Genera) => Taxon,
+        extraTaxa?: TaxonData[],
+        extraSynonyms?: SynonymData[]
+    );
+    getTaxon(string): Taxon;
+    getTaxonList(): Taxon[];
+}