Typed contexts

Author: mstijak

MIGRATION.md

@@ -404,9 +404,67 @@ export { Button, ButtonConfig } from "./Button";
 export { FlexBox, FlexBoxConfig } from "./FlexBox";
 ```
 
+## Typed RenderingContext Usage
+
+RenderingContext uses `[key: string]: any` to allow dynamic property access. Parent widgets set context properties that children consume. To add type safety, define typed context interfaces that extend RenderingContext and use them directly in method signatures.
+
+### Pattern: Typed Method Signatures
+
+Define a typed context interface next to the widget that sets the context properties, then use it in method signatures:
+
+```typescript
+// In ValidationGroup.ts
+import { RenderingContext } from "../../ui/RenderingContext";
+
+/** Typed context interface for form-related context properties */
+export interface FormRenderingContext extends RenderingContext {
+   parentDisabled?: boolean;
+   parentReadOnly?: boolean;
+   parentViewMode?: boolean | string;
+   parentTabOnEnterKey?: boolean;
+   parentVisited?: boolean;
+   parentStrict?: boolean;
+   parentAsterisk?: boolean;
+   validation?: { errors: ValidationErrorData[] };
+   lastFieldId?: string;
+}
+
+export class ValidationGroup extends PureContainerBase<...> {
+   // Use typed context directly in method signature
+   explore(context: FormRenderingContext, instance: ValidationGroupInstance): void {
+      context.push("parentStrict", coalesce(instance.data.strict, context.parentStrict));
+      context.push("parentDisabled", coalesce(instance.data.disabled, context.parentDisabled));
+      super.explore(context, instance);
+   }
+}
+```
+
+### Existing Typed Contexts
+
+**FormRenderingContext** (ValidationGroup.ts):
+- Used by: ValidationGroup, Field, Label, ValidationError, Button
+- Properties: `parentDisabled`, `parentReadOnly`, `parentViewMode`, `parentTabOnEnterKey`, `parentVisited`, `parentStrict`, `parentAsterisk`, `validation`, `lastFieldId`
+
+**SvgRenderingContext** (BoundedObject.ts):
+- Used by: Svg, BoundedObject and all SVG components
+- Properties: `parentRect`, `inSvg`, `addClipRect`
+
+**ChartRenderingContext** (Chart.ts) - extends SvgRenderingContext:
+- Used by: Chart, all chart components (LineGraph, ScatterGraph, Gridlines, Marker, etc.)
+- Properties: `axes` (Record of axis calculators)
+
+### Guidelines
+
+1. **Define locally**: Keep context interfaces next to the widgets that define them
+2. **Export for consumers**: Export the interface so child widgets can import and use it
+3. **Extend appropriately**: ChartRenderingContext extends SvgRenderingContext since charts need `parentRect`
+4. **Use non-null assertion**: When accessing context properties that must exist, use `context.axes!`
+
+---
+
 ## Nice to Have Improvements
 
-[ ] Typed RenderingContext usage
+[x] Typed RenderingContext usage
 [ ] Better StructuredProp and typed ContentResolver
 [ ] dropdownOptions might typed as DropdownConfig?
 [x] Properly type Component.create, Widget.create, etc.

docs/content/intro/TypeScriptMigration.js

@@ -132,6 +132,37 @@ export default (
          typed controller instance, enabling full autocomplete and compile-time type checking for
          controller methods and their parameters.
 
+         ### Typed RenderingContext
+
+         CxJS uses a `RenderingContext` object to pass information down the widget tree during rendering.
+         Different widget families define typed context interfaces that extend `RenderingContext` for
+         type-safe access to context properties.
+
+         **Available typed contexts:**
+
+         - `FormRenderingContext` - Form validation context (`parentDisabled`, `parentReadOnly`, `validation`, etc.)
+         - `SvgRenderingContext` - SVG layout context (`parentRect`, `inSvg`, `addClipRect`)
+         - `ChartRenderingContext` - Chart context extending SVG (`axes`)
+
+         When creating custom widgets that consume these context properties, import and use the typed
+         context interface in your method signatures:
+
+         <CodeSplit>
+            <CodeSnippet copy={false}>{`
+import type { FormRenderingContext } from "cx/widgets";
+
+export class MyFormWidget extends Field<MyFormWidgetConfig> {
+   explore(context: FormRenderingContext, instance: Instance) {
+      // Type-safe access to form context properties
+      if (context.parentDisabled) {
+         // handle disabled state
+      }
+      super.explore(context, instance);
+   }
+}
+            `}</CodeSnippet>
+         </CodeSplit>
+
          ## Authoring Widgets
 
          Previously, CxJS widgets had to be written in JavaScript with optional

packages/cx/src/charts/BubbleGraph.tsx

@@ -8,6 +8,7 @@ import { Instance } from "../ui/Instance";
 import { RenderingContext, CxChild } from "../ui/RenderingContext";
 import { Prop, StyleProp, DataRecord } from "../ui/Prop";
 import { Create } from "../util/Component";
+import type { ChartRenderingContext } from "./Chart";
 
 export interface BubbleGraphConfig extends WidgetConfig {
    /** Data array for the bubbles. */
@@ -80,8 +81,8 @@ export class BubbleGraph extends Widget<BubbleGraphConfig> {
       super.init();
    }
 
-   explore(context: RenderingContext, instance: BubbleGraphInstance) {
-      instance.axes = context.axes;
+   explore(context: ChartRenderingContext, instance: BubbleGraphInstance) {
+      instance.axes = context.axes!;
       super.explore(context, instance);
       var { data } = instance;
       const d = data as any;
@@ -93,13 +94,13 @@ export class BubbleGraph extends Widget<BubbleGraphConfig> {
       }
    }
 
-   prepare(context: RenderingContext, instance: BubbleGraphInstance) {
+   prepare(context: ChartRenderingContext, instance: BubbleGraphInstance) {
       super.prepare?.(context, instance);
       if (instance.axes[this.xAxis].shouldUpdate || (instance.axes as any)[this.yAxis].shouldUpdate)
          instance.markShouldUpdate(context);
    }
 
-   render(context: RenderingContext, instance: BubbleGraphInstance, key: string): CxChild {
+   render(context: ChartRenderingContext, instance: BubbleGraphInstance, key: string): CxChild {
       var { data } = instance;
       return (
          <g key={key} className={(data as any).classNames}>
@@ -108,7 +109,7 @@ export class BubbleGraph extends Widget<BubbleGraphConfig> {
       );
    }
 
-   renderData(context: RenderingContext, instance: BubbleGraphInstance): any {
+   renderData(context: ChartRenderingContext, instance: BubbleGraphInstance): any {
       var { data, axes, store } = instance;
       const d = data as any;
 

packages/cx/src/charts/Chart.ts

@@ -1,9 +1,14 @@
 import { Widget, VDOM, getContent } from "../ui/Widget";
-import { BoundedObject, BoundedObjectConfig, BoundedObjectInstance } from "../svg/BoundedObject";
+import { BoundedObject, BoundedObjectConfig, BoundedObjectInstance, SvgRenderingContext } from "../svg/BoundedObject";
 import { Axis } from "./axis/Axis";
 import { RenderingContext } from "../ui/RenderingContext";
 import { Create } from "../util/Component";
 
+/** Typed context interface for chart-related context properties */
+export interface ChartRenderingContext extends SvgRenderingContext {
+   axes?: Record<string, any>;
+}
+
 export interface ChartConfig extends BoundedObjectConfig {
    /** Axis definition. Each key represent an axis, and each value hold axis configuration. */
    axes?: Record<string, Create<typeof Axis>>;
@@ -35,7 +40,7 @@ export class Chart extends BoundedObject<ChartConfig, ChartInstance> {
       }
    }
 
-   explore(context: RenderingContext, instance: ChartInstance): void {
+   explore(context: ChartRenderingContext, instance: ChartInstance): void {
       instance.calculators = { ...context.axes };
 
       context.push("axes", instance.calculators);
@@ -53,25 +58,25 @@ export class Chart extends BoundedObject<ChartConfig, ChartInstance> {
       super.explore(context, instance);
    }
 
-   exploreCleanup(context: RenderingContext, instance: ChartInstance): void {
+   exploreCleanup(context: ChartRenderingContext, instance: ChartInstance): void {
       context.pop("axes");
 
       for (let axis in instance.axes) {
          instance.axes[axis].widget.reportData(context, instance.axes[axis]);
       }
    }
 
-   prepare(context: RenderingContext, instance: ChartInstance): void {
+   prepare(context: ChartRenderingContext, instance: ChartInstance): void {
       context.push("axes", instance.calculators);
       super.prepare(context, instance);
    }
 
-   prepareCleanup(context: RenderingContext, instance: ChartInstance): void {
+   prepareCleanup(context: ChartRenderingContext, instance: ChartInstance): void {
       context.pop("axes");
       super.prepareCleanup(context, instance);
    }
 
-   render(context: RenderingContext, instance: ChartInstance, key: string): any[] {
+   render(context: ChartRenderingContext, instance: ChartInstance, key: string): any[] {
       let axes = [];
       for (let k in instance.axes) {
          axes.push(getContent(instance.axes[k].render(context, key + "-axis-" + k)));

packages/cx/src/charts/ColumnBarBase.tsx

@@ -9,6 +9,7 @@ import { Prop, BooleanProp, NumberProp, StringProp } from "../ui/Prop";
 import { Instance } from "../ui/Instance";
 import { RenderingContext } from "../ui/RenderingContext";
 import { Rect } from "../svg/util/Rect";
+import type { ChartRenderingContext } from "./Chart";
 
 export interface ColumnBarBaseConfig extends StyledContainerConfig {
    /** The `x` value binding or expression. */
@@ -141,10 +142,10 @@ export class ColumnBarBase extends StyledContainerBase<ColumnBarBaseConfig> {
       );
    }
 
-   prepareData(context: RenderingContext, instance: ColumnBarBaseInstance): void {
-      instance.axes = context.axes;
-      instance.xAxis = context.axes[this.xAxis];
-      instance.yAxis = context.axes[this.yAxis];
+   prepareData(context: ChartRenderingContext, instance: ColumnBarBaseInstance): void {
+      instance.axes = context.axes!;
+      instance.xAxis = context.axes![this.xAxis];
+      instance.yAxis = context.axes![this.yAxis];
       instance.hoverSync = context.hoverSync;
       var { data } = instance;
       data.valid = this.checkValid(data);
@@ -156,7 +157,7 @@ export class ColumnBarBase extends StyledContainerBase<ColumnBarBaseConfig> {
       return true;
    }
 
-   prepare(context: RenderingContext, instance: ColumnBarBaseInstance): void {
+   prepare(context: ChartRenderingContext, instance: ColumnBarBaseInstance): void {
       let { data, colorMap } = instance;
 
       if (colorMap && data.colorName) {
@@ -190,7 +191,7 @@ export class ColumnBarBase extends StyledContainerBase<ColumnBarBaseConfig> {
          });
    }
 
-   prepareCleanup(context: RenderingContext, instance: ColumnBarBaseInstance): void {
+   prepareCleanup(context: ChartRenderingContext, instance: ColumnBarBaseInstance): void {
       let { data } = instance;
       if (data.valid && data.active) context.pop("parentRect");
    }

packages/cx/src/charts/ColumnBarGraphBase.tsx

@@ -5,6 +5,7 @@ import { Selection } from "../ui/selection/Selection";
 import { Instance } from "../ui/Instance";
 import { RenderingContext } from "../ui/RenderingContext";
 import { NumberProp, BooleanProp, StringProp, RecordsProp } from "../ui/Prop";
+import type { ChartRenderingContext } from "./Chart";
 
 export interface ColumnBarGraphBaseConfig extends WidgetConfig {
    /**
@@ -148,9 +149,9 @@ export class ColumnBarGraphBase extends Widget<ColumnBarGraphBaseConfig> {
       super.prepareData(context, instance);
    }
 
-   explore(context: RenderingContext, instance: ColumnBarGraphBaseInstance): void {
-      instance.xAxis = context.axes[this.xAxis];
-      instance.yAxis = context.axes[this.yAxis];
+   explore(context: ChartRenderingContext, instance: ColumnBarGraphBaseInstance): void {
+      instance.xAxis = context.axes![this.xAxis];
+      instance.yAxis = context.axes![this.yAxis];
 
       var { data } = instance;
 
@@ -160,7 +161,7 @@ export class ColumnBarGraphBase extends Widget<ColumnBarGraphBaseConfig> {
       super.explore(context, instance);
    }
 
-   prepare(context: RenderingContext, instance: ColumnBarGraphBaseInstance): void {
+   prepare(context: ChartRenderingContext, instance: ColumnBarGraphBaseInstance): void {
       let { data, colorMap, xAxis, yAxis } = instance;
 
       if (colorMap && data.name) {

packages/cx/src/charts/Gridlines.tsx

@@ -3,6 +3,7 @@
 import { BoundedObject, BoundedObjectConfig, BoundedObjectInstance } from "../svg/BoundedObject";
 import { VDOM } from "../ui/Widget";
 import { RenderingContext, CxChild } from "../ui/RenderingContext";
+import type { ChartRenderingContext } from "./Chart";
 
 export interface GridlinesConfig extends BoundedObjectConfig {
    /**
@@ -38,13 +39,13 @@ export class Gridlines extends BoundedObject<GridlinesConfig, GridlinesInstance>
       super(config);
    }
 
-   explore(context: RenderingContext, instance: GridlinesInstance) {
+   explore(context: ChartRenderingContext, instance: GridlinesInstance) {
       super.explore(context, instance);
-      instance.xAxis = (context.axes as any)?.[this.xAxis];
-      instance.yAxis = (context.axes as any)?.[this.yAxis];
+      instance.xAxis = context.axes?.[this.xAxis];
+      instance.yAxis = context.axes?.[this.yAxis];
    }
 
-   prepare(context: RenderingContext, instance: GridlinesInstance) {
+   prepare(context: ChartRenderingContext, instance: GridlinesInstance) {
       super.prepare(context, instance);
       let { xAxis, yAxis } = instance;
       if ((xAxis && xAxis.shouldUpdate) || (yAxis && yAxis.shouldUpdate)) instance.markShouldUpdate(context);

packages/cx/src/charts/LineGraph.tsx

@@ -6,6 +6,7 @@ import { parseStyle } from "../util/parseStyle";
 import { Instance } from "../ui/Instance";
 import { RenderingContext } from "../ui/RenderingContext";
 import { NumberProp, BooleanProp, StringProp, RecordsProp, StyleProp } from "../ui/Prop";
+import type { ChartRenderingContext } from "./Chart";
 
 interface LinePoint {
    x: number;
@@ -162,15 +163,15 @@ export class LineGraph extends Widget {
       super.prepareData(context, instance);
    }
 
-   explore(context: RenderingContext, instance: LineGraphInstance): void {
+   explore(context: ChartRenderingContext, instance: LineGraphInstance): void {
       let { data } = instance;
 
       instance.colorMap = data.colorMap && context.getColorMap && context.getColorMap(data.colorMap);
 
       if (instance.colorMap && data.colorName) instance.colorMap.acknowledge(data.colorName);
 
       if (data.active) {
-         instance.axes = context.axes;
+         instance.axes = context.axes!;
          instance.xAxis = instance.axes[this.xAxis];
          instance.yAxis = instance.axes[this.yAxis];
          super.explore(context, instance);
@@ -192,7 +193,7 @@ export class LineGraph extends Widget {
       }
    }
 
-   prepare(context: RenderingContext, instance: LineGraphInstance): void {
+   prepare(context: ChartRenderingContext, instance: LineGraphInstance): void {
       let { data, colorMap } = instance;
 
       if (colorMap && data.colorName) {

packages/cx/src/charts/Marker.tsx

@@ -21,6 +21,7 @@ import { getTopLevelBoundingClientRect } from "../util/getTopLevelBoundingClient
 import { RenderingContext } from "../ui/RenderingContext";
 import { NumberProp, BooleanProp, StringProp, StructuredProp } from "../ui/Prop";
 import { Instance } from "../ui/Instance";
+import type { ChartRenderingContext } from "./Chart";
 
 export interface MarkerConfig extends BoundedObjectConfig {
    /** The `x` value binding or expression. */

packages/cx/src/charts/MarkerLine.tsx

@@ -6,6 +6,7 @@ import { isDefined } from "../util/isDefined";
 import { Rect } from "../svg/util/Rect";
 import { RenderingContext } from "../ui/RenderingContext";
 import { NumberProp, BooleanProp, StringProp } from "../ui/Prop";
+import type { ChartRenderingContext } from "./Chart";
 
 export interface MarkerLineConfig extends BoundedObjectConfig {
    /** X coordinate for vertical line. */