module-definitions

# 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: | Type | Implied location | Requested when | | --------------- | -------------------------------------- | ---------------------------------- | | `plugin` | `<name>` at the chart root | non-null and not `{ enabled: false }` | | `axis:plugin` | `axes[].<optionsKey ?? name>` | as above | | `series:plugin` | `series[].<name>` | any non-null value (`'present'`) | 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: ```ts 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: ```bash 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.