Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TargetProcess/tauCharts/llms.txt

Use this file to discover all available pages before exploring further.

PluginsSDK provides utilities for plugin authors to interact with the internal chart specification tree, traverse units, and extract formatted field information. It is accessible at Taucharts.api.pluginsSDK.

​
Static methods

​
Unit and spec wrappers

​
PluginsSDK.unit
function
Wrap a raw unit reference in a helper object for easier manipulation.
PluginsSDK.unit(unitRef: object): Unit
​
PluginsSDK.spec
function
Wrap a raw spec reference in a helper object for easier manipulation.
PluginsSDK.spec(specRef: object): Spec

​
Object utilities

​
PluginsSDK.cloneObject
function
Deep clone an object using JSON serialization.
PluginsSDK.cloneObject(obj: object): object
This is a fast, dependency-free deep clone. It does not handle non-serializable values such as Date instances, functions, or undefined properties.

​
Spec tree traversal

​
PluginsSDK.depthFirstSearch
function
Search the spec unit tree depth-first, returning the first node that satisfies predicate.
PluginsSDK.depthFirstSearch(
  node: object,
  predicate: (node: object) => boolean
): object | undefined
Traverses node.frames[].units and node.units recursively.
​
PluginsSDK.traverseSpec
function
Visit every node in the spec tree, calling iterator on each node and its parent.
PluginsSDK.traverseSpec(
  spec: GPLSpec,
  iterator: (node: SpecUnit, parent: SpecUnit | null) => void
): void
Traversal starts at spec.unit. The root node receives null as its parent.
​
PluginsSDK.getParentUnit
function
Find the direct parent unit of a given unit within the spec tree, matched by uid.
PluginsSDK.getParentUnit(spec: object, unit: object): object | null
Returns null if the unit is the root or is not found.

​
Field format extraction

​
PluginsSDK.extractFieldsFormatInfo
function
Inspect the compiled spec and return a DimMap — one DimInfo entry per data field used in the chart.
PluginsSDK.extractFieldsFormatInfo(spec: GPLSpec): DimMap
Walks all COORDS.RECT nodes and extracts x, y, color, size, and label scale information, resolving format names and null aliases.
​
PluginsSDK.getFieldFormatters
function
Merge a caller-supplied formatter map with auto-detected field format info from the spec.
PluginsSDK.getFieldFormatters(
  spec: GPLSpec,
  formatters: { [field: string]: Formatter }
): { [field: string]: { label: string; format: (x: any) => string } }
Caller-supplied formatters override auto-detected ones. Each Formatter entry can be:
  • A function (x: any) => string
  • A string (registered format name)
  • An object { label?: string; format: (x: any) => string; nullAlias?: string }

​
Token registry

​
PluginsSDK.tokens
function
Return a simple key/value token registry scoped to the call site.
PluginsSDK.tokens(): {
  reg: (key: string, val: any) => this;
  get: (key: string) => any;
}
If a key has not been registered, get returns the key itself as a fallback.

​
The DimInfo interface

extractFieldsFormatInfo returns a map of field names to DimInfo objects:
​
label
string
required
Human-readable display label for the dimension. Derived from the axis guide label, or falls back to the field name.
​
format
(x: any, nullAlias?: string) => string
required
Formatter function for the dimension’s values. Handles null/undefined using nullAlias.
​
nullAlias
string
required
Text shown when a value is null or undefined. Defaults to "No <label>".
​
tickLabel
string
For complex object fields: the property name on the object that holds the tick label value.
​
isComplexField
boolean
true when the field references a nested object property via tickLabel.
​
parentField
string
For complex sub-fields: the name of the parent field in the DimMap.

​
Usage example

The pattern below is the standard way to read formatted field values inside a plugin: 
Taucharts.api.plugins.add('my-plugin', function (settings) {
  return {
    init(chart) {
      chart.on('specready', (chart, spec) => {
        // Extract format info from the compiled spec
        const info = Taucharts.api.pluginsSDK.extractFieldsFormatInfo(spec);

        // info['revenue'].label   => 'Revenue'
        // info['revenue'].format(1234567)  => '1.23M' (with x-num-auto)
        // info['revenue'].format(null)     => 'No Revenue'
      });
    },

    onRender() {
      // Example: find a specific unit type in the tree
      const chart = this._chart;
      const spec  = chart.getSpec();
      const pointUnit = Taucharts.api.pluginsSDK.depthFirstSearch(
        spec.unit,
        (node) => node.type === 'ELEMENT.POINT'
      );
    }
  };
});

​
Using getFieldFormatters with the tooltip plugin

Taucharts.api.plugins.get('tooltip')({
  formatters: Taucharts.api.pluginsSDK.getFieldFormatters(spec, {
    revenue: {
      label: 'Revenue (USD)',
      format: (x) => '$' + x.toLocaleString()
    }
  })
})
extractFieldsFormatInfo and getFieldFormatters operate on the compiled GPL spec available in the specready event, not on the original ChartSpec passed to the constructor.

Build docs developers (and LLMs) love

Get started for freeTalk to us