Improve disclosure component for state creating content, add options to control a transition's initial and after-end classes

Overview

This PR changes the headless disclosure to only render its panel's content once and then show/hide it based on styling. Currently, the panel's content is rendered every time the disclosure is opened/closed.

[!WARNING] In order to achieve this, the headless component no longer controls the panel's visibility. All styling is now solely done by the implementor of a headless discloure and needs to be adjusted accordingly. Thus, the changes introduced in this PR are api breaking!

Additionally, the transition function for Flow-based transitions has been extended to allow optional control over initial classes and classes that should be present after the leave-transition has ended. This is useful to allow transitions on an element's visibility which are normally not possible using pure CSS.

Disclosure

As mentioned earlier, the headless disclosure no longer creates a mount-point for its panel to re-render based on the open-state. Instead, it now only provides the state and leaves the styling to the implementor.

This is necessary due to multiple reasons: 1) Creating a mount-point is not related to styling, thus it can easily be done in headless. Hiding/showing an element is - that's why it cannot be done in headless. 2) Leaving the entire styling (including the styles used for hiding/showing the element) to the implementor allows for greater flexibility on how a concrete disclosure component might work. For example, it might behave similar to a spoiler element on social media sites and provide a blurred preview of some content that is revealed when clicked. 3) By leaving the styling to the user, all styling can be applied in a single place whithout some internal styling working against you.

Migration

In order to migrate an existing disclosure component, styling information for the opened/closed states must be provided. Find different migration scenarios below.

[!NOTE] Most of the examples below use Tailwind CSS. However, you are free to use any CSS framework, or even plain CSS, as well.

Example using plain CSS:

disclosurePanel {
    inlineStyle(opened.map {
        if (it) "display: block;" else "display: none;"
    })
}

1) The disclosure to migrate does not use transitions

In this case, the appropriate styling for the opened/closed states needs to be added. No existing styles have to be adjusted. This can be as easy as simply providing basic CSS styling:

Before:

disclosurePanel {
    // some content
}

After:

disclosurePanel {
    className(
        opened.map { if (it) "" else "hidden" },
        initial = "hidden"
    )
    // some content
}

2) The existing disclosure makes use of transitions

In this case, the existing transition call needs to be adjusted in order to provide visible/hidden classes. As mentioned in the beginning, this function has been adjusted accordingly.

Before:

disclosurePanel {
    transition(
        "transition transition-all duration-500 ease-in",
        "opacity-0 scale-y-95 max-h-0",
        "opacity-100 scale-y-100 max-h-[100vh]",
        "transition transition-all duration-500 ease-out",
        "opacity-100 scale-y-100 max-h-[100vh]",
        "opacity-0 scale-y-95 max-h-[0]"
    )
    // some content
}

After:

disclosurePanel {
    transition(
        opened,
//      ^^^^^^
//      change the transition to be flow based by specifing a triggering flow via the `on` parameter
        "transition transition-all duration-500 ease-in",
        "opacity-0 scale-y-95 max-h-0",
        "opacity-100 scale-y-100 max-h-[100vh]",
        "transition transition-all duration-500 ease-out",
        "opacity-100 scale-y-100 max-h-[100vh]",
        "opacity-0 scale-y-95 max-h-[0]",
         afterLeaveClasses = "hidden",
//      ^^^^^^
//      provide classes that should be present when the leave transition is over (panel hidden)
         initialClasses = "hidden"
//      ^^^^^^
//      provide an initial styling. In this case: `hidden`, since `opened` is false by default
    )
    // some content
}

Closes #754

jwstegemann / fritz2