@legumeinfo/web-components
Version:
Web Components for the Legume Information System and other AgBio databases
266 lines • 10.6 kB
TypeScript
import { LitElement } from 'lit';
import { LisCancelPromiseController } from './controllers';
import { PaginatedSearchOptions } from './mixins';
/**
* The data used to construct the search form in the
* {@link LisGeneSearchElement | `LisGeneSearchElement`} template.
*/
export type GeneSearchFormData = {
genuses: {
genus: string;
species: {
species: string;
strains: {
strain: 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 GeneFormDataOptions = {
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 LisGeneSearchElement | `LisGeneSearchElement`} template.
*/
export type GeneFormDataFunction = (options: GeneFormDataOptions) => Promise<GeneSearchFormData>;
/**
* The data that will be passed to the search function by the
* {@link LisGeneSearchElement | `LisGeneSearchElement`} class when a search is
* performed.
*/
export type GeneSearchData = {
page: number;
genus: string;
species: string;
strain: string;
name: string;
identifier: string;
description: string;
};
/**
* A single result of a gene search performed by the
* {@link LisGeneSearchElement | `LisGeneSearchElement`} class.
*/
export type GeneSearchResult = {
name: string;
identifier: string;
description: string;
genus: string;
species: string;
strain: string;
geneFamilyAssignments: string[];
panGeneSets: string[];
locations: string[];
};
/**
* The signature of the function the
* {@link LisGeneSearchElement | `LisGeneSearchElement`} class requires for
* performing a gene search.
*
* @param searchData An object containing a value of each field in the submitted form.
* new search is performed.
* @param options Optional parameters that aren't required to perform a gene
* search but may be useful.
*
* @returns A {@link !Promise | `Promise`} that resolves to an
* {@link !Array | `Array`} of {@link GeneSearchResult | `GeneSearchResult`}
* objects.
*/
export type GeneSearchFunction = (searchData: GeneSearchData, options: PaginatedSearchOptions) => Promise<Array<GeneSearchResult>>;
declare const LisGeneSearchElement_base: import("./mixins").Constructor<import("./mixins").LisPaginatedSearchElementInterface<GeneSearchData, GeneSearchResult>, any[]> & typeof LitElement;
/**
* @htmlElement `<lis-gene-search-element>`
*
* A Web Component that provides an interface for performing searches for genes and
* displaying 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 form.
* - **species:** The selected species in the search form.
* - **strain:** The selected strain in the search form.
* - **identifier:** The identifier provided in the search form.
* - **description:** The description provided in the search form.
* - **family:** The gene family identifier provided in the search form.
* - **page:** What page of results to load.
*
* @example
* {@link !HTMLElement | `HTMLElement`} properties can only be set via
* JavaScript. This means the {@link searchFunction | `searchFunction`} property
* must be set on a `<lis-gene-search-element>` tag's instance of the
* {@link LisGeneSearchElement | `LisGeneSearchElement`} class. For example:
* ```html
* <!-- add the Web Component to your HTML -->
* <lis-gene-search-element id="gene-search"></lis-gene-search-element>
*
* <!-- configure the Web Component via JavaScript -->
* <script type="text/javascript">
* // a site-specific function that sends a request to a gene search API
* function getGenes(searchData, {abortSignal}) {
* // returns a Promise that resolves to a search result object
* }
* // get the gene search element
* const searchElement = document.getElementById('gene-search');
* // set the element's searchFunction property
* searchElement.searchFunction = getGenes;
* </script>
* ```
*
* @example
* Data must be provided for the genus, species, and strain 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-gene-search-element id="gene-search"></lis-gene-search-element>
*
* <!-- configure the Web Component via JavaScript -->
* <script type="text/javascript">
* // a site-specific function that gets genus, species, and strain data from an API
* function getFormData() {
* // returns a Promise that resolves to a form data object
* }
* // get the gene search element
* const searchElement = document.getElementById('gene-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 field 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 field 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-gene-search-element genus="Glycine"></lis-gene-search-element>
*
* <!-- restrict the genus and species via HTML -->
* <lis-gene-search-element genus="Glycine" species="max"></lis-gene-search-element>
*
* <!-- restrict the genus and species via JavaScript -->
* <lis-gene-search-element id="gene-search"></lis-gene-search-element>
*
* <script type="text/javascript">
* // get the gene search element
* const searchElement = document.getElementById('gene-search');
* // set the element's genus and species properties
* searchElement.genus = "Cicer";
* searchElement.species = "arietinum";
* </script>
* ```
*
* @example
* The {@link identifierExample | `identifierExample`}, {@link descriptionExample | `descriptionExample`},
* and {@link familyExample | `familyExample`} properties can be used to set the example text for the
* identifier, description, and gene family input fields, respectively. For example:
* ```html
* <!-- set the example text via HTML -->
* <lis-gene-search-element identifierExample="Glyma.13G357700" descriptionExample="protein disulfide isomerase-like protein" familyExample="L_HZ6G4Z"></lis-gene-search-element>
*
* <!-- set the example text via JavaScript -->
* <lis-gene-search-element id="gene-search"></lis-gene-search-element>
*
* <script type="text/javascript">
* // get the gene search element
* const searchElement = document.getElementById('gene-search');
* // set the element's example text properties
* searchElement.identifierExample = 'Glyma.13G357700';
* searchElement.descriptionExample = 'protein disulfide isomerase-like protein';
* searchElement.familyExample = 'L_HZ6G4Z';
* </script>
* ```
*/
export declare class LisGeneSearchElement extends LisGeneSearchElement_base {
/** @ignore */
static styles: import("lit").CSSResult;
/**
* The data used to construct the search form in the template.
*
* @attribute
*/
formData: GeneSearchFormData;
/**
* 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: GeneFormDataFunction;
/**
* 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 Identifier input field.
*
* @attribute
*/
identifierExample?: string;
/**
* An optional property to set the example text for the Description input field.
*
* @attribute
*/
descriptionExample?: string;
/**
* An optional property to set the example text for the Gene Family input field.
*
* @attribute
*/
familyExample?: string;
private selectedGenus;
private selectedSpecies;
private selectedStrain;
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 _selectStrain;
private _renderStrainSelector;
/** @ignore */
renderForm(): import("lit-html").TemplateResult<1>;
}
declare global {
interface HTMLElementTagNameMap {
'lis-gene-search-element': LisGeneSearchElement;
}
}
export {};
//# sourceMappingURL=lis-gene-search-element.d.ts.map