Needed to reference this type from common. Should this be modified with the ɵ syntax?

Since this API is already exposed in createComponent , I think it's fine to expose it on the public API. (Binding being also already public).

Could you please add /** @publicApi **/ to both Binding and DirectiveWithBindings.

Please advise if there is a better place to do this check.

Since we didn't deprecate setInput when we introduced bindings, we'll probably want to keep that API for now.
Depending on usages & user feedback, we can still deprecate it later.

Got it. Instead, how about a note in the description that this input is incompatible with the ngComponentOutletBindings input?

We'll definitely need such information in the JSDoc of both properties.
Something like "input and bindings are mutually exclusive, you can either use on or the other but not both together".

This is probably the right location for that (we'll see if we maybe want to extract that in a separate function.

Also, the general behavior we like to have is following:

• Throw if you provide both like you did
• Throw if the bindings change & the component outlet didn't change.

Bindings can only be set once, so we believe that they could be changed only we change the component that we show.

Also, the general behavior we like to have is following:

• Throw if you provide both like you did
• Throw if the bindings change & the component outlet didn't change.

Bindings can only be set once, so we believe that they could be changed only we change the component that we show.

Isn't this covered by adding ngComponentOutletBindings to the check in _needToReCreateComponentInstance(changes)? Or is this implicit behavior undesired?

We would want to explictly throw in such case.
Without this behavior, changing a binding (or more precisly changing the reference to the binding), would recreate the component from scratch which would be surprising.

@JeanMeche I don't mean to push back too much on this, but I think it might be worth considering (if you haven't already) that throwing an error here could make certain usages difficult/impossible.

Consider I have a component:

@Component({
  ...,
  template: `<ng-template *ngComponentOutlet="config().component; bindings = config().bindings" />`
})
class Switcher {
  readonly config = input.required<{ component: Type<>; bindings: Binding[] }>();
}

And I have multiple possible "configs" to pass to this Switcher component, including:

  configA = { component: ComponentX, bindings: [inputBinding("x", myValue)] };
  configB = { component: ComponentY, bindings: [inputBinding("y", myValue)] };
  configC = { component: ComponentX, bindings: [modelBinding("x", myWritableValue)] };

We would be able to switch from configA to configB or from configB to configC with no issue, but with the proposed error, switching directly from configA to configC would throw (because the ngComponentOutlet (component) property didn't change - it was ComponentX in both cases). In this case, it seems quite likely that the user might in fact want a completely different component instance (because their usage of the component is different in each case - one with an input binding and one with a model binding), but it would be impossible for them to achieve this.

Is this real-world use case you have ? Because while I see the argument, you could save that Config A & C are basically the same.
In terms of API design it is easier to go from something more restrictive to something less than the oppositive.
This is also why we prefer to be conservative first and maybe loosen the restrictions later if we consider the change to be worth it.

I guess my example wasn't great. Maybe a better case would be something like this:

productAConfig = {
  component: ProductTypeXComponent,
  bindings: [inputBinding("productId", () => "a"), twoWayBinding("quantity", productAQuantity)]
};
productBConfig = {
  component: ProductTypeYComponent
  bindings: [inputBinding("productId", () => "b"), twoWayBinding("quantity", productBQuantity)]
};
productCConfig = {
  component: ProductTypeXComponent,
  bindings: [inputBinding("productId", () => "c"), twoWayBinding("quantity", productCQuantity)]
};

Here, if we compare A and C, despite the fact that both products would be rendered using the same component type (X), I think we can see two reasons we would want to recreate the component with new bindings:

1. The productId binding is potentially non-reactive, e.g. it has some kind of logic that "initializes" the component using that product ID, and does not respond to further changes. (I try to avoid this kind of component, but I think in reality there are many such components in large codebases, particularly legacy components that use ngOnInit and not ngOnChanges.)
2. The quantity two-way binding needs to be switched to a writable signal that represents the current state of the quantity of that product, hence re-binding (and hence recreation of the component) is necessary.

@JeanMeche If my above example is not persuasive, I'll implement the requested behaviour (throw error when bindings change but component doesn't), can I just verify the following:

1. the requested behaviour should occur in the else block of the if (this._needToReCreateComponentInstance(changes)) conditional.
2. similar behaviour is not expected of the directives input