Apps bauen, nicht Desktop-Rahmen.

Installation

AirWorks besteht aus einem ES-Modul (airworks.js), einem Stylesheet (airworks.css) und dem Ordner icons/. Drei Wege, dieselbe API.

npm install github:fgilde/AirWorks

<link rel="stylesheet"
  href="https://fgilde.github.io/AirWorks/lib/airworks.css">
<script type="module">
  import { AirWorks } from
    "https://fgilde.github.io/AirWorks/lib/airworks.js";
</script>

C · Repository auschecken

git clone https://github.com/fgilde/AirWorks.git
cd AirWorks/src/airworks
npm install
npm run dev            # Doku auf http://127.0.0.1:4173, Demo unter /webtop.html
npm run build:package  # schreibt ../../package (airworks.js, airworks.css, icons, types)

Schnellstart

<air-desktop></air-desktop>
<script type="module">
  import { AirWorks } from "@fgilde/airworks";
  import "@fgilde/airworks/style.css";

  AirWorks.configure({
    brand: { title: "Contoso Desk", logo: "/img/logo.png" },
    initialShortcuts: ["hello"],
    initialApps: ["hello"],
  });
  AirWorks.registerApp({
    id: "hello",
    title: "Hallo",
    icon: "fn-dashboard.png",          // Datei im Icon-Ordner oder beliebige URL
    accent: "#00a4a6",
    width: 640, height: 420,
    render: () => "<h1>Hallo AirWorks</h1>",
  });
</script>

<air-desktop> initialisiert sich in einem Microtask; configure() und Registrierungen im selben Modul laufen also immer vorher. Ist dein Setup asynchron (z. B. await auf einen Konfigurations-Endpunkt), füge das Element danach ein: document.body.append(document.createElement("air-desktop")). Apps, Rechte und Provider lassen sich jederzeit registrieren; der Desktop aktualisiert sich sofort.

Optionen

AirWorks.configure(options) führt Optionen zusammen und darf mehrfach aufgerufen werden. assetBase, storageKey, initialApps und initialShortcuts werden beim Initialisieren des Desktops gelesen.

Apps registrieren

Eine App ist ein einfaches Objekt. Sie braucht id, title, icon und genau eine Inhaltsquelle: render, url oder entry.

AirWorks.registerApp({
  id: "orders",
  title: "Aufträge",
  icon: "fn-reporttable.png",
  accent: "#35496b",               // Farbe von Fenster, Kachel und Taskleiste
  width: 900, height: 600,
  requiredPermissions: ["orders.read"],
  hidden: false,                   // true: nicht in Startmenü/Suche, per API weiterhin öffenbar
  async render({ host, request, can, onClose, setTitle, session, access }) {
    host.innerHTML = "Lädt …";
    const orders = await request("/orders");
    host.innerHTML = renderTable(orders);
    const timer = setInterval(refresh, 30_000);
    onClose(() => clearInterval(timer));     // Aufräumen beim Schließen
  },
});

Jedes Fenster hat die Menüaktionen Verknüpfung erstellen/aktualisieren, Duplizieren und Im Browser öffnen (ein Pop-out, das nur diese App über ?app=<id> zeigt). Eigene Einträge ergänzt eine App mit menu: [{ id, title, icon, run(context) }]. Apps lassen sich beliebig oft öffnen; singleInstance: true erlaubt nur ein Fenster (beim nächsten Öffnen wird es fokussiert, ohne Duplizieren), wie bei den eingebauten Einstellungen. Im Pop-out (Im Browser öffnen) füllt das Fenster den Browser-Tab, ohne Verschieben, Größenänderung oder Fensterknöpfe; das Menü behält Verknüpfung aktualisieren und Im Browser öffnen für ein weiteres Pop-out. Eingebaute Apps: airworks.settings, airworks.identity, airworks.weblink und airworks.docs. AirWorks.unregisterApp(id) entfernt eine App.

Verknüpfungen merken sich die Stelle in der App

Eine App meldet ihre aktuelle Position mit setState, z. B. den gewählten Bericht oder die Kennzahl, samt Titel. Verknüpfung erstellen schlägt diesen Titel vor und speichert den Zustand, Verknüpfung aktualisieren übernimmt den neuen Zustand, und Duplizieren, Im Browser öffnen sowie wiederhergestellte Fenster öffnen genau dort. Der Zustand kommt wie bei Suchtreffern als intent an.

render: ({ host, intent, onIntent, setState }) => {
  const show = (ratio) => { draw(ratio); setState({ ratio }, titleOf(ratio)); };
  onIntent((next) => show(next.ratio));
  show(intent?.ratio ?? "cash-ratio");
}

Web-Verknüpfungen

Die App Web-Verknüpfung macht aus jeder Webseite eine App: Name, Webadresse, Farbe und Icon (hochgeladenes Bild oder das Favicon der Seite). Sie legt eine Verknüpfung an und zeigt die Seite in einem Fenster; Web-Verknüpfung bearbeiten im Fenstermenü ändert sie später. Seiten, die das Einbetten verbieten (X-Frame-Options), bleiben leer; das Fenster bietet an, sie im Browser zu öffnen. Abschalten mit webLinks: false.

Mit einem Framework

// React
render: ({ host, onClose }) => {
  const root = createRoot(host);
  root.render(<Orders />);
  onClose(() => root.unmount());
}

Globale Suche

Die Suche in der Taskleiste findet Apps und Inhalte. Apps liefern Inhalte über search; alles andere (typischerweise dein Server) registriert einen Suchanbieter. Treffer öffnen ihre App mit einem Intent, der beschreibt, was gezeigt werden soll.

AirWorks.registerApp({
  id: "orders", title: "Aufträge", icon: "fn-reporttable.png",
  search: (query) => orders
    .filter((order) => order.customer.toLowerCase().includes(query))
    .map((order) => ({ title: order.number, description: order.customer, intent: { order: order.id } })),
  render: ({ host, intent, onIntent }) => {
    show(intent?.order);                         // aus einem Suchtreffer geöffnet
    onIntent((next) => show(next.order));        // Fenster schon offen, neuer Treffer gewählt
  },
});

AirWorks.registerSearchProvider({
  id: "server",
  search: (query, { request, signal }) => request(`/search?q=${encodeURIComponent(query)}`, { signal }),
});                                              // liefert [{ title, description?, icon?, appId, intent? }]

AirWorks.openApp("orders", { order: "4711" });   // derselbe Intent aus Code

Die Suche startet ab zwei Zeichen, wartet 200 ms nach der Eingabe und bricht veraltete Anfragen über signal ab. Treffer zu Apps ohne Berechtigung werden verworfen. Die Kennzahlen der Demo und die Serversuche des Aspire-Beispiels (Berichte, Benutzer) nutzen das.

Micro-Frontends

Teams liefern Apps unabhängig aus. AirWorks.loadRemote(url) lädt ein JSON-Manifest; relative Pfade in entry, url und icon werden gegen die Manifest-URL aufgelöst. Apps mit entry laden erst beim ersten Öffnen.

// https://team-a.example.com/airworks/manifest.json
{
  "permissions": [{ "id": "remote.hello", "title": "Hallo nutzen", "group": "Team A" }],
  "apps": [
    { "id": "remote-hello", "title": "Remote Hallo", "icon": "fn-ideaportal.png",
      "entry": "./hello.js", "requiredPermissions": ["remote.hello"] },
    { "id": "billing", "title": "Abrechnung", "icon": "./billing.png", "url": "./billing/index.html" }
  ],
  "modules": ["./register-more.js"]   // Module, die selbst AirWorks.* aufrufen
}

// hello.js
export default function render({ host, access, onClose }) {
  return `<h2>Hallo ${access.identity?.displayName ?? "Gast"}</h2>`;
}

await AirWorks.loadRemote("https://team-a.example.com/airworks/manifest.json");
await AirWorks.loadRemote({ apps: [/* Manifest inline */] });

Die Client-only-Demo lädt remote/manifest.json genau so. Module von fremden Origins brauchen CORS-Header. Ein Manifest kann auch pro Benutzer vom Server erzeugt werden.

Webtops, Ordner und Drag-and-drop

Webtops (bis zu 9) und Ordner sind dasselbe: seitenweise Raster. Webtops haben 5 × 3 Zellen, Ordner 4 × 3 und beliebig viele Seiten. Alle Regeln gelten für beide:

• Freie Zelle – das Icon wandert dorthin, auch seitenübergreifend.
• App auf App (Webtop) – erzeugt in dieser Zelle einen Ordner.
• App auf Ordner – ca. 0,65 s verweilen und der Ordner öffnet sich, dann auf eine genaue Zelle ablegen; sofortiges Ablegen nutzt die erste freie Zelle.
• Zwischen Verknüpfungen – auf den Rand einer belegten Zelle ziehen, die folgenden Verknüpfungen rücken (beim Ziehen animiert) zur Seite; nur die Mitte einer Kachel bildet oder füllt einen Ordner.
• Am Rand verweilen – wechselt zur vorherigen/nächsten Seite, solange du dort bleibst, immer weiter; hinter der letzten Seite entsteht eine neue (bleibt sie leer, verschwindet sie wieder).
• Aus dem Ordner ziehen – den Ordner mit dem Zeiger verlassen, er schließt sich, auf dem Webtop ablegen. Bleibt nur eine App übrig, löst sich der Ordner auf und die App nimmt seinen Platz ein.
• Papierkorb – beim Ziehen einer vorhandenen Verknüpfung oder eines Ordners erscheint unten ein Papierkorb. Darauf ablegen löscht; ein Ordner wird samt Inhalt gelöscht. Fenster, die mit der Verknüpfung verbunden waren, laufen weiter.
• Apps aus dem Startmenü auf jeden Webtop oder Ordner ziehen. Umbenennen per Doppelklick unter die Kachel oder F2. Fenster wachsen aus der Verknüpfung, aus der sie geöffnet wurden, und schrumpfen beim Schließen dorthin zurück; Verknüpfung aktualisieren lässt Verknüpfung und Fenster gemeinsam aufleuchten.

Drag-and-drop arbeitet mit Pointer-Events und einem schwebenden Abbild (Maus, Stift und Touch); während des Ziehens wird nichts neu gerendert. Fenster weichen beim Ziehen zur Seite. Fenster lassen sich an allen Kanten und Ecken in der Größe ändern und andocken: nach oben ziehen maximiert, an linken/rechten/unteren Rand für Hälften, in eine Ecke für Viertel; Strg+Pfeile wechseln zwischen diesen Positionen (zweimal oben = obere Hälfte, zweimal unten = minimieren). Außerdem:, Taskleiste an jeder Seite mit Auto-Hide, Vorschauen, Suche, Pilotansicht (alle Fenster und Webtops; Webtops hinzufügen/löschen), Hintergründe, eigene Systemfarbe und Effekte (springende Logos, Schnee, Sternenfeld, Warp, Netzwerk, Polarlicht). Verknüpfungen auf Apps ohne Berechtigung behalten ihren Platz, werden aber ausgeblendet.

Anmeldung

Ohne Auth-Provider läuft AirWorks ganz ohne Anmeldung. Sobald ein oder mehrere Provider registriert sind, startet der Desktop im Anmeldebildschirm: Die Karte listet alle Provider, schüttelt sich bei einem Fehlversuch und schrumpft nach der Anmeldung in den Startknopf. Abmelden führt zurück zum Anmeldebildschirm. Mit requireLogin: false bleibt der Desktop für Gäste nutzbar und die Anmeldung wird über das Startmenü angeboten.

Echte Anmeldung mit Server (empfohlen)

1. Einen Identity Provider betreiben (Keycloak, Entra ID, Auth0 …) und einen Public Client mit der Seiten-URL als Redirect-URI und ihrem Origin als Web-Origin anlegen.
2. Den Provider im Browser mit createOidcProvider registrieren (siehe unten). Die Anmeldung findet beim Identity Provider statt; AirWorks erhält die Tokens per PKCE.
3. Die API prüft das Access-Token (JWT-Bearer) und entscheidet, was der Benutzer darf. AirWorks.request sendet das Token automatisch mit.
4. Die API liefert die wirksamen Rollen und Rechte (GET /me); dieser Endpunkt wird als accessProvider eingebunden. Dieselben Rechte an jedem Endpunkt erzwingen.
5. Optional Benutzer, Rollen und Profile auf dem Server ablegen: identityStore: httpIdentityStore(…), profileStore: httpProfileStore(…).

AirWorks.configure({
  serverBaseUrl: "/api",
  accessProvider: () => AirWorks.request("/me"),
  identityStore: httpIdentityStore(AirWorks.request, "/identity"),
  profileStore: httpProfileStore(AirWorks.request, "/profile"),
});
AirWorks.registerAuthProvider(createOidcProvider({ id: "keycloak", title: "Keycloak", authority, clientId: "airworks-web" }));
document.body.append(document.createElement("air-desktop"));

Das .NET-Aspire-Beispiel setzt genau das um, inklusive API.

OpenID Connect (Keycloak, Entra ID, Auth0, Okta, Zitadel …)

import { AirWorks, createOidcProvider } from "@fgilde/airworks";

AirWorks.registerAuthProvider(createOidcProvider({
  id: "keycloak",
  title: "Keycloak",
  authority: "https://sso.example.com/realms/airworks",
  clientId: "airworks-web",               // Public Client, PKCE S256
  // scope: "openid profile email",       // Standard
  // redirectUri: location.origin + location.pathname,
  // extraParams: { kc_idp_hint: "github" },
  // roleClaims: ["realm_access.roles", "roles", "groups"],
}));

AirWorks.registerAuthProvider(createOidcProvider({
  id: "entra", title: "Microsoft",
  authority: "https://login.microsoftonline.com/<tenant>/v2.0",
  clientId: "<spa-client-id>",
  scope: "openid profile email api://<api-client-id>/access",
}));

createOidcProvider implementiert den Authorization-Code-Flow mit PKCE ohne Abhängigkeiten: Discovery, Redirect, Code-Tausch, Erneuerung per Refresh-Token und RP-initiierter Logout. Registriere die Seiten-URL als Redirect-URI und ihren Origin als erlaubten Web-Origin (CORS) beim Identity Provider. Tokens liegen im sessionStorage. Rollen kommen aus roleClaims; mapSession(claims, tokens) passt die Session an.

Nur Client: lokale Benutzer (Demos)

import { localAuthProvider, localIdentityStore } from "@fgilde/airworks";
const identity = localIdentityStore({ users: [...], roles: [...] });
AirWorks.registerAuthProvider(localAuthProvider(identity, { title: "Demo-Benutzer" }));

Ein Benutzerwechsler für Demos und Prototypen: Der Anmeldebildschirm fragt nur den Benutzernamen ab, Rollen kommen aus dem lokalen Identity-Store. Alles liegt im Browser und lässt sich in den Entwicklerwerkzeugen ändern. Zum Ausprobieren der Oberfläche gedacht, niemals zum Schutz von Daten. Die Live-Demo arbeitet so (Benutzer demo und admin).

Eigener Provider oder eigener Ablauf

AirWorks.registerAuthProvider({
  id: "company", title: "Firmen-Login",
  fields: [{ name: "userName", label: "userName" }, { name: "password", label: "Passwort", type: "password" }],
  async login(values) { return await myLogin(values); },  // liefert eine Session
  async restore() { return mySavedSession(); },           // Start, Rückkehr vom Redirect, Erneuerung
  logout(session) { /* … */ },
});
// oder ohne Provider die Session selbst setzen:
await AirWorks.setSession({ token, identity: { id: "jdoe", displayName: "J. Doe" }, roles: ["user"] });

Eine Session ist { token?, identity?, roles?, permissions?, expiresAt? }. Mit expiresAt ruft AirWorks 30 Sekunden vor Ablauf restore() des Providers zur Erneuerung auf.

Benutzerprofile

Webtops, Ordner, Verknüpfungen, Einstellungen und offene Fenster bilden ein Profil. Ohne Anmeldung gibt es ein Profil; mit Anmeldung hat jeder Benutzer sein eigenes (Schlüssel <storageKey>.<Benutzer-ID>), das bei der Anmeldung geladen und automatisch gespeichert wird.

AirWorks.configure({ profileStore: localProfileStore() });

AirWorks.configure({
  profileStore: httpProfileStore(AirWorks.request, "/profile"),
});
// GET /profile?key=…  → Profil-JSON oder 204
// PUT /profile?key=…  ← Profil-JSON

Jedes Objekt mit load(key) und save(key, profile) eignet sich als profileStore.

Rollen & Rechte

Rechte sind Strings. Apps deklarieren requiredPermissions; Apps ohne sind für alle sichtbar. Registriere Rechte, damit Admins sie auswählen können (im Client, auf dem Server oder beides; die Admin-App führt beide Listen zusammen):

AirWorks.registerPermissions([
  { id: "orders.read", title: "Aufträge lesen", group: "Aufträge" },
  { id: "orders.write", title: "Aufträge bearbeiten", group: "Aufträge", description: "Anlegen und ändern" },
]);
AirWorks.can("orders.write");        // auch im App-Kontext verfügbar
AirWorks.access;                     // { identity, roles, permissions }

So werden Rechte nach der Anmeldung ermittelt

1. Mit accessProvider: dessen Ergebnis (typischerweise /me deines Servers). Für echte Sicherheit empfohlen.
2. Sonst: die permissions der Session plus die Rechte ihrer Rollen aus dem identityStore (Rollen der Session plus Rollen des Benutzer-Datensatzes mit gleicher ID bzw. gleichem Benutzernamen).

Nach Änderungen an anderer Stelle AirWorks.refreshAccess() aufrufen; die eingebaute Admin-App tut das selbst. Fenster von Apps, für die das Recht wegfällt, schließen sich.

App „Benutzer & Rollen“

Konfiguriere einen identityStore und gib Administratoren airworks.identity.manage (exportiert als MANAGE_IDENTITY). Die App bearbeitet Benutzer (Rollen) und Rollen (Rechte).

localIdentityStore(seed?, key?)
// localStorage, für Demos

httpIdentityStore(AirWorks.request, "/identity")
GET    /identity/users     PUT/DELETE /identity/users/{id}
GET    /identity/roles     PUT/DELETE /identity/roles/{id}
GET    /identity/permissions

Oder IdentityStore (listUsers, saveUser, deleteUser, listRoles, saveRole, deleteRole, listPermissions) für ein beliebiges Backend implementieren.

Serveranbindung

AirWorks.configure({
  serverBaseUrl: "/api",
  accessProvider: () => AirWorks.request("/me"),   // { identity?, roles, permissions }
});
const orders = await AirWorks.request("/orders");                     // setzt "Authorization: Bearer <token>"
await AirWorks.request("/orders/7", { method: "PUT", body: JSON.stringify(order) });  // JSON-Content-Type wird gesetzt

request wirft bei Nicht-2xx, liefert JSON oder Text und bei 204 undefined. Über die Option request lässt sich ein eigener HTTP-Client nutzen. Serverseitig (ASP.NET Core, aus dem Beispiel):

api.MapGet("/me", (ClaimsPrincipal user, IdentityService identity) => identity.Describe(user));
api.MapGet("/reports", GetReports).RequirePermission("reports.read");
// RequirePermission: Endpoint-Filter, der Rollen des Aufrufers auf Rechte abbildet, sonst 403.

.NET-Aspire-Beispiel

samples/AirWorks.Demo ist ein vollständig abgesichertes Setup: Aspire-AppHost, Keycloak (Realm-Import), eine ASP.NET-Core-API mit JWT-Prüfung und Rechteprüfung sowie ein Web-Host, der den AirWorks-Client (als Paket eingebunden) ausliefert und /api weiterleitet.

Mit QuickRun starten

Mit QuickRun wird das Sample per Klick aus quickrun.yml geklont, gebaut und gestartet. Oder von Hand:

cd samples/AirWorks.Demo
dotnet run --project AirWorks.Demo.AppHost   # Keycloak benötigt Docker

• http://localhost:5177 öffnen und per Keycloak anmelden: demo/demo oder admin/admin (nur lokale Entwicklung).
• Keycloak liefert die Realm-Rollen airworks-user und airworks-admin. Die API bildet Rollen auf Rechte ab (reports.read, reports.export, airworks.identity.manage) und liefert sie über /api/me.
• Als Admin Benutzer & Rollen öffnen: einem Benutzer die Rolle controller geben oder einer Rolle das im Client registrierte Recht notes.use – die App Notes erscheint sofort.
• Anmeldeknöpfe kommen aus AirWorks:Providers in AirWorks.Demo.Web/appsettings.json; dort stehen deaktivierte Beispiele für GitHub (über Keycloak Brokering) und Microsoft Entra ID.
• Webtops, Verknüpfungen, Einstellungen und offene Fenster liegen pro Benutzer auf dem Server (/api/profile) und folgen dem Benutzer in jeden Browser.
• Keycloak läuft auf https://localhost:8080 mit dem ASP.NET-Core-Entwicklungszertifikat (dotnet dev-certs https --trust). Benutzer und Rollenzuordnungen hält das Beispiel im Speicher.

Events

const off = AirWorks.on("login", (session) => console.log(session));
AirWorks.on("logout", () => location.reload());
AirWorks.on("access-changed", ({ roles, permissions }) => {});
AirWorks.on("app-opened", ({ appId, windowId }) => {});
AirWorks.on("access-denied", ({ appId, requiredPermissions }) => {});
off();

Das Desktop-Element löst zusätzlich bubblende DOM-Events aus: airworks:login, airworks:logout, airworks:access-changed, airworks:app-opened, airworks:access-denied.

Sprachen

Die Shell bringt Englisch und Deutsch mit; umgeschaltet wird unter Einstellungen → Allgemein. Texte ergänzen oder überschreiben:

import { addMessages } from "@fgilde/airworks";
addMessages("fr", { close: "Fermer", settings: "Paramètres" });
AirWorks.configure({ locale: "fr" });

Fehlende Schlüssel fallen auf Englisch zurück. App-Titel übersetzt du selbst.

API-Referenz

Bei Einbindung per Script-Tag liegt dasselbe Objekt auf window.AirWorks.

Entwickeln & deployen

src/airworks/src/
  index.ts        öffentliche API      runtime.ts   Apps, Optionen, Remote-Laden
  desktop.ts      <air-desktop>        windows.ts   Fenster, Taskleiste, Andocken
  workspace.ts    Webtops & Ordner     grid.ts      reines Rastermodell (npm run check)
  grid-view.ts    seitenweises Raster  drag.ts      Pointer-Drag-Engine
  access.ts       Sessions, Rollen     oidc.ts      OIDC-Provider
  apps/           Einstellungen, Admin demo/        Client-only-Demo (GitHub Pages)

npm run check prüft das Rastermodell, npm run build baut Demo und Doku, npm run build:package die Bibliothek. Jeder Push auf main veröffentlicht Demo, Doku und /lib über .github/workflows/pages.yml auf GitHub Pages.