Function buildPublicApi

Returns {
    isEnabled: () => boolean;
    getIcons: () => TaxonomyIconsConfig | null;
    resolvePoiIcon: (poi: TaxonomyFeatureLike) => ResolvedIcon;
    getIconVariants: () => TaxonomyIconVariant[];
    getCategories: (ref: string) => Record<string, TaxonomyCategory>;
    getFieldMappings: (ref: string) => TaxonomyFieldMappings;
    getLayerCategories: (layerId: string) => Record<string, TaxonomyCategory>;
    resolveMarkerPaint: (
        layerId: string,
        existingPaint: Record<string, unknown>,
    ) => Record<string, unknown> | null;
    resolveTitleIcon: (
        layerId: string,
        feature: TaxonomyFeatureLike,
        surface: TaxonomySurface,
    ) => string | null;
    resolveBadgeStyle: (
        layerId: string,
        feature: TaxonomyFeatureLike,
        surface: TaxonomySurface,
        field: string,
    ) => ResolvedBadgeStyle | null;
    ensureSprite: () => void;
}

• isEnabled: () => boolean

  Whether the capability is active. Opt-out: true unless the profile explicitly sets modules.taxonomy.enabled: false.

• getIcons: () => TaxonomyIconsConfig | null

  Returns the shared sprite / icon config (modules.taxonomy.icons), or null when absent or the capability is disabled. Source of truth for the sprite loader (spriteUrl), the symbol layer's icon-size and the legend's showOnMap gate.

• resolvePoiIcon: (poi: TaxonomyFeatureLike) => ResolvedIcon

  Resolves the icon a POI point should display on the map.

  ⚠ The returned symbolId is a MapLibre ATLAS id — tinted when the category declares an iconColor. Not interchangeable with the DOM id returned by resolveTitleIcon.

• getIconVariants: () => TaxonomyIconVariant[]

  Every (icon × tint) pair the config references, for the MapLibre adapter to rasterise and register. Empty when nothing is tinted.

• getCategories: (ref: string) => Record<string, TaxonomyCategory>

  Returns the value → symbol table of a named taxonomy (empty when the taxonomy is unknown or the capability is disabled). Read by legend/filter.

• getFieldMappings: (ref: string) => TaxonomyFieldMappings

  Returns the raw-value → category/sub-category translation table of a named taxonomy (empty when unknown or the capability is disabled). Read by the legend generator to resolve icons for style rules keyed on a raw source attribute (e.g. fclass).

• getLayerCategories: (layerId: string) => Record<string, TaxonomyCategory>

  Returns the categories bound to a LAYER, resolving layers.<id>.use for the caller. Empty when the layer has no binding, the binding names an unknown taxonomy, or the capability is disabled.

  Prefer this over getCategories whenever you start from a layer: getCategories needs a taxonomy ref, which only the layers mapping knows. Reading that mapping from outside means duplicating resolveLayerBinding — which is how the AddPOI form ended up reading a profile key that never existed and silently rendering no category fields at all (dette C-8).

• resolveMarkerPaint: (
      layerId: string,
      existingPaint: Record<string, unknown>,
  ) => Record<string, unknown> | null

  The paint overrides that draw the marker disc under a point layer's icons.

  Returns only the keys taxonomy has something to say about, already spliced into the layer's existing paint: a ["case", …] from the layer's style rules keeps all its branches and only has its DEFAULT swapped. null when taxonomy has nothing to say (disabled, unbound, or no marker declared).

• resolveTitleIcon: (
      layerId: string,
      feature: TaxonomyFeatureLike,
      surface: TaxonomySurface,
  ) => string | null

  Resolves the sprite symbolId of the icon to show next to a feature's TITLE on a feature-info surface, honouring the per-surface render flags (priority sub-category → category → default).

  ⚠ Returns the RAW id, for <use href="#…"> against the DOM sprite. Not interchangeable with the tinted atlas id from resolvePoiIcon.

• resolveBadgeStyle: (
      layerId: string,
      feature: TaxonomyFeatureLike,
      surface: TaxonomySurface,
      field: string,
  ) => ResolvedBadgeStyle | null

  Resolves the colours of a category / sub-category pill badge, when the surface opted in via render.<surface>.colorBadges. Taxonomy decides, feature-info paints. Colours are validated here — the caller can assign them straight to the DOM.

• ensureSprite: () => void

  Ensures the active profile's SVG sprite (its <symbol> defs) is present in the DOM so a <use href="#…"> can reference it. Fire-and-forget and idempotent (the loader dedupes). Consumed by feature-info before injecting a category glyph on a surface that may render before any map icon layer has triggered the sprite injection.