@legumeinfo/web-components
Version:
Web Components for the Legume Information System and other AgBio databases
178 lines • 6.18 kB
TypeScript
import { LitElement } from 'lit';
import { LisResizeObserverController } from '../controllers';
/**
* The structure each entry in the data given to the
* {@link LisLegendElement | `LisLegendElement`} component must have.
*/
export type LegendEntry = {
label: string;
color?: string;
};
/**
* The structure legend data must have when given to the
* {@link LisLegendElement | `LisLegendElement`} component.
*/
export type LegendData = LegendEntry[];
/**
* The signature of the function used by the
* {@link LisLegendElement | `LisLegendElement`} class to color legend entries.
* Note that if an entry already has a color it will be given precedence over the color
* provided by this function.
*
* @param entry The entry being colored.
*
* @returns A string containing a valid CSS color value.
*/
export type LegendColorFunction = (entry: LegendEntry) => string;
/**
* The signature of the function the {@link LisLegendElement | `LisLegendElement`}
* class calls when an entry in the legend has been clicked.
*
* @param entry The entry that was clicked.
*/
export type LegendClickFunction = (entry: LegendEntry) => void;
/**
* @htmlElement `<lis-legend-element>`
*
* A Web Component that draws a legend for data provided as a {@link LegendData | `LegendData`}
* 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-legend-element>` tag requires <b>version 7</b> of {@link https://d3js.org/ | D3}.
* To allow multiple versions of D3 to be used on the same page, the
* {@link LisLegendElement | `LisLegendElement`} class uses the global `d3v7` variable if it has
* been set. Otherwise it uses the global `d3` variable by default. The following is an example of
* how to include D3 in the page and set the `d3v7` variable:
* ```html
* <!-- head -->
*
* <!-- D3 version 7 -->
* <script src='http://d3js.org/d3.v7.min.js'></script>
*
* <!-- another version of D3 -->
* <script type='text/javascript'>
* var d3v7 = d3;
* window.d7 = undefined;
* </script>
* <script src='http://d3js.org/d3.v3.min.js'></script>
*
* <!-- body -->
*
* <!-- add the Web Component to your HTML -->
* <lis-legend-element></lis-legend-element>
* ```
*
* @example
* {@link !HTMLElement | `HTMLElement`} properties can only be set via JavaScript. This means the
* {@link data | `data`}, {@link colorFunction | `colorFunction`}, and
* {@link clickFunction | `nodeClickFunction`} properties must be set on a `<lis-legend-element>`
* tag's instance of the {@link LisLegendElement | `LisLegendElement`} class. For example:
* ```html
* <!-- add the Web Component to your HTML -->
* <lis-legend-element id="legend"></lis-legend-element>
*
* <!-- configure the Web Component via JavaScript -->
* <script type="text/javascript">
* // legend data
* const data = [
* {label: 'Acacia crassicarpa'},
* {label: 'Aeschynomene evenia'},
* {label: 'Apios americana'},
* ];
* // returns a color given an entry
* function color(entry) {
* // returns a color for the given label
* }
* // click callback that gets passed the clicked entry
* function click(entry) {
* // do something
* }
* // get the legend element
* const legendElement = document.getElementById('legend');
* // set the element's properties
* phylotreeElement.data = data;
* phylotreeElement.colorFunction = color;
* phylotreeElement.clickFunction = click;
* </script>
* ```
*
* @example
* The {@link layout | `layout`}, {@link glyph | `glyph`}, and {@link position | `position`}
* properties can be set as attributes of the `<lis-legend-element>` tag or as properties of the
* tag's instance of the {@link LisLegendElement | `LisLegendElement`} class.
* {@link layout | `layout`} sets the layout of the legend to `vertical` or `horizontal` (`vertical`
* by default). {@link glyph | `glyph`} determines whether the glyph of each entry will be drawn as
* a circle or a square (`circle` by default). And {@link position | `position`} determines the
* position of the glyph relative to the label (`left` by default). For example:
* ```html
* <!-- add the Web Component to your HTML -->
* <lis-legend-element
* layout="horizontal"
* glyph="square"
* position="contain"
* ></lis-legend-element>
* <lis-legend-element id="legend"></lis-legend-element>
*
* <!-- configure the Web Component via JavaScript -->
* <script type="text/javascript">
* // get the legend element
* const legendElement = document.getElementById('legend');
* // set the element's properties
* legendElement.layout = 'horizontal';
* legendElement.glyph = 'square';
* legendElement.position = 'contain';
* </script>
* ```
*/
export declare class LisLegendElement extends LitElement {
static readonly GLYPH_MARGIN = 5;
static readonly GLYPH_SIZE = 15;
createRenderRoot(): this;
private _legendContainerRef;
protected resizeObserverController: LisResizeObserverController;
/**
* The layout the legend should be drawn in.
*
* @attribute
*/
layout: 'vertical' | 'horizontal';
/**
* The glyph to use for each element in the legend.
*
* @attribute
*/
glyph: 'circle' | 'square';
/**
* Determines the position of the glyph relative to the label.
*
* @attribute
*/
position: 'left' | 'contain' | 'right';
/**
* The legend data.
*
* @attribute
*/
data: LegendData;
/**
* A function used to assign colors to entries.
*/
colorFunction?: LegendColorFunction;
/**
* A function called when an entry is clicked;
* the entry that was clicked is passed as the argument.
*/
clickFunction?: LegendClickFunction;
private _resize;
private _legendContainerReady;
render(): import("lit-html").TemplateResult<1>;
private _legendWidth;
private _drawLegend;
}
declare global {
interface HTMLElementTagNameMap {
'lis-legend-element': LisLegendElement;
}
}
//# sourceMappingURL=lis-legend-element.d.ts.map