The widget provides an interface to an AI assistant that can process the content of its slotted element. It presents a
dropdown menu with various prompts (e.g., summarize, fix grammar) and displays the result in a card for review before
applying it back to the target widget.

## Examples

:::warning
None of the examples will work here in the docs as the AI agent cannot be accessed.
:::

### Single Target (Default)

By default, the widget processes the first element placed in its default slot.

```html:preview
<et2-ai>
<et2-textbox value="This is some text that needs to be more formal."></et2-textbox>
</et2-ai>
```

### Multiple Elements (Nested Target)

If you want to process multiple fields together, or if your target is inside a container like Et2Box, the widget will
attempt to extract values from the container using standard eTemplate2 methods.

```html:preview
<et2-ai>
    <et2-vbox>
        <et2-textbox label="Job" id="job_name" value="Do the thing with the thing"></et2-textbox>
        <et2-textarea label="Details" id="body" value="Don't forget the meeting tomorrow at 10 AM."></et2-textarea>
    </et2-box>
</et2-ai>
```

### Custom Prompt Menu

By default, the widget displays the prompts available to the current user and app from the server-side AI Tools
configuration. You can override that list for a specific Et2Ai instance to select, relabel, group, or configure how
registered prompts are applied. This does not define new prompt text in the browser: every prompt ID must exist in the
server-side AI Tools prompt configuration.

Each prompt can define an `actions` array. An action can specify a target (where the result goes) and a mode (`replace`,
`append`, or `prepend`).

```html:preview
<et2-ai id="custom-ai">
<et2-textarea id="my-target" value="Original content. "></et2-textarea>
</et2-ai>
<et2-textarea id="review-copy" label="Review copy"></et2-textarea>
<script>
    const aiWidget = document.getElementById('custom-ai');
    aiWidget.prompts = [
        {
            id: "aiassist.translate-de", 
            label: "Translate to German",
            actions: [{ target: "#my-target", mode: "replace" }]
        },
        {
            // This ID must be configured in AI Tools first
            id: "custom.expand",
            label: "Add more detail",
            actions: [
                { label: "Append", target: "#my-target", mode: "append" },
                {
                    label: "Send for review",
                    handler: function(result) {
                        document.getElementById("review-copy").set_value(result);
                        // Custom handlers run with the Et2Ai element as `this`
                        this.dispatchEvent(new CustomEvent("review-copy-ready", {
                            detail: { result },
                            bubbles: true,
                            composed: true
                        }));
                    }
                }
            ]
        }
    ];
</script>
```

:::tip
Administrators create or edit custom prompt text in the AI Tools prompt configuration. Setting `prompts` here only
changes the menu and response actions for this widget instance.
:::

An action with a `handler` receives the raw AI result as its only argument. The handler runs with the Et2Ai element as
`this` and is responsible for applying or forwarding the result; `target` and `mode` are not used for that action.

### Using Events

You can listen for the `et2-ai-apply` event to inspect the prompt, result, and resolved target before the action runs.
Change `event.detail.result` to transform the value passed to the built-in action or custom handler. Call
`preventDefault()` to cancel the action entirely.

```html:preview 
<et2-ai id="event-demo">
    <et2-textarea value="This text will be intercepted."></et2-textarea>
</et2-ai>

<script>
    const eventAi = document.getElementById('event-demo');
    eventAi.addEventListener('et2-ai-apply', (e) => {
        // e.detail.result contains the AI output
        // e.detail.target contains the element where it will be applied

        if (confirm("Add a signature to the result?")) {
            e.detail.result += "\n\nGenerated by AI Assistant";
        }

        if (!confirm("Apply this result?")) {
            e.preventDefault();
        }
    });
</script>
```
