.OVERLAY

Zeigt modale Overlays (Text, Buttons, HTML, Datei-Upload, Ladeanimation) über dem Chat an (RAGAI.OVERLAY).

Hintergrund

Im Gegensatz zu RAGAI.CARDS sind Overlays nicht Teil des persistenten Chatverlaufs - sie legen sich modal über die aktuelle Ansicht und verschwinden wieder, ohne im Verlauf gespeichert zu werden. Pro Zeitpunkt existiert höchstens ein Overlay: Jede neue show*-Methode schließt implizit ein zuvor offenes Overlay. setPlacement bestimmt, in welchem Dokument (eigenes Bot-Fenster oder das umgebende Elternfenster bei 'fusionview') das Overlay eingehängt wird - wichtig, wenn der Bot in eine Fusion-View (LMS-Kursseite) eingebettet läuft und das Overlay die gesamte Seite abdecken soll statt nur das (oft kleine) Bot-Iframe.

Methoden

.close()

Schließt das aktuell angezeigte Overlay (im Bot- und ggf. Fusion-View-Fenster).

Rückgabewert: void

.setPlacement(placement)

Legt fest, in welchem Fenster (Bot- oder Fusion-View) Overlays angezeigt werden.

Parameter	Typ	Beschreibung
placement	'botview' | 'fusionview' | z.input<typeof overlayPlacementSchema>	Zielfenster, oder ein Objekt gemäß overlayPlacementSchema.

Objekt-Form (validiert über overlayPlacementSchema):

Feld	Typ	Pflicht	Beschreibung
placement	string	✔	Fenster, in dem Overlays angezeigt werden.

Rückgabewert: void

.text(text, onClose?)

Zeigt ein Text-Overlay an.

Parameter	Typ	Beschreibung
text	string | z.input<typeof overlayTextSchema>	Der anzuzeigende Text, oder ein Objekt gemäß overlayTextSchema.
onClose	() => void	Callback, der beim Schließen des Overlays aufgerufen wird.

Objekt-Form (validiert über overlayTextSchema):

Feld	Typ	Pflicht	Beschreibung
text	string	✔	Der im Overlay anzuzeigende Text.

Rückgabewert: void

.textAndButton(text, buttons, onClose?, cssClass?)

Zeigt ein Overlay mit Text und Buttons an.

Parameter	Typ	Beschreibung
text	string	Der anzuzeigende Text.
buttons	{ text: string, onClick: () => void, className?: string }[]	Die anzuzeigenden Buttons.
onClose	() => void	Callback, der beim Schließen des Overlays aufgerufen wird.
cssClass	string	Optionale CSS-Klasse für das Overlay.

Rückgabewert: void

.prompt(text?, buttons?, onClose?, cssClass?)

Zeigt ein Overlay mit Texteingabefeld und Buttons an.

Parameter	Typ	Beschreibung
text	string	Der anzuzeigende Hinweistext.
buttons	{ text: string, onClick: () => void, className?: string }[]	Die anzuzeigenden Buttons.
onClose	() => void	Callback, der beim Schließen des Overlays aufgerufen wird.
cssClass	string	Optionale CSS-Klasse für das Overlay.

Rückgabewert: void

.loading(text?, cssClass?)

Zeigt ein Lade-Overlay mit Spinner an.

Parameter	Typ	Beschreibung
text	string | z.input<typeof overlayTextSchema>	Der anzuzeigende Ladetext, oder ein Objekt gemäß overlayTextSchema.
cssClass	string	Optionale CSS-Klasse für das Overlay.

Objekt-Form (validiert über overlayTextSchema):

Feld	Typ	Pflicht	Beschreibung
text	string	✔	Der im Overlay anzuzeigende Text.

Rückgabewert: void

.promptArea(text?, buttons?, onClose?, cssClass?)

Zeigt ein Overlay mit mehrzeiligem Texteingabefeld (Textarea) und Buttons an.

Parameter	Typ	Beschreibung
text	string	Der anzuzeigende Hinweistext.
buttons	{ text: string, onClick: () => void, className?: string }[]	Die anzuzeigenden Buttons.
onClose	() => void	Callback, der beim Schließen des Overlays aufgerufen wird.
cssClass	string	Optionale CSS-Klasse für das Overlay.

Rückgabewert: void

.prompt_getInput()

Gibt das Eingabefeld eines aktuell offenen prompt()-Overlays zurück.

Rückgabewert: HTMLInputElement | null

Das Eingabefeld-Element, oder null.

.fileUpload_getTextArea()

Gibt das Textarea-Element eines aktuell offenen promptArea()-Overlays zurück.

Rückgabewert: HTMLInputElement | null

Das Textarea-Element, oder null.

.fileUpload_getValue()

Gibt den aktuellen Wert des promptArea()-Textarea-Elements zurück.

Rückgabewert: string

Der eingegebene Text, oder ein leerer String.

.prompt_getInputValue()

Gibt den aktuellen Wert des prompt()-Eingabefelds zurück.

Rückgabewert: string

Der eingegebene Text, oder ein leerer String.

.button(buttons, onClose?, cssClass?)

Zeigt ein Overlay ausschließlich mit Buttons an (ohne Text).

Parameter	Typ	Beschreibung
buttons	{ text: string, onClick: () => void, className?: string }[]	Die anzuzeigenden Buttons.
onClose	() => void	Callback, der beim Schließen des Overlays aufgerufen wird.
cssClass	string	Optionale CSS-Klasse für das Overlay.

Rückgabewert: void

.html(html, onClose?, cssClass?)

Zeigt ein HTML-Overlay an.

Parameter	Typ	Beschreibung
html	string | z.input<typeof overlayHtmlSchema>	Der anzuzeigende HTML-Inhalt, oder ein Objekt gemäß overlayHtmlSchema.
onClose	() => void	Callback, der beim Schließen des Overlays aufgerufen wird.
cssClass	string	Optionale CSS-Klasse für das Overlay.

Objekt-Form (validiert über overlayHtmlSchema):

Feld	Typ	Pflicht	Beschreibung
html	string	✔	Der im Overlay anzuzeigende HTML-Inhalt.

Rückgabewert: void

.stageChangeDialog(text?)

Zeigt ein Overlay mit Buttons zum Wechseln in eine andere sichtbare Stage.

Parameter	Typ	Beschreibung
text	string	Optionaler Hinweistext.

Rückgabewert: void

.uploadImage(title?, instruction?, onImageLoaded?, onClose?)

Zeigt ein Overlay zum Hochladen eines Bildes per Drag-and-Drop an.

Parameter	Typ	Beschreibung
title	string	Titel des Overlays.
instruction	string	Hinweistext in der Drop-Zone.
onImageLoaded	(fileContent: string, fileName?: string, fileType?: string) => void	Callback mit dem Bildinhalt (Data-URL), sobald ein Bild geladen wurde.
onClose	() => void	Callback beim Schließen des Overlays.

Rückgabewert: void

.uploadFile(title?, instruction?, onTextLoaded?, onClose?)

Zeigt ein Overlay zum Hochladen einer Textdatei per Drag-and-Drop an.

Parameter	Typ	Beschreibung
title	string	Titel des Overlays.
instruction	string	Hinweistext in der Drop-Zone.
onTextLoaded	(fileContent: string, fileName?: string, fileType?: string) => void	Callback mit dem Dateiinhalt, sobald eine Datei geladen wurde.
onClose	() => void	Callback beim Schließen des Overlays.

Rückgabewert: void

.stageList(text?, cssClass?)

Zeigt ein Overlay mit Buttons zu allen sichtbaren Stages an.

Parameter	Typ	Beschreibung
text	string	Optionaler Hinweistext.
cssClass	string	Optionale CSS-Klasse für das Overlay.

Rückgabewert: void