@legumeinfo/web-components
Version:
Web Components for the Legume Information System and other AgBio databases
235 lines • 8.81 kB
TypeScript
import { LitElement } from 'lit';
import { LisResizeObserverController } from '../controllers';
/**
* The structure a phylotree must have if given to the
* {@link LisPhylotreeElement | `LisPhylotreeElement`} as an object.
*/
export type Phylotree = {
name: string;
length?: number;
color?: string;
children?: Phylotree[];
};
/**
* The signature of the function of the
* {@link LisPhylotreeElement | `LisPhylotreeElement`} class uses to color nodes by name.
* Note that if a node already has a color it will be given precedence over the color
* provided by this function.
*
* @param name The name of the being colored.
*
* @returns A string containing a valid CSS color value.
*/
export type PhylotreeColorFunction = (name: string) => string;
/**
* The signature of the function of the
* {@link LisPhylotreeElement | `LisPhylotreeElement`} class calls when a node in the
* phylotree has been clicked.
*
* @param node An instand of the TnT Tree Node class for the node that was clicked.
*/
export type PhylotreeClickFunction = (tree: unknown, node: unknown) => void;
/**
* @htmlElement `<lis-phylotree-element>`
*
* A Web Component that draws a phylotree provided as either a Newick string or a
* {@link Phylotree | `Phylotree`} object. Note that the component fills all of the
* available horizontal space and will automatically redraw if the width of its parent
* element changes.
*
* @example
* The `<lis-phylotree-element>` tag requires the
* {@link https://tntvis.github.io/tnt.tree/ | TnT Tree} library, which itself requires
* <b>version 3</b> of {@link https://d3js.org/ | D3}. To allow multiple versions of D3 to
* be used on the same page, the {@link LisPhylotreeElement | `LisPhylotreeElement`} class
* uses the global `d3v3` variable if it has been set. Otherwise it uses the global `d3`
* variable by default. The following is an example of how to include these dependencies
* in the page and set the `d3v3` variable:
* ```html
* <!-- head -->
*
* <!-- D3 version 3-->
* <script src="http://d3js.org/d3.v3.min.js"></script>
*
* <!-- another version of D3 -->
* <script type="text/javascript">
* var d3v3 = d3;
* window.d3 = undefined;
* </script>
* <script src="http://d3js.org/d3.v7.min.js"></script>
*
* <!-- TnT -->
* <link rel="stylesheet" href="http://tntvis.github.io/tnt/build/tnt.css" type="text/css" />
* <script src="http://tntvis.github.io/tnt/build/tnt.min.js"></script>
*
* <!-- body -->
*
* <!-- add the Web Component to your HTML -->
* <lis-phylotree-element></lis-phylotree-element>
* ```
*
* @example
* {@link !HTMLElement | `HTMLElement`} properties can only be set via JavaScript. This means the
* {@link colorFunction | `colorFunction`}, {@link nodeClickFunction | `nodeClickFunction`}, and
* {@link labelClickFunction | `labelClickFunction`} properties must be set on a
* `<lis-phylotree-element>` tag's instance of the
* {@link LisPhylotreeElement | `LisPhylotreeElement`} class. Similarly, if the
* {@link tree | `tree`} property will be set to a {@link Phylotree | `Phylotree`} object, rather
* than a Newick string, then it too must be set via the class instance. For example:
* ```html
* <!-- add the Web Component to your HTML -->
* <lis-phylotree-element id="phylotree"></lis-phylotree-element>
*
* <!-- configure the Web Component via JavaScript -->
* <script type="text/javascript">
* // returns a color given label of a node'
* function nodeColor(label) {
* // returns a color for the given label
* }
* // label click function that gets passed the TnT Tree and the TnT Node
* // associated with the label and is called in the TnT context
* function labelClick(tree, node) {
* // `this` is the TnT context
* }
* // node click function that gets passed the TnT Tree and the clicked TnT node
* // and is called in the TnT context
* function nodeClick(tree, node) {
* // `this` is the TnT context
* }
* // get the phylotree element
* const phylotreeElement = document.getElementById('phylotree');
* // set the element's properties
* phylotreeElement.colorFunction = nodeColor;
* phylotreeElement.labelClickFunction = labelClick;
* phylotreeElement.nodeClickFunction = nodeClick;
* </script>
* ```
*
* @example
* The {@link layout | `layout`}, {@link scale | `scale`}, and {@link edgeLengths | `edgeLengths`}
* properties can be set as attributes of the `<lis-phylotree-element>` tag or as properties of the
* tag's instance of the {@link LisPhylotreeElement | `LisPhylotreeElement`} class.
* {@link layout | `layout`} sets the layout of the phylotree to `vertical` or `radial` (`vertical`
* by default). {@link scale | `scale`} determines whether or not an edge length scale will be
* shown with the tree (`false` by default). And {@link edgeLengths | `edgeLengths`} determines
* whether edges should be drawn using unit length or using length data provided by the tree (unit,
* i.e. `false`, by default). For example:
* ```html
* <!-- add the Web Component to your HTML -->
* <lis-phylotree-element
* tree="(B:6.0,(A:5.0,C:3.0,E:4.0)G:5.0,D:11.0);"
* layout="radial"
* scale
* edgeLengths
* ></lis-phylotree-element>
* <lis-phylotree-element id="phylotree"></lis-phylotree-element>
*
* <!-- configure the Web Component via JavaScript -->
* <script type="text/javascript">
* // get the gene search element
* const phylotreeElement = document.getElementById('phylotree');
* // set the element's properties
* phylotreeElement.layout = 'radial';
* phylotreeElement.scale = true;
* phylotreeElement.edgeLengths = true;
* </script>
* ```
*/
export declare class LisPhylotreeElement extends LitElement {
static readonly AXIS_SAMPLE_PIXELS = 30;
static readonly AXIS_TICKS = 12;
static readonly SCALE_HEIGHT = 40;
static readonly TNT_LEFT_RIGHT_MARGIN = 3;
static readonly TNT_TRANSITION_DURATION = 500;
static readonly TNT_TRANSLATE = 20;
static newickToData(newick: string): Phylotree;
createRenderRoot(): this;
private _treeContainerRef;
private _scaleContainerRef;
protected resizeObserverController: LisResizeObserverController;
private _labelClicked;
private _data?;
private _tree;
/**
* The layout the tree should be drawn in.
*
* @attribute
*/
layout: 'vertical' | 'radial';
/**
* Determines whether or not a scale for the edge lengths will be drawn.
*
* @attribute
*/
scale: boolean;
/**
* Determines whether or not edge lengths are given by the tree. If not, each
* edge will be given unit length.
*
* @attribute
*/
edgeLengths: boolean;
/**
* Sets the pixel height of each label element.
*
* @attribute
*/
labelHeight: number;
/**
* The tree data.
*
* @attribute
*/
set tree(tree: string | Phylotree);
/**
* A function used to assign colors to nodes based on their name.
*/
colorFunction?: PhylotreeColorFunction;
/**
* A function called when a node is clicked;
* the TnT Tree Node object that was clicked is passed as the argument.
*/
nodeClickFunction?: PhylotreeClickFunction;
/**
* A function called when a leaf node label is clicked;
* the TnT Tree Node object the clicked label belongs to is passed as the argument.
*/
labelClickFunction?: PhylotreeClickFunction;
/**
* Determines if label click events are propagated to the node they are associated with.
* If so, this will trigger the node label click function. If a label click function and
* a node click function has been assigned, both click functions will be called.
*
* @attribute
*/
labelClickPropagation: boolean;
private _resize;
private _treeContainerReady;
render(): import("lit-html").TemplateResult<1>;
private _emitNodeClick;
private _emitLabelClick;
private _treeWidth;
private _actualTreeWidth;
private _drawTree;
/**
* Recursively computes the maximum distance from the root node.
*
* @param node The next node in the recursive traversal.
*/
private _maxRootDist;
private _xAxis;
private _drawScale;
private _updateXAxis;
/**
* Calls the `.update()` method on the component's instance of the TnT Tree. This should be used
* in preference of calling the `.update()` method directly when using the scale property because
* this method will also update the scale to reflect updates in the tree.
*/
updateTree(): void;
}
declare global {
interface HTMLElementTagNameMap {
'lis-phylotree-element': LisPhylotreeElement;
}
}
//# sourceMappingURL=lis-phylotree-element.d.ts.map