OverReact Documentation

The new boilerplate uses mixins for props declaration instead of direct subclassing. This allows for better sharing of props between components.

Rules:

1. Props classes must directly subclass UiProps.
2. All other props must be inherited via mixins.
3. Props must be declared within mixins.

Standard Pattern: Define a mixin for your props, then create a concrete class that is an alias for UiProps mixed with your props mixins.

Abbreviated Pattern: If no other mixins are used, you can use the mixin directly as the props type.

// Standard Pattern
mixin FooPropsMixin on UiProps {
  String foo;
}

class FooProps = UiProps with FooPropsMixin, BarPropsMixin;

// Abbreviated Pattern (when no other mixins are used)
mixin FooProps on UiProps {
  String foo;
}

Some props cannot be safely converted directly from JavaScript to Dart without risking runtime errors. In these cases, use a pattern involving a private JS-typed field (like JsMap) and public Dart getters/setters that use OverReact utilities to perform the translation.

This pattern allows the component to receive raw JS data while providing a clean, typed Dart interface to the consumer.

@Props(keyNamespace: '')
mixin ArbitraryComponentProps on UiProps {
  Map get aMapProp => unjsifyMapProp(_aMapProp$rawJs);

  set aMapProp(Map value) => _aMapProp$rawJs = jsifyMapProp(value);

  @Accessor(key: 'aMapProp')
  JsMap _aMapProp$rawJs;
}

You can create a unified props API for a component by combining multiple UiProps mixins using the with keyword in a class definition. This allows a component to expose properties from several different sources.

To implement this pattern effectively, you must distinguish between props that the component itself consumes and props that should be forwarded to a child component. This is achieved by controlling the consumedProps in class-based components or using getPropsToForward in functional components.

class MyComponentProps = UiProps with MixinA, MixinB;

class MyComponent extends UiComponent2<MyComponentProps> {
  @override
  get consumedProps => propsMeta.forMixins({MixinA}); // Only consumes MixinA, MixinB is forwarded

  @override
  render() {
    return (ChildComponent()
      ..modifyProps(addUnconsumedProps)
    )(/* ... */);
  }
}

The consumedProps method determines which props are considered 'consumed' by a component (and thus not forwarded via addUnconsumedProps or copyUnconsumedProps).

Default Behavior: In the new mixin-based syntax, UiComponent2 automatically consumes props from all props mixins by default if consumedProps is not overridden.

Customizing Consumption: To change this behavior, override consumedProps. You can use propsMeta to easily include or exclude specific mixins.

• To consume all except specific mixins: Use propsMeta.allExceptForMixins({MixinType}).
• To consume only specific mixins: Use propsMeta.forMixins({MixinType1, MixinType2}) (or manually list them via forMixin).

class FooComponent extends UiComponent2<FooProps> {
  @override
  get consumedProps => propsMeta.allExceptForMixins({NoConsumeProps});
}

When migrating to null safety, you must decide if a prop should be nullable (?) or non-nullable.

Decision Logic

1. Is it optional? All optional props should be made nullable (e.g., String? prop;).
2. Is it required?
   • If it is required but can be explicitly set to null, make it nullable and required (late String? prop;).
   • If it is required and should never be null, make it non-nullable and required (late String prop;).

Warning: Using the late keyword to make a prop required can be a breaking change if consumers do not always provide that prop.

Summary Table

With the addition of componentDidCatch and getDerivedStateFromError in Component2, you can now use Error Boundaries.

• Default ErrorBoundary: Use the built-in ErrorBoundary component provided by OverReact to wrap a component tree. This prevents the entire application from unmounting when a child component throws an error.
• Custom Error Boundaries: If you need custom logic, implement the ErrorBoundaryMixin to create your own boundary component.

OverReact is a layer atop the react-dart package that provides a 1:1 relationship with React JS component classes and APIs. An OverReact component is composed of four core pieces wired together via a builder:

1. UiFactory: The entry point used to consume a component.
2. UiProps: A Map class providing statically-typed getters and setters for component props.
3. A component, which can be either:
   • A function component defined via uiFunction.
   • A class component defined via UiComponent2 (optionally using UiState).

// Example of the four pieces working together (Conceptual)
// 1. UiFactory
// 2. UiProps
// 3. Component (UiComponent2 or uiFunction)