Sankey

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.

import { createSankey } from '@blukavantui/charts-pro/sankey'
import '@blukavantui/charts-pro/theme.css'
import '@blukavantui/charts-pro/styles.css'

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

export function mount(host: HTMLElement, options: Options, events: Events = {}) {
  const instance = createSankey(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 Sankey 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 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
         └─ If (LicenseReady) — True branch contains the chart
            └─ LiveChart — BluKavantUi_Charts_Pro.Sankey

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.

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.

Create Nodes first, then Links with a unique Key, SourceKey, TargetKey and nonnegative Value. Both endpoints must exist in Nodes. Link keys must be distinct from node keys. Aggregate duplicate business flows if you want one visible link per pair. The graph must be acyclic: remove self-links and loops before binding. Orientation and NodeAlign control layout.

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: Nodes)
For Each source record in your ordered query result:
  Assign RowNodes fields from that record
  ListAppend(List: Nodes, Element: RowNodes)

Example Assign values for the first sample row:
RowNodes.Key = "Organic"
RowNodes.Label = "Organic"
RowNodes.Color.Mode = Entities.ChartColorMode.Automatic
RowNodes.Color.ThemeColor = Entities.ComponentColor.Primary
RowNodes.Color.Hex = ""

[
  {
    "Key": "Organic",
    "Label": "Organic",
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "Paid",
    "Label": "Paid",
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "Referral",
    "Label": "Referral",
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "Trial",
    "Label": "Trial",
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "Demo",
    "Label": "Demo",
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  },
  {
    "Key": "Customer",
    "Label": "Customer",
    "Color": {
      "Mode": "Automatic",
      "ThemeColor": "Primary",
      "Hex": ""
    }
  }
]

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

Example Assign values for the first sample row:
RowLinks.Key = "organic-trial"
RowLinks.SourceKey = "Organic"
RowLinks.TargetKey = "Trial"
RowLinks.Value = 180

[
  {
    "Key": "organic-trial",
    "SourceKey": "Organic",
    "TargetKey": "Trial",
    "Value": 180
  },
  {
    "Key": "paid-trial",
    "SourceKey": "Paid",
    "TargetKey": "Trial",
    "Value": 120
  },
  {
    "Key": "paid-demo",
    "SourceKey": "Paid",
    "TargetKey": "Demo",
    "Value": 80
  },
  {
    "Key": "referral-demo",
    "SourceKey": "Referral",
    "TargetKey": "Demo",
    "Value": 100
  },
  {
    "Key": "trial-customer",
    "SourceKey": "Trial",
    "TargetKey": "Customer",
    "Value": 210
  },
  {
    "Key": "demo-customer",
    "SourceKey": "Demo",
    "TargetKey": "Customer",
    "Value": 140
  }
]

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
      Nodes = GetChartData.Nodes
      Links = GetChartData.Links
      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.

Point.PointKind distinguishes Node from Link. Links expose SourceKey and TargetKey; a node’s Value is derived throughput and IsDerived 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 a node and a link, route each to its own detail lookup, and reject a cyclic dataset in your application before rendering.
• 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 Sankey review screen ↗ · Full native API →