Module Definitions and Option Contributions

A ModuleDefinition is the single place a feature declares itself. Its type decides the lifecycle (chart, axis, series, plugin, axis:plugin, series:plugin, preset). Its option contributions decide which locations in the options tree it owns. Everything downstream derives from these two facts:

• first-pass validation defs for module-owned locations (composeChartOptionsDefs),
• the "required modules are not registered" report and the stripping of unowned options,
• stripping options a chart type does not support (Option \x` is not supported by `pie` series`),
• theme defaults merged from themeTemplate at the contributed path,
• the runtime decision to instantiate an axis or series plugin,
• the generated placeholder table in community and the ESLint example-validation mappings.

Never add a consumer that special-cases a module by name or option key. If a consumer needs to know about a location, the owning module must declare it.

When contributes is implied

Most modules own exactly the location their type implies, and declare nothing:

Chart, axis, series and preset modules own whole subtrees by identity and contribute nothing.

When to declare contributes

Declare it when the module owns options anywhere else, or owns several locations:

export const AxisInteractionModule: PluginModuleDefinition<never> = {
    type: 'plugin',
    name: 'axis-interaction',
    chartTypes: ['cartesian'],
    enterprise: true,
    version: VERSION,
    contributes: [
        { path: 'axes[].listeners.click', options: callback },
        { path: 'listeners.axisClick', options: callback },
    ],
    create: (ctx) => new AxisInteraction(ctx),
};

Each contribution:

• path: dotted, with [] marking a segment whose every child is a host (axes[], series[]). The first segment decides the host: axes[] is the axis host, series[] the series host, anything else the chart host.
• options: validation for the subtree, or one validator for a leaf such as a callback. Omit it to keep whatever the chart defs already declare there.
• themeTemplate: defaults merged at the path.
• chartTypes / axisTypes / seriesTypes: where the location applies. A contribution without chartTypes inherits the definition's; omitting the list applies everywhere, while an empty list applies nowhere.
• requested: 'enabled' (default) or 'present', deciding whether a supplied value counts as a request for the missing module.
• apiName: a public name for the report when the path alone reads badly.

A module with neither options nor a themeTemplate owns no option location at all (internal dependencies, the community series area), so it declares nothing.

Community and enterprise pairs

An enterprise module with the same name and version as a community one replaces it on registration (enterprise: true). Reserve this for a module whose behaviour the enterprise build changes wholesale; the generated placeholder then names the enterprise variant.

Contributing into another module's options

A feature that lives under another module's option key is its own module, not an override of the host. BackgroundRegionsModule declares contributes: [{ path: 'seriesArea.backgroundRegions', ... }] and depends on the community SeriesAreaModule, which exposes itself as the seriesArea service. Every chart module depends on that service, so ctx.seriesArea is never optional. The feature implements SeriesAreaContent and calls ctx.seriesArea.attach(this) to render inside the series area. The host reads the keys other modules contribute below its path through contributedKeysUnder and leaves them alone, so it validates only its own options.

Presets that users reach through an API entry point declare apiName: 'AgCharts.createGauge' so the report names the entry point rather than the registry name.

Generated tables

packages/ag-charts-enterprise/src/moduleTables.test.ts derives from the exported definitions:

• packages/ag-charts-community/src/chart/factory/expectedModules.generated.ts
• libraries/ag-charts-eslint-rules/rules/module-mappings.generated.mjs

and asserts that the documentation module list names only exported module ids. After changing a definition, a bundle, or a main.ts export, regenerate:

UPDATE_MODULE_TABLES=1 yarn nx test ag-charts-enterprise -- moduleTables
yarn nx format

The test fails until the files are regenerated. Do not edit the generated files. A module reachable only through a bundle is named after the smallest exported bundle that carries it.

libraries/ag-charts-eslint-rules/rules/module-mappings.mjs keeps only what definitions do not carry (default axes per series, intrinsic defaults, the cross-line listener owners) and merges it with the generated tables.

Checklist for a new module

1. Write the definition with type, name, version, create, and options/themeTemplate. Put undocumented keys inside the options literal with ...undocumentedDefs({...}), never by assigning onto it afterwards, which keeps it out of tree-shaking (see the api-contracts rule).
2. Declare contributes only if the implied location is wrong or incomplete. It replaces the implied location, so when adding locations, list the implied one alongside them.
3. Export it from the package main.ts and add it to the relevant module-bundles/*.ts.
4. Regenerate the tables and run yarn nx test ag-charts-community -- optionsModule so the parametrised contract test covers the new contribution.
5. Add the module to packages/ag-charts-website/src/content/module-mappings/modules.json if it is user-facing.