[6.x] Add Utility examples

[tao]

I understand the docs are still in Alpha and likely to change, but I would recommend adding some practical examples to the Utilities page as I found this the most difficult part of upgrading to 6.x.

One of the main issues I had is that because everything is powered by Inertia.JS now, the old functionality I had built no longer works.

I had a few utilities that would save or parse data (like converting raw text to markdown) that had to be rebuilt because when you return a result now, the Inertia page just refreshes back to it's original state.

There is also a function to commenceWangjangling in the docs but it doesn't show how that actually links up in the PHP code.

<ui-button @click="commenceWangjangling">
    Wangjangle that data.
</ui-button>

From scanning how Utilities work in the Statamic codebase, it seems like the only appropriate way to use Utilities is to redirect back with a Toast message.

Additionally, I had some Utilities that included some custom javascript that Inertia seems to remove from the page during render. I was able to get around these issues temporarily by including external scripts:

    /**
     * Bootstrap services.
     */
    public function boot(): void
    {
        $this->publishes([
            __DIR__.'/public' => public_path('vendor/llresearch/cp'),
        ], 'llresearch');

        Statamic::externalScript('/vendor/llresearch/cp/markdown-converter-utility.js');
    }

And then I could run the javascript functions with onclick.

But it also doesn't seem that elegant and maybe it would be easier to create a custom VueJS component and mount that in the view for the Utility?

I had another Utility which included a form to update the dictionary, as we run a custom spell-checker, and to update the dictionary I would have a textarea inside a form element, which would send the form data to the server to update the dictionaries and return back with the new data.

To get that to work I wrapped the whole Utility in a Form element, but that also doesn't seem like the correct or most elegant solution:

@section('content')
    <form method="POST" action="{{ cp_route('utilities.dictionary.update-all') }}">
        @csrf
        <ui-header title="Dictionary Editor">
            <template v-slot:actions>
                <ui-button type="submit" variant="primary">Save all</ui-button>
            </template>
        </ui-header>
        <div class="max-w-xl">
            @foreach ($dictionaries as $file => $content)
                <ui-panel>
                    <ui-heading size="lg" class="m-2">
                        {{ $file }}
                    </ui-heading>
                    <ui-textarea name="files[{{ $file }}]" rows="12" model-value="{{ $content }}"></ui-textarea>
                </ui-panel>
            @endforeach
        </div>
    </form>
@endsection

And this function works because it just redirects back with a toast message, so nothing fancy is happening:

 Utility::extend(function () {
            Utility::register('dictionary')
                ->title('Dictionary')
                ->description('View or edit custom words in Vale’s dictionary')
                ->icon('dictionary-language-book')
                ->view('dictionary::vale-dictionary', function () {
                    $manager = new DictionaryManager();

                    return [
                        'dictionaries' => $manager->allDictionaries(),
                    ];
                })
                ->routes(function ($router) {
                    $router->post('/', function (Request $request) {
                        $manager = new DictionaryManager;
                        $manager->saveMany($request->input('files', []));

                        return redirect()->back()->with('success', 'Dictionaries updated!');
                    })->name('update-all');
                });
        });

However, in the example included in the docs to commenceWangjangling and "Wangjangle that data." it doesn't actually provide an example of how to read the data that needs to be wanjangled. So maybe the example needs to show how to read form data and respond correctly for Inertia to work.