ScatterChart

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.

import { createScatterChart } from '@blukavantui/charts-community/scatter'
import '@blukavantui/charts-community/theme.css'
import '@blukavantui/charts-community/styles.css'

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

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

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.

• 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.

In Service Studio, open Manage Dependencies. Reference ScatterChart from BluKavantUi_Charts_Community, 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. 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 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.

ChartScreen — your Screen
└─ ExistingLayout — your referenced Layout
   └─ Content — the Layout’s existing content slot
      └─ ChartRegion — new Container
         └─ LiveChart — BluKavantUi_Charts_Community.ScatterChart

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.

Build one Points record per observation with a stable Key, Label, X and Y. Use Group for an optional legend grouping. Set Bubble = True and each Points.UseSize = True to apply its nonnegative Size; leave UseSize = False for the default marker size. Label both axes with the metric and unit using XLabel and YLabel.

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.

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

Example Assign values for the first sample row:
RowPoints.Key = "a"
RowPoints.Label = "Acme"
RowPoints.X = 35
RowPoints.Y = 72
RowPoints.Size = 30
RowPoints.Group = "Enterprise"
RowPoints.UseSize = True
RowPoints.Color.Mode = Entities.ChartColorMode.Automatic
RowPoints.Color.ThemeColor = Entities.ComponentColor.Primary
RowPoints.Color.Hex = ""

[
  {
    "Key": "a",
    "Label": "Acme",
    "X": 35,
    "Y": 72,
    "Size": 30,
    "Group": "Enterprise",
    "UseSize": true,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "b",
    "Label": "Northstar",
    "X": 62,
    "Y": 110,
    "Size": 50,
    "Group": "Enterprise",
    "UseSize": true,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "c",
    "Label": "Brightline",
    "X": 82,
    "Y": 90,
    "Size": 45,
    "Group": "Enterprise",
    "UseSize": true,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "d",
    "Label": "Orbit",
    "X": 95,
    "Y": 148,
    "Size": 80,
    "Group": "Enterprise",
    "UseSize": true,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "e",
    "Label": "Studio",
    "X": 15,
    "Y": 25,
    "Size": 12,
    "Group": "Growth",
    "UseSize": true,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "f",
    "Label": "Beacon",
    "X": 30,
    "Y": 45,
    "Size": 18,
    "Group": "Growth",
    "UseSize": true,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "g",
    "Label": "Peak",
    "X": 48,
    "Y": 60,
    "Size": 28,
    "Group": "Growth",
    "UseSize": true,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "h",
    "Label": "Evergreen",
    "X": 70,
    "Y": 78,
    "Size": 35,
    "Group": "Growth",
    "UseSize": true,
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  }
]

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
      Points = GetChartData.Points
      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.

SelectionKey identifies the observation. Read X/Y only when Point.HasXY is True and Size only when Point.HasSize 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.

Start → Assign LiveChartId = ReceivedChartId → End

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

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

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

Start → Assign PatternsEnabled = ReceivedShowPatterns → End

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

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

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.

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.

• Activate two points that share the same coordinates but have different keys. Confirm the detail lookup uses the key, not a coordinate.
• 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.

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