GeoMap

Combine shaded regions and location bubbles on bundled or custom geographic maps.

IMPLEMENTATION GUIDE

Implement GeoMap in your application

Follow the setup steps, connect your application state, and verify each feature. Use the Code tab for the complete working Web example.

Web / TypeScript

Mount once, update state, clean up

Provide a real <div id="example"></div> in your view. Use the Code tab example's options and data as a starting point, then call this adapter with that host. Import the shared theme once per application and the component stylesheet with the component. Keep the returned instance for updates; call destroy() from your router/framework cleanup before removing the host. Configure your Pro license before mounting and keep your backend authorization separate from UI settings.

Typed mounting and cleanup adapter

import { createGeoMap } from '@blukavantui/charts-pro/geo-map'
import '@blukavantui/charts-pro/theme.css'
import '@blukavantui/charts-pro/styles.css'

type Options = NonNullable<Parameters<typeof createGeoMap>[1]>
type Events = NonNullable<Parameters<typeof createGeoMap>[2]>

export function mount(host: HTMLElement, options: Options, events: Events = {}) {
  const instance = createGeoMap(host, options, events)
  return {
    instance,
    update: (patch: Partial<Options>) => instance.update(patch),
    destroy: () => instance.destroy(),
  }
}

This helper takes your real options and callbacks; it does not fetch records or invent a backend. The Code tab’s working example supplies a usable data shape. Use stable record keys when updates refer to existing items.

Connect the features you need

Join business regions to the selected map

MapMapModeRegionsLocationsGeoJSONRoam

Choose World, US or Custom. Region keys must match the selected map's region identities; location points need valid longitude and latitude. For Custom, load valid GeoJSON through your application and pass the parsed object; configure CORS if your application fetches it from another origin. Select Regions, Locations or Combined mode and enable Roam only when useful.

Verify: Test unmatched regions, invalid coordinates, a failed custom map request and readable table alternatives.

Connect selection, loading and exports

Set IsLoading while your own request is pending and update data plus IsLoading together when it finishes. Use EmptyMessage for an empty result and your page's feedback region for a failed request. PointClick reports the selected point; resolve its stable key through your own authorized route or detail handler. In the released 1.0.0 package, SelectionChange reports Key. Echo controlled selection with SelectedKey or setSelection, without creating an update loop.

Call resize when a hidden chart becomes visible or its container changes outside normal layout observation. Use download for PNG/SVG and handle ExportComplete and Error. In the released 1.0.0 package, ExportComplete reports Format and FileName when the export is initiated; it does not prove the user saved the file. The browser controls the final file save. Keep ShowDataTable available for exact values, supply AccessibleLabel, and configure Locale/ValueFormat/CurrencyCode consistently. Do not infer additional permissions from a clicked point.

Before shipping

Use representative real data, including empty, loading and failed requests.
Test keyboard interaction, Light and Dark appearance, and a narrow screen with your longest labels.
Navigate away and back; confirm cleanup, expected state restoration and no duplicated callbacks.

OutSystems / Service Studio

Native OutSystems downloads available. Community is free; Pro requires a valid license covering the release. Download the native packages and complete IPP processing for your destination. Web downloads do not install in Service Studio. Modules, downloads and setup →

Reference the native producer and its types

In Service Studio, open Manage Dependencies. Reference GeoMap from BluKavantUi_Charts_Pro, the data Structures listed below from BluKavantUi_Charts_Core, and the Static Entities used by your options. Also reference BluChartPoint, BluChartSelection, BluChartError, ChartOrigin, ChartState, ChartExportFormat and the public Chart_Resize, Chart_Highlight and Chart_Download Client Actions.

Charts Core depends on BluKavantUi_Community_Core. Inherit BluUICommunityTheme through your application theme. Charts Pro does not require Charts Community if your application only uses Pro charts. The referenced Block includes the chart runtime and styles; you do not add ChartsRuntime or a separate chart engine to the screen. Refresh dependencies and publish your consumer after updating a producer.

Create screen state and place the Block

Create a screen named ChartScreen, or use an existing screen. Add these local variables; names are suggestions, but types must match. Keep each chart instance’s ChartId and selected state separate.

Screen local	Native type	Initial value	Binding / use
Regions	BluChartMapRegion List	Empty List	LiveChart.Regions = Regions
Locations	BluChartMapLocation List	Empty List	LiveChart.Locations = Locations
LastChartError	BluChartError	Native default	Set in HandleError
Loading	Boolean	True	LiveChart.IsLoading = Loading
LiveChartId	Text	""	Set in HandleChartReady
SelectionKey	Text	""	LiveChart.SelectedKey = SelectionKey
PatternsEnabled	Boolean	False	LiveChart.ShowPatterns = PatternsEnabled
LastPoint	BluChartPoint	Native default	Set in HandlePointClick
CurrentChartState	ChartState Identifier	Entities.ChartState.Loading	Set in HandleStateChanged
ChartRevision	Integer	0	Set in HandleStateChanged
ExportStatus	Text	""	Set in HandleExportStarted
LicenseReady	Boolean	False	Condition of the If containing LiveChart

ChartScreen — your Screen
└─ ExistingLayout — your referenced Layout
   └─ Content — the Layout’s existing content slot
      └─ ChartRegion — new Container
         └─ If (LicenseReady) — True branch contains the chart
            └─ LiveChart — BluKavantUi_Charts_Pro.GeoMap

Set the data bindings in the table on LiveChart. Set AccessibleLabel to a useful metric and time period, and Title to the chart heading. Use the layout’s actual slot name if it differs. Bind native choice values with expressions such as Entities.ChartValueFormat.Number.

Activate the Pro license before showing the chart

Reference ConfigureChartsLicense from BluKavantUi_Charts_Pro. In your consumer initialization flow, retrieve the authorized license and application ID from your application configuration, call the action, then set LicenseReady = ConfigureChartsLicense.Success. Pass its typed Error to your feedback path when activation fails. Keep the Block inside the True branch of the LicenseReady If.

Start → Load your authorized application license configuration
  → ConfigureChartsLicense(LicenseKey: configured key, ApplicationId: configured application ID)
  → Assign LicenseReady = ConfigureChartsLicense.Success
  → If not LicenseReady: handle ConfigureChartsLicense.Error → End

Use the existing BluKavantUI Pro entitlement. Never embed a customer or demo key into reusable producers. Follow the license validation and network connectivity requirements for your deployment.

Join region keys to map geometry

For World, use the supplied geometry keys such as USA or CAN; for US, use keys such as FL. Labels are display names, not join keys. Custom Regions.Key must exactly match each GeoJSON feature’s properties.name. Locations use independent keys, Longitude from −180 to 180, Latitude from −90 to 90 and nonnegative Value. Region and location keys must not collide. Bind MapMode to Regions, Locations or Combined.

Create your own GetChartData Data Action or Server Action, authorize its query and return the typed Lists above. If an Aggregate returns entity records, map them explicitly into these public Structures using a For Each, Assign and ListAppend. Only bind a query result directly when its type already matches. The chart does not query your database.

Regions · BluChartMapRegion List · sample records and mapping

Create a screen local Regions of type BluChartMapRegion List. In your mapping action, use a temporary RowRegions of type BluChartMapRegion. Fill every field used by this chart before appending each row.

ListClear(List: Regions)
For Each source record in your ordered query result:
  Assign RowRegions fields from that record
  ListAppend(List: Regions, Element: RowRegions)

Example Assign values for the first sample row:
RowRegions.Key = "USA"
RowRegions.Label = "United States"
RowRegions.Value = 840
RowRegions.Color.Mode = Entities.ChartColorMode.Automatic
RowRegions.Color.ThemeColor = Entities.ComponentColor.Primary
RowRegions.Color.Hex = ""
RowRegions.IsMissing = False

The loop describes your action flow, not code to paste into a JavaScript node. Replace the sample literals with your query fields. Reset optional fields on every iteration so values do not carry over from the previous row.

For a quick fixture, use JSON Deserialize with Data Type BluChartMapRegion List, then assign its Data output to Regions. In the JSONString expression editor, wrap the copied JSON in a Text literal and double embedded quotes, or read it from a Text variable. The resulting Block input remains a typed List.

[
  {
    "Key": "USA",
    "Label": "United States",
    "Value": 840,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    },
    "IsMissing": false
  },
  {
    "Key": "CAN",
    "Label": "Canada",
    "Value": 340,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    },
    "IsMissing": false
  },
  {
    "Key": "BRA",
    "Label": "Brazil",
    "Value": 220,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    },
    "IsMissing": false
  },
  {
    "Key": "GBR",
    "Label": "United Kingdom",
    "Value": 460,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    },
    "IsMissing": false
  },
  {
    "Key": "DEU",
    "Label": "Germany",
    "Value": 380,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    },
    "IsMissing": false
  },
  {
    "Key": "FRA",
    "Label": "France",
    "Value": 310,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    },
    "IsMissing": false
  },
  {
    "Key": "IND",
    "Label": "India",
    "Value": 520,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    },
    "IsMissing": false
  },
  {
    "Key": "AUS",
    "Label": "Australia",
    "Value": 290,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    },
    "IsMissing": false
  }
]

Locations · BluChartMapLocation List · sample records and mapping

Create a screen local Locations of type BluChartMapLocation List. In your mapping action, use a temporary RowLocations of type BluChartMapLocation. Fill every field used by this chart before appending each row.

ListClear(List: Locations)
For Each source record in your ordered query result:
  Assign RowLocations fields from that record
  ListAppend(List: Locations, Element: RowLocations)

Example Assign values for the first sample row:
RowLocations.Key = "new-york"
RowLocations.Label = "New York"
RowLocations.Longitude = -74.01
RowLocations.Latitude = 40.71
RowLocations.Value = 90
RowLocations.Color.Mode = Entities.ChartColorMode.Automatic
RowLocations.Color.ThemeColor = Entities.ComponentColor.Primary
RowLocations.Color.Hex = ""

For a quick fixture, use JSON Deserialize with Data Type BluChartMapLocation List, then assign its Data output to Locations. In the JSONString expression editor, wrap the copied JSON in a Text literal and double embedded quotes, or read it from a Text variable. The resulting Block input remains a typed List.

[
  {
    "Key": "new-york",
    "Label": "New York",
    "Longitude": -74.01,
    "Latitude": 40.71,
    "Value": 90,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "london",
    "Label": "London",
    "Longitude": -0.12,
    "Latitude": 51.51,
    "Value": 70,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "mumbai",
    "Label": "Mumbai",
    "Longitude": 72.88,
    "Latitude": 19.08,
    "Value": 65,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "sydney",
    "Label": "Sydney",
    "Longitude": 151.21,
    "Latitude": -33.87,
    "Value": 50,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  }
]

Use a custom GeoJSON resource

Add a GeoJSON FeatureCollection as a Resource in your consumer and deploy it to the application directory. Bind MapSource = Entities.ChartMapSource.Resource and MapResourceURL = Resources.YourMap.URL, using the actual resource name from Service Studio. Leave MapGeometryJSON blank. For inline data, select Entities.ChartMapSource.Inline, supply MapGeometryJSON as Text and leave MapResourceURL blank.

Each feature needs a unique properties.name matching Regions.Key and valid Polygon or MultiPolygon geometry. The browser must be able to retrieve a resource URL; check deployment, access and CORS when hosting externally. Built-in World/US maps must leave both custom-source fields blank.

Load and refresh data without remounting

Set Loading = True before a request. On success, assign all related Lists and Loading = False together in one Assign node. An empty successful result is a valid empty state. On an exception, set Loading to False and show your application’s request error; preserve the last successful data if useful. OnError reports chart failures, not errors in your Server Action.

GetChartData completes successfully
  → Assign
      Regions = GetChartData.Regions
      Locations = GetChartData.Locations
      Loading = False
  → End

If filters can change while a request is pending, disable repeated requests or use a request-version local and apply only the latest response. Keep keys stable and leave ResetKey unchanged during ordinary refreshes. Change ResetKey intentionally only when you want to reset the view and temporary highlight. The Block owns creation, updates and cleanup; do not manually mount a Web chart inside it.

Wire the Block events to screen Client Actions

Point.PointKind distinguishes Region from Location. Use SelectionKey for lookup; read coordinates only when HasCoordinates is True.

Create a screen Client Action for each event you need. Add the handler input parameters below, select that handler on LiveChart, and map its inputs to the event arguments in the Block properties.

OnChartReady → HandleChartReady

The native chart is mounted. Save ChartId for public Client Actions; it is valid only for this mounted instance.

Handler input	Native type	Mapping in LiveChart event property
ReceivedChartId	Text	ReceivedChartId = ChartId

Start → Assign LiveChartId = ReceivedChartId → End

OnPointClick → HandlePointClick

A point was activated on the chart or its data table. Origin distinguishes the two. Use Point business keys to open an authorized detail view.

Handler input	Native type	Mapping in LiveChart event property
ReceivedPoint	BluChartPoint	ReceivedPoint = Point
ReceivedOrigin	ChartOrigin Identifier	ReceivedOrigin = Origin

Start → Assign LastPoint = ReceivedPoint →
  Use the relevant business keys to open your detail screen or call your own data action → End

Keep ReceivedOrigin if your application distinguishes chart interaction from data-table interaction. An event does not authorize access: your Server Action or detail route must check the current user’s permissions.

OnSelectionChanged → HandleSelectionChanged

Selection changed or was cleared after a data update. Echo Key into SelectedKey only when HasSelection is True; otherwise assign an empty string.

Handler input	Native type	Mapping in LiveChart event property
ReceivedSelection	BluChartSelection	ReceivedSelection = Selection

Start → Assign SelectionKey = If(ReceivedSelection.HasSelection, ReceivedSelection.Key, "") → End

Bind LiveChart.SelectedKey = SelectionKey. Use the supplied key unchanged; do not reconstruct it from a label. Reason = "DataChanged" can clear a selection removed by a refresh. Echoing the new value is silent; do not reload all data solely to echo selection.

OnStateChanged → HandleStateChanged

The chart reports Loading, Ready, Empty or Error with its render revision. This is chart state, not confirmation of a database transaction.

Handler input	Native type	Mapping in LiveChart event property
ReceivedState	ChartState Identifier	ReceivedState = State
ReceivedRevision	Integer	ReceivedRevision = Revision

Start → Assign CurrentChartState = ReceivedState, ChartRevision = ReceivedRevision → End

OnPatternsChanged → HandlePatternsChanged

The toolbar changed pattern visibility. Echo ShowPatterns into the bound Boolean local.

Handler input	Native type	Mapping in LiveChart event property
ReceivedShowPatterns	Boolean	ReceivedShowPatterns = ShowPatterns

Start → Assign PatternsEnabled = ReceivedShowPatterns → End

OnExportStarted → HandleExportStarted

A PNG/SVG export was initiated. RequestId correlates a requested export; this event does not confirm the user saved a file.

Handler input	Native type	Mapping in LiveChart event property
ReceivedRequestId	Text	ReceivedRequestId = RequestId
ReceivedFormat	ChartExportFormat Identifier	ReceivedFormat = Format
ReceivedFileName	Text	ReceivedFileName = FileName

Start → Assign ExportStatus = "Export started" →
  Correlate ReceivedRequestId with your export request → End

OnError → HandleError

Validation, rendering, resource or license failure. Inspect Code and FieldPath; use RequestId to correlate an action failure. Show safe feedback and permit retry when appropriate.

Handler input	Native type	Mapping in LiveChart event property
ReceivedError	BluChartError	ReceivedError = Error

Start → Assign LastChartError = ReceivedError →
  Show safe feedback; log Code, FieldPath and RequestId in your application → End

Add external resize, highlight and export controls

Enable external chart controls only after LiveChartId <> "". Capture this value from OnChartReady, not ChartRegion.Id. Clear the stored ID if your screen removes the Block, and use the newly emitted ID after remounting.

Action	Input mappings	When to call
Chart_Resize	ChartId = LiveChartId	After the chart’s tab, modal or container becomes visible and its layout has rendered.
Chart_Highlight	ChartId = LiveChartId; SelectionKey = SelectionKey	Temporarily emphasize the selected item; pass "" to clear. It does not change SelectedKey.
Chart_Download	ChartId = LiveChartId; Format = Entities.ChartExportFormat.svg; FileName = "chart-report"; RequestId = ExportRequestId	From your Export button. Create ExportRequestId as a Text local and assign a new unique application token for each attempt.

Export button → If LiveChartId <> ""
  → Assign ExportRequestId = your new unique request token
  → Chart_Download(ChartId: LiveChartId, Format: Entities.ChartExportFormat.svg,
      FileName: "chart-report", RequestId: ExportRequestId)
  → If Chart_Download.Success
      True: show "Export started"
      False: handle Chart_Download.Error
  → End

Check Success and Error from every command. PNG is Entities.ChartExportFormat.png. OnExportStarted reports initiation only; the browser controls the file save. Chart_Highlight is temporary emphasis; use the bound SelectedKey for persistent selection.

Verify the complete application flow

Click a region and a marker and resolve different business records. Check an unknown geometry key and a failed custom resource load through OnError.
Publish the consumer, load realistic data, refresh it, then navigate away and back. Verify that handlers run once and that stale responses cannot overwrite new data.
Try empty data and an invalid record. Use OnError.Code and FieldPath to find the problem, then correct the inputs and retry.
Check narrow layouts, Light and Dark appearance, keyboard interaction and accessible labels. Keep exact values available in the data table.
Test a valid license and an activation failure in your consumer; show actionable feedback when the chart cannot be enabled.

Open the native GeoMap review screen ↗ · Full native API →

SEPARATE WEB PACKAGE

Install Charts Pro

Download Charts Pro from your account. It is included with your existing Pro license; configure the same license key.

npm install ./blukavantui-charts-pro-1.0.1.tgz

Import this chart from @blukavantui/charts-pro/geo-map. Keep the shared theme loaded once. Charts is separate from the UI library; your bundler only includes the chart modules you import.

Get package ↓Browser files & setup

Working TypeScript example

This code follows the current playground settings and input data.

Web / TypeScript · separate Charts bundle

These APIs belong to the released Web Charts package. Select OutSystems above for native Block inputs, types and events.

OUTSYSTEMS / SERVICE STUDIO

GeoMap native API

BluKavantUi_Charts_Pro.GeoMap · Structures and chart Static Entities from BluKavantUi_Charts_Core.

Follow the implementation guide →Open native showcase ↗

Block inputs

Bind typed Lists directly. Use native Static Entity records for choices; the Block handles serialization and its own lifecycle.

Application data

Input	Native type	Default / required	Meaning
Regions	BluChartMapRegion List	Empty List	Typed BluChartMapRegion List. Bind the matching screen List; see Implementation for field mapping and key relationships.
Locations	BluChartMapLocation List	Empty List	Typed BluChartMapLocation List. Bind the matching screen List; see Implementation for field mapping and key relationships.

Display and behavior

Input	Native type	Default / required	Meaning
Title	Text	"Chart"	Heading shown above the chart when ShowHeader is True.
Description	Text	""	Plain-text context beneath the title.
Height	Integer	320	Plot height in CSS pixels; large charts allow 160–1000. Header and table add to total height.
ValueFormat	ChartValueFormat Identifier	Entities.ChartValueFormat.Number	Display numbers, currency or percentages. Percent formats a ratio: 0.25 displays as 25%.
CurrencyCode	Text	"USD"	ISO currency code used with ValueFormat.Currency, for example USD or EUR.
Locale	Text	"en-US"	BCP 47 locale for number and date presentation, for example en-US or de-DE.
UseCustomPrecision	Boolean	False	Enable DecimalPlaces for display only; underlying values and exported table text are preserved.
DecimalPlaces	Integer	2	Display precision when UseCustomPrecision is True; does not round stored data.
AccessibleLabel	Text	""	Meaningful label for assistive technology; include the metric and reporting period.
ExtendedClass	Text	""	Additional CSS classes on this Block.
ResetKey	Text	""	Change intentionally to reset the view and temporary highlight. Ordinary data updates preserve the view.
ShowHeader	Boolean	True	Show the title and description.
ShowToolbar	Boolean	True	Show the built-in chart toolbar.
ShowLegend	Boolean	True	Show the series or item legend.
LegendStyle	ChartLegendStyle Identifier	Entities.ChartLegendStyle.Standard	Choose the legend presentation using a ChartLegendStyle record.
LegendPosition	ChartLegendPosition Identifier	Entities.ChartLegendPosition.Top	Place the legend above, below or beside the plot.
LegendShowValues	Boolean	True	Family-aware metric: latest observation, reported measures, count, throughput or value.
LegendShowPercentages	Boolean	False	Percentages apply only to circular partitions and top-level Treemap groups.
ShowTooltip	Boolean	True	Show point details on interaction.
ShowLabels	Boolean	False	Show measurement labels. Treemap, Sankey and Funnel retain identifying names even when False.
ShowDataTable	Boolean	True	True opens the accessible data table. False uses a compact disclosure; the data alternative remains available.
ShowPatterns	Boolean	False	Use patterns as an additional cue; echo OnPatternsChanged into this input.
EnableSelection	Boolean	True	Allow users to select data points.
EnableAnimation	Boolean	True	Animate chart transitions; reduced-motion preferences are respected.
IsLoading	Boolean	False	Set True while the consumer retrieves data; an empty list with False is an empty result.
EmptyMessage	Text	"No data to display"	Plain-text feedback when data is empty and IsLoading is False.
SelectedKey	Text	""	Stable family selection key; blank clears. Parent echoes are silent.
ExportFootnote	Text	"BluKavantUI Charts"	Plain-text attribution included in downloaded charts.
MapSource	ChartMapSource Identifier	Entities.ChartMapSource.World	Use a built-in world/US map, a deployed GeoJSON resource or inline GeoJSON.
MapView	ChartMapView Identifier	Entities.ChartMapView.Mainland	Choose the US mainland framing or the full map extent.
MapMode	ChartMapMode Identifier	Entities.ChartMapMode.Combined	Show region values, location markers or both.
Roam	Boolean	True	Allow map pan and zoom.
ColorScale	ChartColorScale Identifier	Entities.ChartColorScale.Automatic	Theme palette for the numeric scale. Diverging is supported by Heatmap only.
MapResourceURL	Text	""	Actual deployed resource URL for MapSource.Resource. Never concatenate a guessed resource path.
MapGeometryJSON	Text	""	Validated GeoJSON for MapSource.Inline. Built-in maps must leave custom sources blank.
Messages	BluChartMessage List	Empty List	Optional unique Key/Text translations. Labels are plain text, never executable HTML.

Events

Select a handler on the referenced Block’s event property. Create handler inputs with these exact types and map each event argument to its handler input. The Implementation tab includes complete mappings and action flows.

`OnChartReady`

The native chart is mounted. Save ChartId for public Client Actions; it is valid only for this mounted instance.

Event argument	Native type
ChartId	Text

`OnPointClick`

A point was activated on the chart or its data table. Origin distinguishes the two. Use Point business keys to open an authorized detail view.

Event argument	Native type
Point	BluChartPoint
Origin	ChartOrigin Identifier

`OnSelectionChanged`

Selection changed or was cleared after a data update. Echo Key into SelectedKey only when HasSelection is True; otherwise assign an empty string.

Event argument	Native type
Selection	BluChartSelection

`OnStateChanged`

The chart reports Loading, Ready, Empty or Error with its render revision. This is chart state, not confirmation of a database transaction.

Event argument	Native type
State	ChartState Identifier
Revision	Integer

`OnPatternsChanged`

The toolbar changed pattern visibility. Echo ShowPatterns into the bound Boolean local.

Event argument	Native type
ShowPatterns	Boolean

`OnExportStarted`

A PNG/SVG export was initiated. RequestId correlates a requested export; this event does not confirm the user saved a file.

Event argument	Native type
RequestId	Text
Format	ChartExportFormat Identifier
FileName	Text

`OnError`

Validation, rendering, resource or license failure. Inspect Code and FieldPath; use RequestId to correlate an action failure. Show safe feedback and permit retry when appropriate.

Event argument	Native type
Error	BluChartError

Public Client Actions

Reference each action from its owning producer. Chart commands require the live ChartId from OnChartReady. Check both Success and Error.

`ConfigureChartsLicense`

Producer: BluKavantUi_Charts_Pro. Configure the existing BluKavantUI Pro entitlement before rendering Pro chart Blocks. The consuming application supplies its key and application ID.

Input	Native type	Default / required	Meaning
LicenseKey	Text	Required	Commercial license from the consuming application configuration.
ApplicationId	Text	Required	Stable application ID associated with that license.

Output	Native type	Meaning
Success	Boolean	True when the entitlement can be used by this application.
Error	BluChartError	Structured activation error when Success is False.

`Chart_Resize`

Producer: BluKavantUi_Charts_Core. Recalculate layout after revealing a previously hidden chart. Call after its containing UI has rendered.

Input	Native type	Default / required	Meaning
ChartId	Text	Required	Saved ChartId from OnChartReady; never a Container.Id.

Output	Native type	Meaning
Success	Boolean	Whether the command was accepted.
Error	BluChartError	Structured error when rejected.

`Chart_Highlight`

Producer: BluKavantUi_Charts_Core. Temporarily highlight a selection key. Pass an empty string to clear the highlight. This does not change the controlled SelectedKey.

Input	Native type	Default / required	Meaning
ChartId	Text	Required	Saved ChartId from OnChartReady; never a Container.Id.
SelectionKey	Text	""	Existing family selection key, or blank to clear the temporary highlight.

Output	Native type	Meaning
Success	Boolean	Whether the command was accepted.
Error	BluChartError	Structured error when rejected.

`Chart_Download`

Producer: BluKavantUi_Charts_Core. Initiate a PNG or SVG export. Success means the operation was accepted, not that a file was saved.

Input	Native type	Default / required	Meaning
ChartId	Text	Required	Saved ChartId from OnChartReady; never a Container.Id.
Format	ChartExportFormat Identifier	Entities.ChartExportFormat.png	Native ChartExportFormat record.
FileName	Text	"chart"	Download filename without the format extension.
RequestId	Text	""	Optional application request token to correlate export events and errors.

Output	Native type	Meaning
Success	Boolean	Whether the command was accepted.
Error	BluChartError	Structured error when rejected.

Structures

Reference these public structures instead of creating lookalike local structures. Guard optional point fields with their Has… flags. Zero is a real number; IsMissing identifies absent measurements.

BluChartColorStructure · 3 fields

Producer: BluKavantUi_Charts_Core.

Attribute	Native type	Default	Meaning
Mode	ChartColorMode Identifier	Entities.ChartColorMode.Automatic	Select Automatic, Theme, or Custom.
ThemeColor	ComponentColor Identifier	Entities.ComponentColor.Primary	Existing Community palette identifier.
Hex	Text	""	Custom #RGB or #RRGGBB color.

BluChartMapRegionStructure · 5 fields

Producer: BluKavantUi_Charts_Core.

Attribute	Native type	Default	Meaning
Key	Text	""	Stable business key; must be unique in its list.
Label	Text	""	Plain-text display label.
Color	BluChartColor	Native default	Automatic palette, shared theme color, or validated custom hex.
Value	Decimal	0	Measurement. Use IsMissing for absent values; zero is a real value.
IsMissing	Boolean	False	True means the measurement is absent.

BluChartMapLocationStructure · 6 fields

Producer: BluKavantUi_Charts_Core.

Attribute	Native type	Default	Meaning
Key	Text	""	Stable business key; must be unique in its list.
Label	Text	""	Plain-text display label.
Color	BluChartColor	Native default	Automatic palette, shared theme color, or validated custom hex.
Longitude	Decimal	0	Longitude, -180 to 180.
Latitude	Decimal	0	Latitude, -90 to 90.
Value	Decimal	0	Marker measurement.

BluChartMessageStructure · 2 fields

Producer: BluKavantUi_Charts_Core.

Attribute	Native type	Default	Meaning
Key	Text	""	Supported translation key, unique in this list.
Text	Text	""	Plain-text translation; never HTML.

BluChartSelectionStructure · 4 fields

Producer: BluKavantUi_Charts_Core.

Attribute	Native type	Default	Meaning
HasSelection	Boolean	False	False means selection was cleared.
Key	Text	""	Stable selected key.
Kind	Text	""	Family selection category.
Reason	Text	""	User or DataChanged.

BluChartErrorStructure · 5 fields

Producer: BluKavantUi_Charts_Core.

Attribute	Native type	Default	Meaning
Code	Text	""	Stable error code.
Message	Text	""	Developer-facing diagnostic without consumer records or secrets.
FieldPath	Text	""	Field when identifiable.
RequestId	Text	""	Correlated request identifier.
IsRecoverable	Boolean	True	Whether corrected inputs can recover.

BluChartPointStructure · 29 fields

Producer: BluKavantUi_Charts_Core.

Attribute	Native type	Default	Meaning
PointKey	Text	""	Opaque identity for the specific observation. Use SelectionKey for SelectedKey; use business keys for your queries.
SelectionKey	Text	""	Value to use for controlled selection or highlighting.
SelectionKind	Text	""	Family selection kind; for example Category, Series, Cell, Point, Day or Node.
PointKind	Text	""	Point or observation kind. Sankey distinguishes Node and Link; GeoMap distinguishes Region and Location.
Label	Text	""	Native point context: Label.
Value	Decimal	0	Numeric measurement; when IsMissing is True, the zero here is only a placeholder.
IsMissing	Boolean	False	Native point context: IsMissing.
ValueText	Text	""	Invariant Decimal text retained at the native boundary where available; use for precise display or logging. Derived aggregates can be rounded.
CategoryKey	Text	""	Native point context: CategoryKey.
SeriesKey	Text	""	Native point context: SeriesKey.
SeriesLabel	Text	""	Native point context: SeriesLabel.
RingKey	Text	""	Native point context: RingKey.
XKey	Text	""	Native point context: XKey.
YKey	Text	""	Native point context: YKey.
ParentKey	Text	""	Native point context: ParentKey.
SourceKey	Text	""	Native point context: SourceKey.
TargetKey	Text	""	Native point context: TargetKey.
Group	Text	""	Native point context: Group.
HasDate	Boolean	False	Read Date only when True.
Date	Text	""	Date-only ISO text when HasDate=True.
HasXY	Boolean	False	Read X and Y only when True.
X	Decimal	0	Native point context: X.
Y	Decimal	0	Native point context: Y.
HasSize	Boolean	False	Read Size only when True.
Size	Decimal	0	Native point context: Size.
HasCoordinates	Boolean	False	Read Longitude and Latitude only when True.
Longitude	Decimal	0	Native point context: Longitude.
Latitude	Decimal	0	Native point context: Latitude.
IsDerived	Boolean	False	True for computed treemap parent totals and Sankey node throughput.

Static Entity choices

Bind expressions such as Entities.ChartValueFormat.Number. Names are case-sensitive. ComponentColor comes from Community Core; other chart choices come from Charts Core.

ChartColorMode3 records