@imerss/inat-components 2.0.1 → 3.0.0

package/README.md

@@ -1,12 +1,31 @@
 # @imerss/inat-components
 
 The [inat-components repo](https://github.com/IMERSS/inat-components) contains some pre-built React components to
-display iNaturalist data on your own sites. The original goal was to provide add an 
+display iNaturalist data on your own sites. The original goal was to add an 
 [interactive page to the BC Lepidoptera website](https://bcleps.weebly.com/inat.html) so visitors could see some
 high-level information about lepidoptera (butterflies and moths) spotted in British Columbia. But the code
 was written to allow it to be re-used by any website and for any taxon or place.
 
-This specific package is only the React components, plus a standalone.min.js file for 
+This package holds the React components, with their typings, and `dist/standalone.min.js`, a single script holding
+the components and React together, for sites which don't use React.
 
-Please see the [main documentation](https://github.com/IMERSS/inat-components) for more information on the script, 
-including the standalone version.
+```
+npm install @imerss/inat-components
+```
+
+```jsx
+import TaxonPanel from "@imerss/inat-components";
+
+<TaxonPanel
+    taxon={{ id: 47157, str: "leps" }}
+    place={{ id: 7085, str: "bc" }}
+    dataSource="url"
+    dataSourceBaseUrl="https://example.org/inat"
+    features={[{ feature: "recentObservations" }, { feature: "commonTaxa" }, { feature: "favourites" }, { feature: "stats" }]}
+/>
+```
+
+See the [main documentation](https://github.com/IMERSS/inat-components) for every setting, the individual components,
+the data files which [@imerss/inat-components-utils](https://www.npmjs.com/package/@imerss/inat-components-utils)
+writes for the `"url"` data source, and the
+[standalone version](https://github.com/IMERSS/inat-components/tree/main/packages/inat-components-standalone).

package/dist/index.d.ts

@@ -1,50 +1,58 @@
-declare type CommonTaxaCallProps = {
+import React from 'react';
+
+type ObservationFilter = {
+    taxonId?: string | number;
+    placeId?: string | number;
+    projectId?: string | number;
+};
+/**
+ * Render a filter as query parameters, to be appended to a URL which already has a query.
+ * @param filter - The taxon, place and project of the observations
+ * @return The parameters, each beginning with "&", of those members of the filter which are supplied
+ */
+declare const filterParams: (filter: ObservationFilter) => string;
+
+type CommonTaxaCallProps = ObservationFilter & {
     year: string | number;
-    taxonId: string | number;
-    placeId: string | number;
     numResults: number;
 };
-declare type CommonTaxData = {
+type CommonTaxData = {
     id: number;
     imageUrl: string;
     taxonName: string;
     taxonCommonName: string;
     obsCount: number;
 };
-declare type CommonTaxaRespData = {
+type CommonTaxaRespData = {
     totalResults: number;
     results: [CommonTaxData];
 };
-declare const getCommonTaxa: ({ year, taxonId, placeId, numResults }: CommonTaxaCallProps) => Promise<CommonTaxaRespData>;
+declare const getCommonTaxa: ({ year, taxonId, placeId, projectId, numResults }: CommonTaxaCallProps) => Promise<CommonTaxaRespData>;
 
-declare type FavouritesCallProps = {
+type FavouritesCallProps = ObservationFilter & {
     year: string | number;
-    taxonId: string | number;
-    placeId: string | number;
     numResults: number;
 };
-declare type FavouritesData = {
+type FavouritesData = {
     id: number;
     imageUrl: string;
     taxonName: string;
     taxonCommonName: string;
     obsDate: string;
-    obsCount: number;
+    obsUrl: string;
     observerUsername: string;
     numFaves: number;
 };
-declare type FavouritesRespData = {
+type FavouritesRespData = {
     totalResults: number;
     results: [FavouritesData];
 };
-declare const getFavourites: ({ year, taxonId, placeId, numResults }: FavouritesCallProps) => Promise<FavouritesRespData>;
+declare const getFavourites: ({ year, taxonId, placeId, projectId, numResults }: FavouritesCallProps) => Promise<FavouritesRespData>;
 
-declare type RecentObservationsCallProps = {
-    taxonId: string | number;
-    placeId: string | number;
+type RecentObservationsCallProps = ObservationFilter & {
     numResults: number;
 };
-declare type RecentObservationData = {
+type RecentObservationData = {
     id: number;
     imageUrl: string;
     obsUrl: string;
@@ -53,38 +61,37 @@ declare type RecentObservationData = {
     taxonCommonName: string;
     observerUsername: string;
 };
-declare type RecentObservationsRespData = {
+type RecentObservationsRespData = {
     totalResults: number;
     results: [RecentObservationData];
 };
-declare const getRecentObservations: ({ taxonId, placeId, numResults }: RecentObservationsCallProps) => Promise<RecentObservationsRespData>;
+declare const getRecentObservations: ({ taxonId, placeId, projectId, numResults }: RecentObservationsCallProps) => Promise<RecentObservationsRespData>;
 
-declare type SummaryApiProps = {
-    taxonId: number;
-    placeId: number;
+type SummaryApiProps = ObservationFilter & {
     year: string | number;
+    numTopObservers?: number;
 };
-declare const getSummary: ({ taxonId, placeId, year }: SummaryApiProps) => Promise<any>;
-declare type Observer = {
+declare const getSummary: ({ taxonId, placeId, projectId, year, numTopObservers }: SummaryApiProps) => Promise<any>;
+type Observer = {
     id: number;
     userName: string;
     numObservations: number;
     iconUrl: string | null;
 };
-declare type SummaryData = {
+type SummaryData = {
     totalCount: number;
     top: [Observer];
 };
-declare const getObserverSummary: (taxonId: number, placeId: number, year: string | number) => Promise<SummaryData>;
-declare const getObservationSummary: (taxonId: number, placeId: number, year: string | number) => Promise<{
+declare const getObserverSummary: (filter: ObservationFilter, year: string | number, numTopObservers?: number) => Promise<SummaryData>;
+declare const getObservationSummary: (filter: ObservationFilter, year: string | number) => Promise<{
     totalCount: any;
 }>;
-declare type SeasonalityData = {
+type SeasonalityData = {
     monthOfYear: {
         [monthNum: string]: number;
     };
 };
-declare const getSeasonalityData: (taxonId: number, placeId: number, year: string | number) => Promise<SeasonalityData>;
+declare const getSeasonalityData: (filter: ObservationFilter, year: string | number) => Promise<SeasonalityData>;
 
 declare enum Feature {
     commonTaxa = "commonTaxa",
@@ -96,12 +103,12 @@ declare enum DataSourceEnum {
     autoLoad = "autoLoad",
     url = "url"
 }
-declare type DataSource = `${DataSourceEnum}`;
-declare type ItemConfig = {
-    id: number;
+type DataSource = `${DataSourceEnum}`;
+type ItemConfig = {
+    id: number | string;
     str: string;
 };
-declare type GeneralClasses = {
+type GeneralClasses = {
     tabsElement?: string;
     yearsDropdown?: string;
     pageHeadings?: string;
@@ -111,9 +118,10 @@ declare type GeneralClasses = {
     observationLabelName?: string;
     observationCount?: string;
 };
-declare type BaseComponentProps = {
-    taxonId?: number;
-    placeId?: number;
+type BaseComponentProps = {
+    taxonId?: number | string;
+    placeId?: number | string;
+    projectId?: number | string;
     numResults?: number;
     source?: DataSource;
     dataUrl?: string;
@@ -127,14 +135,14 @@ declare type BaseComponentProps = {
     generalClasses?: GeneralClasses;
     tabDesc?: string;
 };
-declare type RecentObservationsConfig = {
+type RecentObservationsConfig = {
     feature: Feature.recentObservations;
     title?: string;
     numResults?: number;
     desc?: string;
     className?: string;
 };
-declare type CommonTaxaConfig = {
+type CommonTaxaConfig = {
     feature: Feature.commonTaxa;
     title?: string;
     numResults?: number;
@@ -142,7 +150,7 @@ declare type CommonTaxaConfig = {
     desc?: string;
     className?: string;
 };
-declare type FavouritesConfig = {
+type FavouritesConfig = {
     feature: Feature.favourites;
     title?: string;
     numResults?: number;
@@ -150,7 +158,7 @@ declare type FavouritesConfig = {
     desc?: string;
     className?: string;
 };
-declare type StatsConfig = {
+type StatsConfig = {
     feature: Feature.stats;
     title?: string;
     numTopObservers?: number;
@@ -160,9 +168,9 @@ declare type StatsConfig = {
     observersListClass?: string;
     statsCountSummaryClass?: string;
 };
-declare type TaxonPanelFeatures = (RecentObservationsConfig | CommonTaxaConfig | FavouritesConfig | StatsConfig)[];
+type TaxonPanelFeatures = (RecentObservationsConfig | CommonTaxaConfig | FavouritesConfig | StatsConfig)[];
 
-declare const getSourceFile: (api: Feature, taxon: ItemConfig, place: ItemConfig, year?: string | number) => string;
+declare const getSourceFile: (api: Feature, taxon: ItemConfig | undefined, place: ItemConfig | undefined, year?: string | number, project?: ItemConfig) => string;
 
 declare const getCurrentYear: () => number;
 declare const formatDate: (date: string, dateFormat?: string) => any;
@@ -173,78 +181,80 @@ declare const BASE_API_URL = "https://api.inaturalist.org";
 declare const NUM_RESULTS = 100;
 declare const DEFAULT_NUM_YEARS = 10;
 declare const BASE_URL = "https://www.inaturalist.org";
-declare const ERROR_LOG_FILENAME = "inat-components-error.log";
 declare const DEFAULT_ITEM_WIDTH = 150;
+declare const DEFAULT_NUM_TOP_OBSERVERS = 10;
 
 declare const constants_BASE_API_URL: typeof BASE_API_URL;
 declare const constants_NUM_RESULTS: typeof NUM_RESULTS;
 declare const constants_DEFAULT_NUM_YEARS: typeof DEFAULT_NUM_YEARS;
 declare const constants_BASE_URL: typeof BASE_URL;
-declare const constants_ERROR_LOG_FILENAME: typeof ERROR_LOG_FILENAME;
 declare const constants_DEFAULT_ITEM_WIDTH: typeof DEFAULT_ITEM_WIDTH;
+declare const constants_DEFAULT_NUM_TOP_OBSERVERS: typeof DEFAULT_NUM_TOP_OBSERVERS;
 declare namespace constants {
   export {
     constants_BASE_API_URL as BASE_API_URL,
     constants_NUM_RESULTS as NUM_RESULTS,
     constants_DEFAULT_NUM_YEARS as DEFAULT_NUM_YEARS,
     constants_BASE_URL as BASE_URL,
-    constants_ERROR_LOG_FILENAME as ERROR_LOG_FILENAME,
     constants_DEFAULT_ITEM_WIDTH as DEFAULT_ITEM_WIDTH,
+    constants_DEFAULT_NUM_TOP_OBSERVERS as DEFAULT_NUM_TOP_OBSERVERS,
   };
 }
 
-declare type TaxonPanelProps = {
-    taxon: {
-        id: number;
-        str: string;
-    };
-    place: {
-        id: number;
-        str: string;
-    };
-    dataSourceBaseUrl: string;
+type TaxonPanelProps = {
+    taxon?: ItemConfig;
+    place?: ItemConfig;
+    project?: ItemConfig;
+    dataSourceBaseUrl?: string;
     dataSource: DataSource;
     features: TaxonPanelFeatures;
-    generalClasses: GeneralClasses;
+    generalClasses?: GeneralClasses;
     itemWidth?: number;
 };
-declare const TaxonPanel: ({ taxon, place, features, dataSource, dataSourceBaseUrl, itemWidth, generalClasses }: TaxonPanelProps) => JSX.Element;
+declare const TaxonPanel: ({ taxon, place, project, features, dataSource, dataSourceBaseUrl, itemWidth, generalClasses }: TaxonPanelProps) => React.JSX.Element;
 
-declare type ObservationProps = {
+/**
+ * The columns of a grid of observations. Each is at least `itemWidth` wide, but no wider than allows two across a narrow
+ * screen, and a row of fewer results than fill it leaves the rest empty, rather than stretching them across it.
+ * @param itemWidth - The least width of a column, in pixels
+ * @return The value of the grid's `grid-template-columns`
+ */
+declare const gridColumns: (itemWidth: number) => string;
+type ObservationProps = {
     imageUrl: string;
     linkUrl: string;
-    itemWidth: number;
     children: any;
 };
-declare const Observation: ({ imageUrl, linkUrl, itemWidth, children }: ObservationProps) => JSX.Element;
+declare const Observation: ({ imageUrl, linkUrl, children }: ObservationProps) => React.JSX.Element;
 
-declare type CommonTaxaProps = BaseComponentProps & {
+type CommonTaxaProps = BaseComponentProps & {
     year: number;
 };
 declare const CommonTaxaLabel: (data: CommonTaxData & {
     classes: GeneralClasses;
-}) => JSX.Element;
-declare const CommonTaxa: ({ year, source, taxonId, placeId, numResults, itemWidth, dataUrl, components, generalClasses, className, tabDesc }: CommonTaxaProps) => JSX.Element;
+}) => React.JSX.Element;
+declare const CommonTaxa: ({ year, source, taxonId, placeId, projectId, numResults, itemWidth, dataUrl, components, generalClasses, className, tabDesc }: CommonTaxaProps) => React.JSX.Element;
 
-declare type RecentObservationsProps = BaseComponentProps;
+type RecentObservationsProps = BaseComponentProps;
 declare const RecentObservationLabel: (obs: RecentObservationData & {
     classes: GeneralClasses;
-}) => JSX.Element;
-declare const RecentObservations: ({ taxonId, placeId, dataUrl, components, className, generalClasses, tabDesc, source, numResults, itemWidth }: RecentObservationsProps) => JSX.Element;
+}) => React.JSX.Element;
+declare const RecentObservations: ({ taxonId, placeId, projectId, dataUrl, components, className, generalClasses, tabDesc, source, numResults, itemWidth }: RecentObservationsProps) => React.JSX.Element;
 
-declare type FavouritesProps = BaseComponentProps & {
+type FavouritesProps = BaseComponentProps & {
     year: number | string;
 };
 declare const FavouritesLabel: (data: FavouritesData & {
     classes: GeneralClasses;
-}) => JSX.Element;
-declare const Favourites: ({ year, source, taxonId, placeId, dataUrl, components, className, tabDesc, generalClasses, itemWidth, numResults }: FavouritesProps) => JSX.Element;
+}) => React.JSX.Element;
+declare const Favourites: ({ year, source, taxonId, placeId, projectId, dataUrl, components, className, tabDesc, generalClasses, itemWidth, numResults }: FavouritesProps) => React.JSX.Element;
 
-declare const SeasonalityGraph: ({ data }: any) => JSX.Element;
+declare const SeasonalityGraph: ({ data }: any) => React.JSX.Element;
 
-declare type SummaryProps = {
-    taxonId: number;
-    placeId: number;
+type SummaryProps = {
+    taxonId?: number | string;
+    placeId?: number | string;
+    projectId?: number | string;
     year: number;
     source: DataSource;
     dataUrl?: string;
@@ -253,7 +263,9 @@ declare type SummaryProps = {
     tabDesc?: string;
     observersListClass?: string;
     statsCountSummaryClass?: string;
+    numTopObservers?: number;
+    components?: BaseComponentProps["components"];
 };
-declare const Summary: ({ source, dataUrl, taxonId, placeId, year, generalClasses, className, tabDesc, observersListClass, statsCountSummaryClass }: SummaryProps) => JSX.Element;
+declare const Summary: ({ source, dataUrl, taxonId, placeId, projectId, year, generalClasses, className, tabDesc, observersListClass, statsCountSummaryClass, numTopObservers, components }: SummaryProps) => React.JSX.Element;
 
-export { BaseComponentProps, constants as C, CommonTaxData, CommonTaxa, CommonTaxaCallProps, CommonTaxaConfig, CommonTaxaLabel, CommonTaxaProps, CommonTaxaRespData, DataSource, DataSourceEnum, Favourites, FavouritesCallProps, FavouritesConfig, FavouritesData, FavouritesLabel, FavouritesProps, FavouritesRespData, Feature, GeneralClasses, ItemConfig, Observation, ObservationProps, Observer, RecentObservationData, RecentObservationLabel, RecentObservations, RecentObservationsCallProps, RecentObservationsConfig, RecentObservationsProps, RecentObservationsRespData, SeasonalityData, SeasonalityGraph, StatsConfig, Summary, SummaryApiProps, SummaryData, SummaryProps, TaxonPanelFeatures, TaxonPanelProps, TaxonPanel as default, formatDate, getCommonTaxa, getCurrentYear, getFavourites, getObservationSummary, getObserverSummary, getRecentObservations, getSeasonalityData, getSourceFile, getSummary, numberWithCommas };
+export { BaseComponentProps, constants as C, CommonTaxData, CommonTaxa, CommonTaxaCallProps, CommonTaxaConfig, CommonTaxaLabel, CommonTaxaProps, CommonTaxaRespData, DataSource, DataSourceEnum, Favourites, FavouritesCallProps, FavouritesConfig, FavouritesData, FavouritesLabel, FavouritesProps, FavouritesRespData, Feature, GeneralClasses, ItemConfig, Observation, ObservationFilter, ObservationProps, Observer, RecentObservationData, RecentObservationLabel, RecentObservations, RecentObservationsCallProps, RecentObservationsConfig, RecentObservationsProps, RecentObservationsRespData, SeasonalityData, SeasonalityGraph, StatsConfig, Summary, SummaryApiProps, SummaryData, SummaryProps, TaxonPanelFeatures, TaxonPanelProps, TaxonPanel as default, filterParams, formatDate, getCommonTaxa, getCurrentYear, getFavourites, getObservationSummary, getObserverSummary, getRecentObservations, getSeasonalityData, getSourceFile, getSummary, gridColumns, numberWithCommas };