React Embedded AnalyticsUpgrading to AG Studio 2

New time intelligence, field customisation, keyboard, charting and theming features.

What's New Copy Link

AG Studio 2 introduces:

• Calendars - Group and analyse data across time periods.
• Field Customisation - Configure field labels, formatting and behaviour.
• Keyboard Shortcuts - Drive Studio from the keyboard in edit and view modes.
• Group by Legend - Use a field as a chart legend to create grouped series.
• Pre-Configured Widgets - Offer widgets that come ready-configured for users to add.
• AI Extensibility - Extend the AI assistant with custom tools.
• Theme Builder - A visual tool for building and customising themes.

These features introduce certain breaking changes, as listed below.

Supported Frameworks Copy Link

The minimum supported framework and TypeScript versions have increased in AG Studio 2. See Version Compatibility for the full compatibility matrix.

The minimum supported React version is now 17.0.

The minimum supported TypeScript version is now 5.8.3.

Dependencies Copy Link

Studio now requires an additional first-party dependency ag-stack. This is automatically included in the ag-studio package dependencies.

Breaking Changes Copy Link

The full list of breaking changes in AG Studio 2.

Fields / Formats Copy Link

The following properties have been updated on the field (AgFieldDefinition) and format (AgFormatDefinition):

• options has been renamed to formatOptions.
• valueFormatter has been removed and replaced with createValueFormatter. createValueFormatter should return a value formatting function. Note that createValueFormatter receives the full set of params (options, fields, API, context), but the value formatting function will only receive the value to be formatted.

The format generic TFormats has now been replaced with TRegistry, with the custom format definition moved into the Registry Type (AgBaseRegistry gains the formats property). The following have had the generic property changed: AgDataSourcesDefinition (now only TRegistry generic), AgExpressionFieldDefinition (TRegistry swapped with TExpressionOperatorTypes and TFormats removed), AgExpressionOperatorTypes, AgFunctionExpression, AgExpression, AgSimpleDataSourceDefinition (generic order changed), AgAsyncTableDefinition, AgDataSourceDefinition, AgDataSource, AgDataSourcesUpdate, AgFieldDefinition (generic order changed), AgFormatOverride (added as first generic) and createFormats.

Filters Copy Link

The date-specific filter operators have been removed in favour of their generic equivalents:

The between operator (formerly inRange) is now inclusive of its endpoints, where it was previously exclusive. For the previous exclusive behaviour, combine greaterThan and lessThan with an AND.

Saved filter state from a version prior to 2.0.0 is migrated to the new operator names automatically on load. You only need to update code that sets these operators directly.

The filter state types now take the Registry Type instead of the removed AgFilterOperatorTypes:

• The types AgFilterOperatorTypeDefinition and AgFilterOperatorTypes have been removed.
• Types that previously took AgFilterOperatorTypes as a generic now take the registry type instead. Pass TRegistry, use the default AgDefaultRegistry, or pass your own registry type.
• Where TRegistry has been added as a generic (or replaced), it has been added as the first generic, shifting existing generics to the right.
  • Types which had AgFilterOperatorTypes as a generic (but not the first), and now have TRegistry as the first: AgConditionDefinition, AgLogicalDefinition, AgFilterDefinition, AgConditionFilterState, AgLogicalFilterState, AgFilterModelState, AgFilterState, AgFiltersState.
  • Types which did not have AgFilterOperatorTypes as a generic, and now have TRegistry as the first: AgFilterCondition, AgFilterLogical, AgFilter.

Removed APIs Copy Link

• AgRequestOptions.preferredShape has been removed. Use AgRequestOptions.shape instead.
• The AgWidget interface has been removed. Use AgDefaultWidget instead.
• AgWidgetConfig.crossFilter has been removed. Use AgWidgetConfig.featureConfig?.crossFilter instead.
• The deprecated locale keys aiToolAddWidgetsDesc, aiToolConfigurePageFiltersDesc, aiToolConfigureWidgetFiltersDesc, aiToolAddWidgets, aiToolConfigurePageFilters and aiToolConfigureWidgetFilters have been removed.

Theming Copy Link

• chartAxisColor has been renamed chartAxisLineColor.
• chartSeparationLinesColor has been renamed chartGroupedCategoryLineColor.
• createStudioTheme() no longer includes the default Studio icons. They are now exported as the part iconSetStudio. createStudioTheme().withPart(iconSetStudio) reproduces the previous behaviour. The default theme and studioTheme are unchanged.
• Studio elements are now inserted into application-owned DOM with a consistent structure: application-div > div.ag-theme-x > div.ag-ltr > div.ag-some-component. The theme and RTL classes that were previously set directly on a component are now set on a parent element. Application CSS targeting these classes on the component itself must be updated - for example, .ag-studio-root-inner.ag-rtl { ... } becomes .ag-rtl .ag-studio-root-inner { ... }.

Widgets & Toolbar Copy Link

• AgWidgetConfig now takes the widget shape as its first generic: AgWidgetConfig<TOptions> becomes AgWidgetConfig<TWidget, TOptions>. This corrects the typing of AgWidgetConfig.data.
• The AgWidgetConfig.toolbar property has been removed. The toolbar is implemented by Studio, so custom widgets should not set it.
• featureConfig.exportCsv has been removed from the widget definition (AgBaseWidgetDefinition). To disable CSV export for a Studio-provided widget, remove the item with id 'export' from the widget definition's toolbar property instead.
• The id property is now required for toolbar items (AgWidgetToolbarItem / AgWidgetToolbarButton) in a widget's toolbar definition.
• The deprecated overrides Studio property has been removed. Use the widgets property to Customise the Widget Configurations and Customise the Available Widgets, and the page property to Customise the Page Setup Form. The AgWidgetDisplayProperties interface has been removed.
• The callback form of the widgets Studio property now receives AgWidgetsConfig<AgDefaultRegistry> instead of AgWidgetsConfig<TRegistry>, since it is passed the default widgets rather than the overridden ones.

Behaviour Changes Copy Link

The full list of behaviour changes in AG Studio 2.

• Date-time fields are now filtered using the full date and time rather than the date alone. Saved filter state against a date-time field may match different rows:
  • greaterThan now matches values later in the same day.
  • lessThanOrEqual no longer matches values in the same day, matching up to the previous day only.
  • equals no longer matches every value within the day.
• Grand total row values in the grid widget are now displayed in bold.
• When state is loaded in View Mode without a widgetLayout property, widgets are no longer added to the layout.
• Series-specific format options are now grouped into a single section named after the series, located at the end of the Format panel. Options previously displayed under generic headings or split across multiple panel locations now appear together under their series name. This affects Bar, Column, Value, Linear Gauge, Radial Gauge, Text, Image, Table, Button Filter, List Filter, and Date Filter widgets:
  • The bar width option for Bar and Column charts has been moved into their respective series sections of the Format panel.
  • Value and gauge style options are consolidated under their respective series sections, with gauge scale options grouped as a sub-section.
  • Text and Image options previously shown under generic headings now appear under their respective series sections.
  • Filter widgets group all options under their respective series sections. Selection Type for List Filter and Filter Type for Date Filter are moved into Format.