@legumeinfo/web-components
Version:
Web Components for the Legume Information System and other AgBio databases
282 lines • 11.1 kB
TypeScript
import { LitElement, PropertyValues } from 'lit';
import { LisCancelPromiseController } from './controllers';
import { DownloadFunction, PaginatedSearchData, PaginatedSearchOptions } from './mixins';
/**
* The data used to construct the lookup form in the
* {@link LisPangeneLookupElement | `LisPangeneLookupElement`} template.
*/
export type PangeneLookupFormData = {
genuses: {
genus: string;
species: {
species: string;
strains: {
strain: string;
assemblies: {
assembly: string;
annotations: {
annotation: 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 PangeneFormDataOptions = {
abortSignal?: AbortSignal;
};
/**
* The type signature of a function that may be used to load the data used to construct
* the lookup form in the {@link LisPangeneLookupElement | `LisPangeneLookupElement`} template.
*/
export type PangeneFormDataFunction = (options: PangeneFormDataOptions) => Promise<PangeneLookupFormData>;
/**
* The data that will be passed to the lookup function by the
* {@link LisPangeneLookupElement | `LisPangeneLookupElement`} class when a lookup is
* performed.
*/
export type PangeneLookupData = {
genus: string;
species: string;
strain: string;
assembly: string;
annotation: string;
genes: string[];
} & PaginatedSearchData;
/**
* A single result of a pangene lookup performed by the
* {@link LisPangeneLookupElement | `LisPangeneLookupElement`} class.
*/
export type PangeneLookupResult = {
input: string;
panGeneSet: string;
target: string;
};
/**
* The signature of the function the
* {@link LisPangeneLookupElement | `LisPangeneLookupElement`} class requires for
* performing a pangene lookup.
*
* @param lookupData An object containing a value of each field in the submitted form.
* @param page What page of results the lookup is for. Will always be 1 when a
* new lookup is performed.
* @param options Optional parameters that aren't required to perform a pangene
* lookup but may be useful.
*
* @returns A {@link !Promise | `Promise`} that resolves to an
* {@link !Array | `Array`} of {@link PangeneLookupResult | `PangeneLookupResult`}
* objects.
*/
export type PangeneSearchFunction = (searchData: PangeneLookupData, options: PaginatedSearchOptions) => Promise<Array<PangeneLookupResult>>;
export type PangeneDownloadFunction = DownloadFunction<PangeneLookupData>;
declare const LisPangeneLookupElement_base: import("./mixins").Constructor<import("./mixins").LisPaginatedSearchElementInterface<PangeneLookupData, PangeneLookupResult>, any[]> & typeof LitElement;
/**
* @htmlElement `<lis-pangene-lookup-element>`
*
* A Web Component that provides an interface for looking up pangenes and
* displaying results in a view table. The component uses the
* {@link mixins!LisPaginatedSearchMixin | `LisPaginatedSearchMixin`} mixin. See the
* mixin docs for further details.
*
* @example
* {@link !HTMLElement | `HTMLElement`} properties can only be set via
* JavaScript. This means the {@link searchFunction | `searchFunction`} property
* must be set on a `<lis-pangene-lookup-element>` tag's instance of the
* {@link LisPangeneLookupElement | `LisPangeneLookupElement`} class. For example:
* ```html
* <!-- add the Web Component to your HTML -->
* <lis-pangene-lookup-element id="pangene-lookup"></lis-pangene-lookup-element>
*
* <!-- configure the Web Component via JavaScript -->
* <script type="text/javascript">
* // a site-specific function that sends a request to a pangene lookup API
* function getPangenes(lookupData, page, {abortSignal}) {
* // returns a Promise that resolves to a lookup result object
* }
* // get the pangene lookup element
* const lookupElement = document.getElementById('pangene-lookup');
* // set the element's searchFunction property
* lookupElement.searchFunction = getPangenes;
* </script>
* ```
*
* @example
* Data must be provided for the genus, species, strain, assembly, and annotation selectors in the
* lookup 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-pangene-lookup-element id="pangene-lookup"></lis-pangene-lookup-element>
*
* <!-- configure the Web Component via JavaScript -->
* <script type="text/javascript">
* // a site-specific function that gets genus, species, strain, assembly, and annotation data from an API
* function getPangeneFormData() {
* // returns a Promise that resolves to a form data object
* }
* // get the pangene looktup element
* const lookupElement = document.getElementById('pangene-lookup');
* // set the element's formDataFunction property
* lookupElement.formDataFunction = getPangeneFormData;
* </script>
* ```
*
* @example
* The {@link genus | `genus`}, {@link species | `species`}, {@link strain | `strain`},
* {@link assembly | `assembly`}, and {@link annotation | `annotation`} properties can be used to
* limit all lookups to a specific genus, species, strain, assembly, and annotation. This will cause
* the genus, species, strain, assembly, and annotation fields of the lookup form to be
* automatically set and disabled so that users cannot change them.
* For example:
* ```html
* <!-- restrict the genus via HTML -->
* <lis-pangene-lookup-element genus="Glycine"></lis-pangene-lookup-element>
*
* <!-- restrict the genus and species via HTML -->
* <lis-pangene-lookup-element genus="Glycine" species="max"></lis-pangene-lookup-element>
*
* <!-- restrict the genus and species via JavaScript -->
* <lis-pangene-lookup-element id="pangene-lookup"></lis-pangene-lookup-element>
*
* <script type="text/javascript">
* // get the pangene lookup element
* const lookupElement = document.getElementById('pangene-lookup');
* // set the element's genus and species properties
* lookupElement.genus = "Cicer";
* lookupElement.species = "arietinum";
* </script>
* ```
*
* @example
* The {@link genesExample | `genesExample`} property can be used to set the example text for the
* gene identifiers input field. For example:
* ```html
* <!-- set the example text via HTML -->
* <lis-pangene-lookup-element genesExample="Glyma.13G357700 Glyma.13G357702"></lis-pangene-lookup-element>
*
* <!-- set the example text via JavaScript -->
* <lis-pangene-lookup-element id="pangene-lookup"></lis-pangene-lookup-element>
*
* <script type="text/javascript">
* // get the pangene lookup element
* const lookupElement = document.getElementById('pangene-lookup');
* // set the element's example text properties
* lookupElement.genesExample = 'Glyma.13G357700 Glyma.13G357702';
* </script>
* ```
*/
export declare class LisPangeneLookupElement extends LisPangeneLookupElement_base {
/** @ignore */
static styles: import("lit").CSSResult;
/**
* The data used to construct the lookup form in the template.
*
* @attribute
*/
formData: PangeneLookupFormData;
/**
* 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: PangeneFormDataFunction;
/**
* An optional property that limits lookups 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 lookups 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 that limits lookups to a specific strain. Setting the property to the
* empty string "" will cause the strain form field to be set to the default "any" value. Doesn't
* work without the `species` property.
*
* @attribute
*/
strain?: string;
/**
* An optional property that limits lookups to a specific assembly. Setting the property to the
* empty string "" will cause the assembly form field to be set to the default "any" value.
* Doesn't work without the `strain` property.
*
* @attribute
*/
assembly?: string;
/**
* An optional property that limits lookups to a specific annotation. Setting the property to the
* empty string "" will cause the annotation form field to be set to the default "any" value.
* Doesn't work without the `assembly` property.
*
* @attribute
*/
annotation?: string;
/**
* An optional property to set the example text for the Gene Identifiers input field.
*
* @attribute
*/
genesExample?: string;
/**
* What regular experssion should be used to parse the input gene identifiers.
*
* @attribute
*/
genesRegexp: RegExp;
/**
* The maximum number of input gene identifiers.
* Warning: setting this number too high can cause queries to hit web browsers' URL size limit.
*
* @attribute
*/
genesLimit: number;
private selectedGenus;
private selectedSpecies;
private selectedStrain;
private selectedAssembly;
private selectedAnnotation;
protected formDataCancelPromiseController: LisCancelPromiseController;
private _splitGenesFunctionWrapper;
willUpdate(changedProperties: PropertyValues<this>): void;
private _formLoadingRef;
constructor();
updated(changedProperties: Map<string, unknown>): void;
private _getFormData;
private _initializeSelections;
private _selectGenus;
private _renderGenusSelector;
private _selectSpecies;
private _renderSpeciesSelector;
private _selectStrain;
private _renderStrainSelector;
private _selectAssembly;
private _renderAssemblySelector;
private _selectAnnotation;
private _renderAnnotationSelector;
private _validateForm;
/** @ignore */
renderForm(): import("lit-html").TemplateResult<1>;
}
declare global {
interface HTMLElementTagNameMap {
'lis-pangene-lookup-element': LisPangeneLookupElement;
}
}
export {};
//# sourceMappingURL=lis-pangene-lookup-element.d.ts.map