Chart Web Components

This page documents the web component layer that wraps PatternFly React charts as custom HTML elements. This layer enables Java code to instantiate and manipulate React-based charts through a standard web component interface.

For information about the overall chart architecture and data flow, see Chart Architecture Overview. For the Java-side API that consumes these web components, see Chart Java API. For the build and publishing process, see Chart Build and Publishing.

Overview

The chart web components are implemented using Lit as the base web component library and manage React component lifecycle internally. All chart web components extend the ReactWrapperElement base class, which provides common functionality for bridging web component attributes/properties to React props and managing the React rendering lifecycle.

Sources: charts/npm/src/react-wrapper.js16-393 charts/npm/src/components/pfj-chart-bullet.js1-196

ReactWrapperElement Base Class

The ReactWrapperElement class (defined in charts/npm/src/react-wrapper.js) provides the foundation for all chart web components. It extends LitElement and manages the complete lifecycle of wrapping React components as web components.

Class Structure and Internal State

Sources: charts/npm/src/react-wrapper.js71-393 charts/npm/src/components/pfj-chart-bullet.js19-193

The base class maintains several critical pieces of state:

Sources: charts/npm/src/react-wrapper.js83-106

Web Component Lifecycle

The lifecycle management ensures proper coordination between Lit's web component lifecycle and React's rendering lifecycle:

Sources: charts/npm/src/react-wrapper.js166-224

firstUpdated Method

The firstUpdated method (charts/npm/src/react-wrapper.js166-194) handles initial setup:

1. Locates the container element - Queries the shadow root for the .container div
2. Determines rendering mode - Checks if the element is slotted into a parent ReactWrapperElement
3. For standalone elements:
   • Creates a React root using createRoot(this._container)
   • Sets up a MutationObserver to watch for attribute and child changes
   • Listens for slot changes to re-render when children are modified
   • Calls _renderReact() to perform initial render
4. For slotted elements:
   • Only creates a MutationObserver to notify the parent when attributes change
   • Does NOT create a React root (parent handles rendering)

disconnectedCallback Method

The disconnectedCallback method (charts/npm/src/react-wrapper.js196-206) ensures proper cleanup:

1. Disconnects and nullifies the MutationObserver
2. Unmounts and nullifies the React root (if present)
3. Calls the superclass cleanup

Sources: charts/npm/src/react-wrapper.js166-206

Attribute and Property Handling

The web component supports two ways to configure charts: HTML attributes and JavaScript properties. The parseAttrValue utility function handles conversion from string attributes to appropriate JavaScript types:

Sources: charts/npm/README.md33-64 charts/npm/src/react-wrapper.js23-41

Property Getters and Setters

Each common property (data, height, width, labels, etc.) has a getter and setter pair that:

1. Stores the value in a private field (e.g., _data)
2. Calls _notifyChange() when set, which triggers a re-render

For example, the data property:

Sources: charts/npm/src/react-wrapper.js236-243

The _notifyChange method (charts/npm/src/react-wrapper.js214-223) implements different behavior based on whether the element is slotted:

• For slotted elements: Notifies the parent to re-render
• For standalone elements: Calls _renderReact() directly

Sources: charts/npm/src/react-wrapper.js214-223

Building React Props

The _commonProps method (charts/npm/src/react-wrapper.js344-392) builds a props object for React by:

1. Checking JavaScript properties first (e.g., this._data)
2. Falling back to HTML attributes if property is not set
3. Parsing attribute values using parseAttrValue
4. Handling special cases (e.g., numbers must be converted explicitly)

This enables both declarative HTML usage and imperative JavaScript manipulation:

Sources: charts/npm/src/react-wrapper.js344-392 charts/npm/demo.html112-142

React Component Rendering

The _renderReact method (charts/npm/src/react-wrapper.js127-140) is the central rendering method:

Sources: charts/npm/src/react-wrapper.js127-140

The rendering process:

1. Exits early if no React root exists (element is slotted)
2. Builds raw props from all HTML attributes using _buildPropsFromAttributes (charts/npm/src/react-wrapper.js44-53)
3. Adds common props from JavaScript properties using _commonProps
4. Calls getReactComponent() - Subclass provides [ReactComponent, extraProps] pair
5. Merges props - Combines raw, common, and extra props
6. Filters disallowed props - Removes props that expect React elements (see Disallowed Props)
7. Gets children - Converts slotted web components to React elements
8. Creates React element - React.createElement(Component, props, ...children)
9. Renders - _root.render(element)

Sources: charts/npm/src/react-wrapper.js127-140

Disallowed Props

Certain React props are filtered out because they expect React components as values, which cannot be passed through web component attributes. The disallowed set is defined at charts/npm/src/react-wrapper.js58-67:

These props are removed during rendering at charts/npm/src/react-wrapper.js134-136

Sources: charts/npm/src/react-wrapper.js58-67 charts/npm/src/react-wrapper.js134-136

Concrete Chart Components

Each chart type is implemented as a subclass of ReactWrapperElement that defines chart-specific properties and returns the corresponding React component.

Chart Component Structure

Sources: charts/npm/README.md9-15 charts/npm/src/components/pfj-chart-bullet.js1-196

Example: ChartBulletWebComponent

The bullet chart component (charts/npm/src/components/pfj-chart-bullet.js) demonstrates the typical implementation pattern:

Constructor (charts/npm/src/components/pfj-chart-bullet.js21-34): Initializes chart-specific properties as undefined:

getReactComponent (charts/npm/src/components/pfj-chart-bullet.js36-93): Returns the React component class and chart-specific props:

Property accessors (charts/npm/src/components/pfj-chart-bullet.js95-193): Each property follows the same pattern:

Custom element registration (charts/npm/src/components/pfj-chart-bullet.js195):

Sources: charts/npm/src/components/pfj-chart-bullet.js1-196

Slotted Children Support

Some chart components support nesting other chart components as children using the slot mechanism. The most common use case is nesting a <pfj-chart-donut-utilization> inside a <pfj-chart-donut-threshold>.

Slotted vs Standalone Rendering

Sources: charts/npm/src/react-wrapper.js166-194 charts/npm/src/react-wrapper.js208-212

How Slotted Children Work

When a ReactWrapperElement detects it is slotted into another ReactWrapperElement (charts/npm/src/react-wrapper.js208-212):

1. It does NOT create a React root
2. It sets up a MutationObserver to notify the parent when its attributes change
3. The parent's _renderReact method calls _getReactChildren() to convert slotted elements to React elements

The _getReactChildren method (charts/npm/src/react-wrapper.js142-162) implements the conversion:

Sources: charts/npm/src/react-wrapper.js142-162

Example: Donut Threshold with Nested Utilization

The HTML structure:

The rendering flow:

1. Parent <pfj-chart-donut-threshold> creates a React root
2. Child <pfj-chart-donut-utilization> detects it is slotted and does NOT create a root
3. Parent's _renderReact calls _getReactChildren()
4. Child element is converted to React.createElement(ChartDonutUtilization, childProps)
5. Parent renders: React.createElement(ChartDonutThreshold, parentProps, childElement)

Sources: charts/npm/README.md50-64 charts/npm/demo.html78-94

Change Detection and Re-rendering

The web component uses a MutationObserver to detect changes and trigger re-renders.

Sources: charts/npm/src/react-wrapper.js184-185 charts/npm/src/react-wrapper.js214-223

Observer Configuration

For standalone elements (charts/npm/src/react-wrapper.js184-192):

This watches for:

• attributes: true - Attribute changes on the element
• childList: true - Children being added/removed
• subtree: true - Changes in descendant nodes

The observer also listens for slotchange events to re-render when slotted children change.

For slotted elements (charts/npm/src/react-wrapper.js174-179):

This only watches for attribute changes and notifies the parent to re-render.

Sources: charts/npm/src/react-wrapper.js174-192

Integration with Showcase Application

The showcase application imports and uses the chart web components:

Import statement in showcase/src/web/main.js19:

This single import registers all chart web components with the browser's custom element registry.

Java code then instantiates and configures the elements:

The DonutElement interface is defined in Java with JSInterop annotations, and the externs file (charts/src/main/resources/META-INF/externs/charts.externs.js) ensures property names are preserved during J2CL compilation.

Sources: showcase/src/web/main.js16-20 charts/npm/README.md1-87

Summary

The chart web component layer provides:

The architecture enables Java developers to work with React-based charts through a clean web component API while the wrapper handles all React-specific complexity transparently.

Sources: charts/npm/src/react-wrapper.js1-394 charts/npm/src/components/pfj-chart-bullet.js1-196 charts/npm/README.md1-87