Adds support for nested forms

[lukeraymonddowning]

Hi all,

I wasn't quite ready to push this in with #118, so thought it best to do in a follow-up PR. This essentially adds support for nested forms, which can optionally be executed under a given condition.

Reasoning

Take the example of the Laravel installer. It asks the user which stack they'd like to install: Jetstream, Breeze or nothing. If you think about it, a different set of inputs will be displayed depending on the stack that you select. In the current setup, it isn't possible to do this in a single form; you'd have to separate it out into multiple forms, but doing so would prevent you from reverting through the various form options (ie. once you selected Breeze, you can't go back and select Jetstream without cancelling the command).

Example

$responses = form()
    ->select(
        'Which scaffolding project would you like?', 
        ['Breeze', 'Jetstream', 'None'], 
        required: true, 
        name: 'scaffolding'
    )
    ->nested(
        fn (array $responses) => form()
            ->note("{$responses['scaffolding']} selected")
            ->confirm('Would you like to install dark mode?')
            ->select('Which stack would you like?', ['Blade', 'Vue', 'React']),
        when: fn (array $responses) => $responses['scaffolding'] === 'Breeze',
        name: 'breeze-stack',
    )
    ->nested(
        form()
            ->confirm('Would you like to install teams support?')
            ->confirm('Would you like to support dark mode?')
            ->select('Which stack would you like', ['Inertia', 'Livewire']),
        when: fn (array $responses) => $responses['scaffolding'] === 'Jetstream',
        name: 'jet-stack',
    )
    ->submit();

💡 This exact scenario is available to play with by running php playground/form.php

Here is an example based on the previously described scenario. The when condition passed allows us only run the nested forms if the given closure for each returns true. From the front-end perspective, it feels seamless, as though it were a single, unified form. However, the user can revert back to the first statement at any time. Here is a video showing this example:

Screen.Recording.2024-04-17.at.13.33.50.mov

You can see that previous responses are pre-filled, as in standard forms, and that we step through the inputs in logical order.

You can pass the nested method either a FormBuilder instance by calling form directly, or a Closure if you need access to previous responses from the form.

Would love to hear your thoughts! Thanks for all the hard work.

Kind Regards,
Luke

[github-actions]

Thanks for submitting a PR!

Note that draft PR's are not reviewed. If you would like a review, please mark your pull request as ready for review in the GitHub user interface.

Pull requests that are abandoned in draft may be closed due to inactivity.

[taylorotwell]

Gonna table this one for now as I don't really want to over-do Prompts in general. 😅