Widget, Konfiguration und Vorschau

defineWidget baut die Widget-Definition, die im Manifest unter widgets steht: Konfigurationsschema, Größen und die Vorschau-Daten, aus denen Katalog, Miniaturen und die Vorlagen des Editors entstehen. Die Tabellen nennen jedes Feld; das Uhr-Beispiel zeigt sie im Zusammenhang.

Die Felder der Widget-Definition#

Jedes Feld der Konfiguration trägt eine Vorgabe, damit eine leere Konfiguration vollständig parst und der Editor ohne Vorbefüllung rendert. Ein Widget-Resolver im Server-Teil parst ctx.config mit demselben Schema erneut; das Schema liegt damit auf beiden Seiten.

Feldtexte und Beispiele#

defineWidget übersetzt das Zod-Schema beim Laden des Manifests einmal in ein JSON-Schema-Dokument nach Draft 2020-12 — das ist es, was GET /v1/widget-catalog ausliefert und was ein fremder Client gegen seine Konfiguration prüft. Zwei Dinge steuern Sie dabei bewusst:

Die Feldtexte. JSON-Schema kennt je Feld zwei Texte — title als kurze Überschrift, description als Satz dazu —, Zod kennt nur einen. Beide stehen deshalb in EINEM .describe(), getrennt durch einen senkrechten Strich:

timezone: z
  .string()
  .max(64)
  .default('')
  .describe('Zeitzone|IANA-Zeitzone wie „Europe/Berlin". Leer heißt: die Zeitzone der Organisation.'),

Ohne Strich wird der ganze Text zur description, und das Feld bekommt keine Überschrift. Ein Feld ohne .describe() steht ohne Erklärung im Katalog — für jeden, der ohne den Editor arbeitet, ist es dann so gut wie unbeschriftet.

Die Beispiele. examples füllt das SDK selbst: die preview.defaultConfig und je Vorschau-Variante dieselbe Konfiguration mit der Teil-Konfiguration der Variante darüber. Jedes Beispiel wird gegen das Zod-Schema geprüft — bricht eines die eigene Regel, schlägt der Bau der App fehl und nennt das Feld. Ein Widget ohne preview.defaultConfig fällt auf preview.mockData zurück; hat es beides nicht, lässt es sich nicht bauen.

Was das Dokument am Ende sagt, steht unter Widgets konfigurieren.

Vorschau-Varianten#

preview.variants ist die einzige Quelle dafür, was eine App zeigen kann: Die Store-Galerie rendert daraus ihre Ansichten, der Bildgenerator leitet daraus ab, welche Miniaturen er aufnimmt, und der Editor bietet die Varianten mit Größe als Vorlagen an. Eine Layout-Option, die hier nicht steht, gibt es im Store nicht.

Größen an Varianten#

Jede Variante bekommt eine size, die zu ihrem Zweck passt: eine Uhr als Kachel (600 × 300), ein Nachrichtenband als Leiste (1920 × 120), ein Aushang hochkant (600 × 800), eine Kartenansicht breit (1280 × 720). Die Größe ist der Rahmen, mit dem ein Klick die Vorlage in eine 1920 × 1080-Szene setzt. Auf einer anderen Bühne rechnet der Editor sie über die kurze Seite um. Eine Variante für stehende Displays bekommt eine hohe Größe statt aspect: '9:16', die Lage folgt ihr. Höher als 1080 Bezugspixel ist keine Vorlage, ein Hochkant-Rahmen ist also eine Spalte in der Szene und kein ganzer Bildschirm.

Die Miniatur einer Variante mit Größe zeigt das Widget 1 : 1 in diesem Rahmen, mittig auf einer ruhigen hellen Fläche, mit Name und Maß darunter. Das Bild bleibt 1920 × 1080, bei hoher Größe 1080 × 1920. Eine Variante ohne Größe füllt die Bühne ihrer Lage.

Die Passt-Prüfung rendert jede Variante jeder App in ihrem Rahmen und schlägt fehl, wenn dort etwas übersteht, ein Text angeschnitten oder zu klein ist oder das Widget über den Passt-Bericht einen eingeschalteten Inhalt ausblendet. Sie läuft als Gate im Pull Request und lokal so:

pnpm --filter @szenera-app/<id> build
pnpm app:fit-check --only=<id>                       # jede Variante, jede Randgröße, jeder Zustand
pnpm app:fit-check --try=<id>:<variante>@600x300     # eine Größe messen, bevor sie im Manifest steht

Gemessen wird die Tinte eines Textes, nicht sein Zeilenkasten. Die Regeln im Einzelnen:

Ein Widget mit size.min steht im neuen Standard und bekommt dazu den Randgrößen-Satz: die Mindestgröße selbst, je Form den kleinsten Rahmen, den size.min erlaubt, und den größten in der Bezugsszene, Leiste und Spalte im äußersten Seitenverhältnis (volle Breite in Mindesthöhe, volle Höhe in Mindestbreite). Gerendert wird mit der Vorgabe-Config, die alles einschaltet. Dort darf das Widget ausblenden, nur abschneiden und zu kleine Schrift darf es nicht. Die Fehler aller Berichte steckten an diesen Rändern, nicht in den Vorlagen.

Läuft ein Inhalt absichtlich durch seinen Kasten und bewegt ihn ein Skript statt einer CSS-Animation, trägt das bewegte Element oder sein Kasten data-fit-scroll (das Laufband setzt es selbst). Eine Schicht, die nur zum Messen gezeichnet wird, trägt data-fit-measure und zählt nicht. Die Bilder eines Rahmens mit Befund liegen danach unter scratchpad/fit-check/. Schneidet eine App, die noch nicht im neuen Standard steht, in jeder vernünftigen Größe ab, gehört der Rahmen mit einem Satz Grund („eigene Welle“) in die Ausnahmeliste tools/app-screenshots/fit-exceptions.mjs. Dort bleibt er im Bericht sichtbar, und passt er eines Tages, wird die Prüfung rot, bis der Eintrag verschwindet. Eine App im neuen Standard trägt keine Ausnahme.

Vorschau-Zustände#

preview.states zeigt im Einstellungs-Fenster, wie das Widget in einer bestimmten Lage aussieht, ohne dass sie gerade eintritt: Regen, Nacht, keine Daten, veraltet. Der Editor bietet die Zustände als Umschalter neben „Echte Daten“ an.

Ein Schema der Nutzlast gibt es nicht. defineWidget prüft deshalb die Form: reine JSON-Daten (keine Funktion, kein Datum, keine Zahl ohne Wert) und dieselbe Art wie preview.mockData (Objekt, Liste oder Einzelwert). Übersetzt wird die Beschriftung unter translations.<sprache>.widgets.<widget>.states.<zustand>.label, wie die einer Variante.

Der Zustand empty ist Pflicht für jedes Widget mit Quelle (noResolver: false), pnpm app:check verlangt ihn in der Zeile „Zustände“. Er zeigt das Widget ohne Daten, bei einem Daten-Widget mit mockData: null (keine Nutzlast, wie vor dem ersten Abruf oder nach einem gescheiterten). Apps, die ihren leeren Zustand erst in ihrer eigenen Welle neu zeichnen, stehen bis dahin in tools/app-kit/src/check/state-exceptions.ts.

Nie Editor-Text am Display. Leer, gestört oder unkonfiguriert heißt am Display eine ruhige Fläche und höchstens ein neutraler Satz, die Erklärung mit dem nächsten Schritt steht im Editor (useWidgetMode(), der Baustein QuietState trennt beides). Die Passt-Prüfung rendert deshalb jeden Zustand im Anzeige-Modus, so wie ein Display ihn zeigt: im Rahmen der primary-Vorlage, die ruhigen Zustände empty und error in jeder Vorlage. Ein Satz an den Bearbeiter oder mehr als zwölf Wörter in einem ruhigen Zustand sind dort ein Befund.

Vorlagen im Editor#

Eine Variante mit size ist im Szenen-Editor eine Vorlage. Ihr Inhalt ist preview.defaultConfig mit der Teil-Konfiguration der Variante flach darüber ({ ...defaultConfig, ...variant.config }), genau wie im Bildgenerator. Was der Store zeigt, fügt der Editor deshalb so ein.

Drei Regeln, die eine App beim Entwerfen ihrer Vorlagen kennen sollte:

• Die Startgröße steht im Bezug 1920 × 1080. Auf einer anderen Bühne rechnet der Editor sie über die kurze Seite um (eine 4K-Szene bekommt das Doppelte) und begrenzt sie, ohne das Seitenverhältnis zu verlieren, auf die Bühne.
• Der Inhalt einer Vorlage sind die Schlüssel ihrer Teil-Konfiguration. Wechselt der Kunde die Vorlage, gehen alle Schlüssel, die irgendeine Vorlage setzt, auf die Vorgabe zurück, darüber kommt die neue Teil-Konfiguration. Was keine Vorlage setzt (ein gewählter Ort, die Fläche), bleibt. Vorlagen, die sich nur in der Größe unterscheiden, dürfen denselben Inhalt tragen.
• Welche Vorlage ein Widget trägt, erkennt der Editor aus Rahmen und Inhalt. Die Instanz merkt sich ihre Vorlage nicht. Zuerst zählt die Form des Rahmens, darunter die Vorlage, deren Inhalt die Config unverändert trägt, sonst die mit dem nächsten Seitenverhältnis.

size.min begrenzt die Griffe auf der Bühne: Kleiner als die Mindestgröße (über die kurze Seite auf die Bühne gerechnet) lässt sich das Widget nicht ziehen. Beim Größenändern zeigt der Editor Form und Maße des Rahmens („Hochkant · 440 × 780“), die Umschalttaste sperrt das Seitenverhältnis.

Ein Widget je App, Vorlagen statt zweiter Widgets#

Keine App trägt zwei Widgets. Die App ist die Einheit, die eine Organisation installiert und wieder entfernt — ein Bündel unverwandter Widgets ließe sich nicht bewerten. Was mehrere Darstellungen braucht, löst das über die Vorschau-Varianten und ein Konfigurationsfeld:

• Eine Variante mit size ist eine Vorlage. Sie legt die Startgröße des Rahmens fest und mit ihrer Teil-Konfiguration den Inhalt, den der Kunde beim Einfügen bekommt.
• Wie der Inhalt innerhalb des Rahmens aussieht, entscheiden Rahmen und Konfiguration — die Form des Rahmens liest das Widget über useWidgetFormat(), die Wahl des Kunden steht in einem Konfigurationsfeld wie composition bei der Uhr.

Ein Widget mit noResolver: false wird auch ohne Player aufgelöst, etwa für die Vorschau im Editor; der Resolver bekommt dann playerId: null und muss diesen Fall verkraften.

Formate: wie ein Widget seinen Rahmen nutzt#

Ein Widget steht in einer Szene selten bildschirmfüllend, oft klein, hochkant oder als Leiste. Es ordnet sich deshalb nach dem Rahmen, den die Szene ihm gibt, und zwar nach einer Rechnung für alle Apps. Die Hooks stehen in @szenera/widget-foundation/hooks:

Die Form folgt dem Seitenverhältnis Breite : Höhe:

Beim Ziehen der Griffe im Editor wechselt die Form erst, wenn das Verhältnis 4 % hinter der Schwelle liegt. So springt ein Widget nicht bei jeder Zeigerbewegung zwischen zwei Anordnungen.

Die Größe misst die kurze Seite des Rahmens in Bezugspixeln einer Bühne mit kurzer Seite 1080: kurze Seite × 1080 / kurze Seite der Bühne. Unter 400 Bezugspixeln ist der Rahmen compact, sonst regular. Eine 4K-Szene hat doppelt so viele Pixel, ihr Widget ist deshalb nicht größer: 600 Pixel auf einer 2160 hohen Bühne sind 300 Bezugspixel. Wer feiner stufen will, übergibt eigene Stufen, etwa useWidgetFormat({ sizes: [{ size: 'tiny', from: 0 }, { size: 'small', from: 200 }, { size: 'large', from: 600 }] }). Eigene Schwellen (thresholds) gehen auch, sind aber die Ausnahme: Dieselbe Rahmengröße soll in jeder App dasselbe heißen.

Der Passt-Bericht. Blendet ein Widget einen eingeschalteten Inhalt aus, weil der Rahmen zu klein ist, meldet es die Teile mit den Schlüsseln der Config-Felder, die sie einschalten, bei jeder Anordnung die vollständige Liste und eine leere, sobald alles zu sehen ist:

const { shape, size } = useWidgetFormat();
const { reportHidden } = useFitReport();
const drawsDaily = config.showDaily && size === 'regular' && shape !== 'band';
useEffect(() => {
  reportHidden(config.showDaily && !drawsDaily ? ['showDaily'] : []);
}, [reportHidden, config.showDaily, drawsDaily]);

Der Editor zeigt daraus unter der Vorschau „In diesem Rahmen ausgeblendet: Nächste Tage.“ mit der Beschriftung des Felds aus der Formular-Beschreibung und unter dem Schalter einen Satz, warum er gerade nichts bewirkt. Ein Teil ohne passendes Feld erscheint mit seinem Schlüssel. Die Passt-Prüfung lässt eine Vorlage scheitern, die in ihrer eigenen Größe etwas ausblendet. Auf dem Display und in Miniaturen bleibt die Meldung ohne Wirkung; ein Widget meldet deshalb immer, ohne zu fragen, wo es läuft. Den Bericht sammelt der SceneRenderer im Modus editor und gibt ihn über onFitReport(widgetInstanceId, hiddenParts) an den Host.

Dieselbe Rechnung ohne React steht als classifyWidgetFormat({ width, height }, { canvas, previous?, thresholds?, sizes? }) in @szenera/widget-foundation/widget-ui/tokens, für Aufnahme-Werkzeug, Tests und Server. useElementSize bleibt für innere Bereiche, deren Maße erst das Layout ergibt.

Anzeige-Bausteine#

Was mehrere Apps brauchen, steht einmal in @szenera/widget-foundation/widget-ui. Die Bausteine tragen keinen eigenen Stil, sie nehmen Fläche, Schrift und Maße der App. Sie kamen mit der Fassung 1.2.0 des Host-Vertrags in die Anzeige, eine App, die einen davon nutzt, verlangt deshalb ^1.2.0 (siehe Host-Vertrag und Freigabe).

Die zwei Bündel#

Der Renderer lädt das runtime-Bündel vom Gerät und lässt es seine Widgets in die Registry eintragen; scheitert der Import, meldet er widget.bundle.load-failed, statt die Szene abzubrechen. Das authoring-Bündel lädt der Szenen-Editor des Portals.

Beispiel: die Uhr (gekürzt)#

import { defineWidget } from '@szenera/apps-sdk/widget';
import { type ClockConfig, ClockConfigSchema } from './config';

const DEFAULT_CONFIG: ClockConfig = {
  variant: 'digital',
  composition: 'stapel',
  timeFormat: 'HH:mm',
  showDate: true,
  timezone: '',
  theme: 'redaktion',
  accentColor: '#0f766e',
  // … weitere Felder, jedes mit Vorgabe im Schema …
};

export const clockWidget = defineWidget({
  id: 'clock',
  appId: 'clock',
  name: 'Uhrzeit',
  description: 'Digitale Uhr oder analoges Zifferblatt, mit optionalem Datum und eigener Zeitzone.',
  configSchema: ClockConfigSchema,
  noResolver: true,
  preview: {
    thumbnailUrl: '/apps/clock/thumbnails/clock.png',
    defaultConfig: DEFAULT_CONFIG,
    mockData: DEFAULT_CONFIG,
    variants: [
      { id: 'digital', size: { w: 600, h: 300 }, label: 'Digital', description: 'Große Ziffern, die sich der Fläche anpassen, darunter wahlweise das Datum.', primary: true },
      { id: 'band', size: { w: 480, h: 300 }, label: 'Band', config: { composition: 'band', theme: 'kachel', dateWeekday: 'short' } },
      { id: 'analog', size: { w: 560, h: 480 }, label: 'Analog', config: { variant: 'analog', theme: 'kachel', dialNumerals: 'quarters' } },
      { id: 'hochkant', size: { w: 440, h: 720 }, label: 'Hochkant', description: 'Dieselbe Uhr auf einem stehenden Display.' },
    ],
  },
});

Das Konfigurationsschema dazu ist ein Zod-Objekt, in dem jedes Feld eine Vorgabe und einen Text trägt — etwa variant: z.enum(['digital', 'analog']).default('digital').describe('Variante|„digital" ist die Zahlen-Uhr, „analog" ein gezeichnetes Zifferblatt.'). Unbekannte Schlüssel verwirft das Schema still, damit ältere gespeicherte Szenen weiter parsen.

Weiterführendes#

• Das Manifest — wo die Widget-Definition eingetragen wird.
• Server-Teil: Resolver, Fetcher und Jobs — der Resolver, den noResolver: false verlangt.
• Die Beispiel-Apps — Kategorie, Klasse und Bedingungen jeder App.
• Signieren und der Weg in den Katalog — wie die fertige Definition über GET /v1/widget-catalog wieder herauskommt.
• Widgets konfigurieren — wie ein Client das erzeugte Schema liest und seine Konfiguration dagegen prüft.