@legumeinfo/web-components
Version:
Web Components for the Legume Information System and other AgBio databases
262 lines • 11.3 kB
TypeScript
import { LitElement } from 'lit';
import { PaginatedSearchOptions } from './mixins';
import { LisCancelPromiseController } from './controllers';
/**
* The data used to construct the search form in the
* {@link LisTraitAssociationSearchElement | `LisTraitAssociationSearchElement`} template.
*/
export type TraitAssociationSearchFormData = {
genuses: {
genus: string;
species: {
species: string;
}[];
}[];
};
/**
* Optional parameters that may be given to a form data function. The
* {@link !AbortSignal | `AbortSignal`} instance will emit if a new function is provided
* before the current function completes. This signal should be used to cancel in-flight
* requests if the external API supports it.
*/
export type TraitAssociationSearchFormDataOptions = {
abortSignal?: AbortSignal;
};
/**
* The type signature of a function that may be used to load the data used to construct
* the search form in the {@link LisTraitAssociationSearchElement | `LisTraitAssociationSearchElement`}
* template.
*/
export type TraitAssociationFormDataFunction = (options: TraitAssociationSearchFormDataOptions) => Promise<TraitAssociationSearchFormData>;
/**
* The data that will be passed to the search function by the
* {@link LisTraitAssociationSearchElement | `LisTraitAssociationSearchElement`} class when a search
* is performed.
*/
export type TraitAssociationSearchData = {
page: number;
genus: string;
species: string;
type: string;
traits: string;
pubId: string;
author: string;
};
/**
* A single result of a trait association search performed by the
* {@link LisTraitAssociationSearchElement | `LisTraitAssociationSearchElement`} class.
* Contains the name of the trait and either a GWAS or QTL study object.
*
*/
export type TraitAssociationSearchResult = {
name: string;
type: string;
identifier: string;
synopsis: string;
description: string;
genotypes: string;
};
/**
* The signature of the function the
* {@link LisTraitAssociationSearchElement | `LisTraitAssociationSearchElement`} class requires for
* performing a trait association search.
*
* @param searchData An object containing a value of each field in the submitted form.
* @param options Optional parameters that aren't required to perform a trait association search
* but may be useful.
*
* @returns A {@link !Promise | `Promise`} that resolves to an
* {@link !Array | `Array`} of {@link TraitAssociationSearchResult | `TraitAssociationSearchResult`}
* objects.
*/
export type TraitAssociationSearchFunction = (searchData: TraitAssociationSearchData, options: PaginatedSearchOptions) => Promise<Array<TraitAssociationSearchResult>>;
declare const LisTraitAssociationSearchElement_base: import("./mixins").Constructor<import("./mixins").LisPaginatedSearchElementInterface<TraitAssociationSearchData, TraitAssociationSearchResult>, any[]> & typeof LitElement;
/**
* @htmlElement `<lis-trait-association-search-element>`
*
* A Web Component that provides a search form for searching for GWAS and QTL trait associations and
* displaying the results in a view table. Note that the component saves its state to the URL query
* string parameters and a search will be automatically performed if the parameters are present when
* the componnent is loaded. The component uses the
* {@link mixins!LisPaginatedSearchMixin | `LisPaginatedSearchMixin`} mixin. See the mixin docs for
* further details.
*
* @queryStringParameters
* - **genus:** The selected genus in the search for.
* - **species:** The selected species in the search for.
* - **type:** The selected type in the search form. Either 'GWAS' or 'QTL'.
* - **traits:** The traits provided in the search form.
* - **pubid** The publication ID provided in the search form. Either a PubMed ID or a DOI.
* - **author** The author provided in the search form.
* - **page:** What page of results is loaded. Starts at 1.
*
* @example
* {@link !HTMLElement | `HTMLElement`} properties can only be set via
* JavaScript. This means the {@link searchFunction | `searchFunction`} property
* must be set on a `<lis-trait-association-search-element>` tag's instance of the
* {@link LisTraitAssociationSearchElement | `LisTraitAssociationSearchElement`} class. For example:
* ```html
* <!-- add the Web Component to your HTML -->
* <lis-trait-association-search-element id="trait-association-search"></lis-trait-association-search-element>
*
* <!-- configure the Web Component via JavaScript -->
* <script type="text/javascript">
* // a site-specific function that sends a request to a trait association search API
* function getTraits(searchData, {abortSignal}) {
* // returns a Promise that resolves to a search result object
* }
* // get the trait association search element
* const searchElement = document.getElementById('trait-association-search');
* // set the element's searchFunction property
* searchElement.searchFunction = getTraits;
* </script>
* ```
*
* @example
* Data must be provided for the genus and species selectors in the search form.
* This can be done by setting the form's {@link formData | `formData`} attribute/property directly
* or by setting the {@link formDataFunction | `formDataFunction`} property. Setting the latter will
* call the function immediately and set the {@link formData | `formData`} value using the result.
* For example:
* ```html
* <!-- add the Web Component to your HTML -->
* <lis-trait-association-search-element id="trait-association-search"></lis-trait-association-search-element>
*
* <!-- configure the Web Component via JavaScript -->
* <script type="text/javascript">
* // a site-specific function that gets genus and species data from an API
* function getFormData() {
* // returns a Promise that resolves to a form data object
* }
* // get the trait association search element
* const searchElement = document.getElementById('trait-association-search');
* // set the element's formDataFunction property
* searchElement.formDataFunction = getGeneFormData;
* </script>
* ```
*
* @example
* The {@link genus | `genus`} and {@link species | `species`} properties can be used to limit all
* searches to a specific genus and species. This will cause the genus and species fields of the
* search form to be automatically set and disabled so that users cannot change them. Additionally,
* these properties cannot be overridden using the `genus` and `species` querystring parameters.
* However, like the `genus` and `species` querystring parameters, if the genus/species set are not
* present in the `formData` then the genus/species form fields will be set to the default `any`
* value. Note that setting the `species` value has no effect if the `genus` value is not also set.
* For example:
* ```html
* <!-- restrict the genus via HTML -->
* <lis-trait-association-search-element genus="Glycine"></lis-trait-association-search-element>
*
* <!-- restrict the genus and species via HTML -->
* <lis-trait-association-search-element genus="Glycine" species="max"></lis-trait-association-search-element>
*
* <!-- restrict the genus and species via JavaScript -->
* <lis-trait-association-search-element id="trait-association-search"></lis-trait-association-search-element>
*
* <script type="text/javascript">
* // get the trait association search element
* const searchElement = document.getElementById('trait-association-search');
* // set the element's genus and species properties
* searchElement.genus = "Cicer";
* searchElement.species = "arietinum";
* </script>
* ```
*
* @example
* The {@link traitsExample | `traitsExample`}, {@link publicationExample | `publicationExample`}, and
* {@link authorExample | `authorExample`} properties can be used to set the example text for the
* Traits, Publication ID, and Author input fields, respectively. For example:
* ```html
* <!-- set the example text via HTML -->
* <lis-trait-association-search-element traitsExample="R8 full maturity" publicationExample="10.2135/cropsci2005.05-0168" authorExample="Specht"></lis-trait-association-search-element>
*
* <!-- set the example text via JavaScript -->
* <lis-trait-association-search-element id="trait-association-search"></lis-trait-association-search-element>
*
* <script type="text/javascript">
* // get the trait association search element
* const searchElement = document.getElementById('trait-association-search');
* // set the element's example text properties
* searchElement.traitsExample = 'R8 full maturity';
* searchElement.publicationExample = '10.2135/cropsci2005.05-0168';
* searchElement.authorExample = 'Specht';
* </script>
* ```
*/
export declare class LisTraitAssociationSearchElement extends LisTraitAssociationSearchElement_base {
/** @ignore */
static styles: import("lit").CSSResult;
/**
* The data used to construct the search form in the template.
*
* @attribute
*/
formData: TraitAssociationSearchFormData;
/**
* An optional property that can be used to load the form data via an external function.
* If used, the `formData` attribute/property will be updated using the result.
*/
formDataFunction: TraitAssociationFormDataFunction;
/**
* An optional property that limits searches to a specific genus. Setting the property to the
* empty string "" will cause the genus form field to be set to the default "any" value.
*
* @attribute
*/
genus?: string;
/**
* An optional property that limits searches to a specific species. Setting the property to the
* empty string "" will cause the species form field to be set to the default "any" value. Doesn't
* work without the `genus` property.
*
* @attribute
*/
species?: string;
/**
* An optional property to set the example text for the Traits input field.
*
* @attribute
*/
traitsExample?: string;
/**
* An optional property to set the example text for the Publication ID input field.
*
* @attribute
*/
publicationExample?: string;
/**
* An optional property to set the example text for the author input field.
*
* @attribute
*/
authorExample?: string;
private selectedGenus;
private selectedSpecies;
private _studyTypes;
private selectedType;
protected formDataCancelPromiseController: LisCancelPromiseController;
private _formLoadingRef;
constructor();
private _getDefaultGenus;
private _getDefaultSpecies;
connectedCallback(): void;
updated(changedProperties: Map<string, unknown>): void;
private _getFormData;
private _initializeSelections;
private _selectGenus;
private _renderGenusSelector;
private _selectSpecies;
private _renderSpeciesSelector;
private _selectType;
private _renderTypeSelector;
/** @ignore */
renderForm(): import("lit-html").TemplateResult<1>;
}
declare global {
interface HTMLElementTagNameMap {
'lis-trait-association-search-element': LisTraitAssociationSearchElement;
}
}
export {};
//# sourceMappingURL=lis-trait-association-search-element.d.ts.map