feat(banner): add expanded input property to the banner

[georgianastasov]

Closes #14890

Additional information (check all that apply):

• Bug fix
• New functionality
• Documentation
• Demos
• CI/CD

Checklist:

• All relevant tags have been applied to this PR
• This PR includes unit tests covering all the new code (test guidelines)
• This PR includes API docs for newly added methods/properties (api docs guidelines)
• This PR includes feature/README.MD updates for the feature docs
• This PR includes general feature table updates in the root README.MD
• This PR includes CHANGELOG.MD updates for newly added functionality
• This PR contains breaking changes
• This PR includes ng update migrations for the breaking changes (migrations guidelines)
• This PR includes behavioral changes and the feature specification has been updated with them

[wnvko]

Setting the collapsed input will not fire opening, opened, closing and closed events. Also banner changes its state without playing any animation. In this way if you:

• call banner.open a nice animation is played, opening and opened events are fired and banners opens.
• set collapsed to false no animation is played, no events are fired and banner gets opened.
  Is this behavior desired?

[georgianastasov]

Setting the collapsed input will not fire opening, opened, closing and closed events. Also banner changes its state without playing any animation. In this way if you:

• call banner.open a nice animation is played, opening and opened events are fired and banners opens.
• set collapsed to false no animation is played, no events are fired and banner gets opened.
  Is this behavior desired?

@wnvko I initially expected this to be the behavior of the collapsed property since it defines the initial state of the banner (expanded or collapsed). I didn’t think that events like opening opened closing or closed should fire when the property is setting the initial state. As for the animations, I’m unsure whether they should be included when toggling collapsed, considering its purpose of defining the starting state.

What’s your suggestion on how this should be handled? Should animations and events be tied to the collapsed property as well?

[wnvko]

@georgianastasov
The new property could be set at any moment. It is not limited to the initial state of the component. You can even change it during the opening/closing animation of the banner. I am not sure how component should behave in these cases. This should be described in the component specification.

[georgianastasov]

@wnvko You're absolutely right, the new collapsed property can be set at any point, even during the banner's open/close animations. I believe the key question here is whether the banner events should be triggered from the collapsed property or not, and if animation should be incorporated during these state transitions. This should definitely be detailed in the component specification to clarify the intended behavior.

@damyanpetev @simeonoff — Would you mind sharing your thoughts on how we should best implement this? Specifically, whether banner events should be triggered from the collapsed property and how to handle animations.

[simeonoff]

Two things I noticed:

1. No events should be fired when setting this property programatically. Also, no animations should be triggered initially. Animations trigger only when the property change programmatically on runtime.
2. To me a boolean property named expanded that is set initially to false sounds more logical.

[damyanpetev]

I'll echo parts of what @wnvko and @simeonoff already said:

• I personally agree events shouldn't fire for API calls, though we've had that discussion internally multiple times over the years and never quite settled; it's not entirely consistent across the product even and I don't think we want to open that can of worms for this. But we might not need to, more below.
• The name collapsed sort of stuck from toggle directive and propagated to multiple components. Can't say I like it much either, more like used to it. There's also the curios case of two other components - the Nav Drawer and Dialog have isOpen which I think is a decent alternative. And don't mind that co-existing with a collapsed getter.
• Animations honestly a toss depending on the component. For the banner I'm leaning towards without.

Funnily enough, collapsed is already an @Input on the Expansion Panel that does the same thing and it should be possible for the banner to use it and since that doesn't do animations it sets a pattern. The panel itself has a small issue with this being set while the closing animation runs since it sets the value on end, but that's a bit edge case and can be logged separately.

[georgianastasov]

After reviewing the discussion, here's the agreed implementation plan:

Property Name

• Introduce a new @Input property: expanded (default: false).
• The current collapsed property will remain accessible.

Event Handling

• No events (opening, opened, closing, closed) will fire when expanded is set programmatically.
• Events will fire only during user interaction (e.g., clicking to open/close the banner).

Animation Handling

• Animations will not trigger when expanded is initially set.
• Animations will trigger when expanded is updated programmatically during runtime.

State Transitions During Animations

• If expanded is updated during an ongoing animation, the current animation will be canceled, and the new state will be applied immediately without additional animations or events.

[wnvko]

If you change expanded to true while close animation is playing nothing happens!

Here is why. If you have banner which is not collapsed, expanded is true and you set expanded to false this will call close method to the internal expansionPanel. This will then call collapse method and it will start the close animation. At this point collapsed is still false. It will change to true once animation is finish.
While animation is playing if you change expanded to true it will call open method of the internal expansion panel. This will then call expand method. In this method the first check is this:

        if (!this.collapsed) { // If the panel is already opened, do nothing
            return;
        }

As expansion panel's collapsed is still false nothing will happen here.

[wnvko]

One more thing. Please when creating a PR add descriptive names, like add-expanded-to-banner. Having this at my side does not help me a lot