@json-render/ink
Ink-Terminal-Renderer, der JSON-Spezifikationen in interaktive Terminal-Komponentenbäume mit Standardkomponenten, Datenbindung, Sichtbarkeit, Aktionen und dynamischen Props umwandelt.
Kurzstart
import { defineCatalog } from "@json-render/core";
import { schema } from "@json-render/ink/schema";
import {
standardComponentDefinitions,
standardActionDefinitions,
} from "@json-render/ink/catalog";
import { defineRegistry, Renderer, type Components } from "@json-render/ink";
import { z } from "zod";
// Katalog mit Standard- und benutzerdefinierten Komponenten erstellen
const catalog = defineCatalog(schema, {
components: {
...standardComponentDefinitions,
CustomWidget: {
props: z.object({ title: z.string() }),
slots: [],
description: "Benutzerdefiniertes Widget",
},
},
actions: standardActionDefinitions,
});
// Nur benutzerdefinierte Komponenten registrieren (Standardkomponenten sind eingebaut)
const { registry } = defineRegistry(catalog, {
components: {
CustomWidget: ({ props }) => <Text>{props.title}</Text>,
} as Components<typeof catalog>,
});
// Rendern
function App({ spec }) {
return (
<JSONUIProvider initialState={{}}>
<Renderer spec={spec} registry={registry} />
</JSONUIProvider>
);
}
Spezifikationsstruktur (Flache Element-Map)
Das Ink-Schema verwendet eine flache Element-Map mit einem root-Schlüssel:
{
"root": "main",
"elements": {
"main": {
"type": "Box",
"props": { "flexDirection": "column", "padding": 1 },
"children": ["heading", "content"]
},
"heading": {
"type": "Heading",
"props": { "text": "Dashboard", "level": "h1" },
"children": []
},
"content": {
"type": "Text",
"props": { "text": "Hallo vom Terminal!" },
"children": []
}
}
}
Standardkomponenten
Layout
Box- Flexbox-Layoutcontainer (wie ein terminalbasiertes<div>). Zum Gruppieren, Abstandhalten, Rahmen und Ausrichten. Standardmäßig ist flexDirection row.Text- Textausgabe mit optionalem Styling (Farbe, fett, kursiv usw.)Newline- Fügt Leerzeilen ein. Muss sich innerhalb einer Box mit flexDirection column befinden.Spacer- Flexibler leerer Raum, der sich entlang der Hauptachse ausdehnt.
Inhalt
Heading- Abschnittsüberschrift (h1: fett+unterstrichen, h2: fett, h3: fett+gedimmt, h4: gedimmt)Divider- Horizontaler Trenner mit optionalem zentrierten TitelBadge- Farbige Inline-Beschriftung (Varianten: default, info, success, warning, error)Spinner- Animierter Ladespinner mit optionalem LabelProgressBar- Horizontale Fortschrittsanzeige (0-1)Sparkline- Inline-Diagramm mit Unicode-BlockzeichenBarChart- Horizontales Balkendiagramm mit Beschriftungen und WertenTable- Tabellarische Daten mit Kopf- und ZeilenList- Aufzählungs- oder Nummerierte ListeListItem- Strukturierte Listenzeile mit Titel, Untertitel, vorangestelltem/nachgestelltem TextCard- Umrandeter Container mit optionalem TitelKeyValue- Schlüssel-Wert-Paar-AnzeigeLink- Klickbarer URL mit optionalem LabelStatusLine- Statusnachricht mit farbigem Symbol (info, success, warning, error)Markdown- Rendert Markdown-Text mit Terminal-Styling
Interaktiv
TextInput- Texteingabefeld (Events: submit, change)Select- Auswahlmenü mit Pfeiltastennavigation (Events: change)MultiSelect- Mehrfachauswahl mit Leertaste zum Umschalten (Events: change, submit)ConfirmInput- Ja/Nein-Bestätigungsaufforderung (Events: confirm, deny)Tabs- Registerkartennavigation mit linken/rechten Pfeiltasten (Events: change)
Sichtbarkeitsbedingungen
Verwenden Sie visible an Elementen, um sie basierend auf dem Zustand ein-/auszublenden. Syntax: { "$state": "/pfad" }, { "$state": "/pfad", "eq": wert }, { "$state": "/pfad", "not": true }, { "$and": [bedingung1, bedingung2] } für UND, { "$or": [bedingung1, bedingung2] } für ODER.
Dynamische Prop-Ausdrücke
Jeder Prop-Wert kann ein datengesteuerter Ausdruck sein, der zur Renderzeit aufgelöst wird:
{ "$state": "/state/key" }- liest aus dem Zustandsmodell (nur Lesen){ "$bindState": "/pfad" }- bidirektionale Bindung: für das natürliche Wert-Prop von Formularkomponenten verwenden{ "$bindItem": "feld" }- bidirektionale Bindung an ein Wiederholungselement-Feld{ "$cond": <bedingung>, "$then": <wert>, "$else": <wert> }- bedingter Wert{ "$template": "Hallo, ${/name}!" }- interpoliert Zustandswerte in Zeichenketten
Komponenten verwenden kein statePath-Prop für bidirektionale Bindung. Verwenden Sie stattdessen { "$bindState": "/pfad" } am natürlichen Wert-Prop.
Event-System
Komponenten verwenden emit, um benannte Events auszulösen. Das on-Feld eines Elements ordnet Events Aktionsbindungen zu:
CustomButton: ({ props, emit }) => (
<Box>
<Text>{props.label}</Text>
{/* emit("press") löst die im on.press der Spezifikation gebundene Aktion aus */}
</Box>
),
{
"type": "CustomButton",
"props": { "label": "Senden" },
"on": { "press": { "action": "submit" } },
"children": []
}
Eingebaute Aktionen
setState, pushState und removeState sind eingebaut und werden automatisch behandelt:
{ "action": "setState", "params": { "statePath": "/activeTab", "value": "home" } }
{ "action": "pushState", "params": { "statePath": "/items", "value": { "text": "Neu" } } }
{ "action": "removeState", "params": { "statePath": "/items", "index": 0 } }
Repeat (Dynamische Listen)
Verwenden Sie das repeat-Feld an einem Containerelement, um Elemente aus einem Zustandsarray zu rendern:
{
"type": "Box",
"props": { "flexDirection": "column" },
"repeat": { "statePath": "/items", "key": "id" },
"children": ["item-row"]
}
Innerhalb wiederholter Kinder verwenden Sie { "$item": "field" }, um aus dem aktuellen Element zu lesen, und { "$index": true } für den aktuellen Index.
Streaming
Verwenden Sie useUIStream, um Spezifikationen schrittweise aus JSONL-Patch-Streams zu rendern:
import { useUIStream } from "@json-render/ink";
const { spec, send, isStreaming } = useUIStream({ api: "/api/generate" });
Serverseitige Prompt-Generierung
Verwenden Sie den Export ./server, um KI-System-Prompts aus Ihrem Katalog zu generieren:
import { catalog } from "./catalog";
const systemPrompt = catalog.prompt({ system: "Sie sind ein Terminal-Assistent." });
Provider
| Provider | Zweck |
|---|---|
StateProvider | Zustand zwischen Komponenten teilen (JSON-Pointer-Pfade). Akzeptiert optionales store-Prop für kontrollierten Modus. |
ActionProvider | Aktionen behandeln, die über das Event-System ausgelöst werden |
VisibilityProvider | Bedingte Darstellung basierend auf dem Zustand ermöglichen |
ValidationProvider | Formularfeld-Validierung |
FocusProvider | Fokus über interaktive Komponenten hinweg verwalten |
JSONUIProvider | Kombinierter Provider für alle Kontexte |
Externer Store (Kontrollierter Modus)
Übergeben Sie einen StateStore an StateProvider (oder JSONUIProvider), um eine externe Zustandsverwaltung zu verwenden:
import { createStateStore, type StateStore } from "@json-render/ink";
const store = createStateStore({ count: 0 });
<StateProvider store={store}>{children}</StateProvider>
store.set("/count", 1); // React rendert automatisch neu
Wenn store angegeben wird, werden initialState und onStateChange ignoriert.
createRenderer (Höhere API-Ebene)
import { createRenderer } from "@json-render/ink";
import { standardComponents } from "@json-render/ink";
import { catalog } from "./catalog";
const InkRenderer = createRenderer(catalog, {
...standardComponents,
// benutzerdefinierte Komponenten-Überschreibungen hier
});
// InkRenderer enthält alle Provider (Zustand, Sichtbarkeit, Aktionen, Fokus)
render(
<InkRenderer spec={spec} state={{ activeTab: "overview" }} />
);
Wichtige Exporte
| Export | Zweck |
|---|---|
defineRegistry | Typsicheres Komponentenregister aus einem Katalog erstellen |
Renderer | Eine Spezifikation mithilfe eines Registers rendern |
createRenderer | Höhere Ebene: erstellt eine Komponente mit integrierten Providern |
JSONUIProvider | Kombinierter Provider für alle Kontexte |
schema | Ink-Flache-Element-Map-Schema (enthält eingebaute Zustandsaktionen) |
standardComponentDefinitions | Katalogdefinitionen für alle Standardkomponenten |
standardActionDefinitions | Katalogdefinitionen für Standardaktionen |
standardComponents | Vorgefertigte Komponentenimplementierungen |
useStateStore | Zugriff auf den Zustandskontext |
useStateValue | Einzelnen Wert aus dem Zustand abrufen |
useBoundProp | Bidirektionale Bindung für $bindState/$bindItem-Ausdrücke |
useActions | Zugriff auf den Aktionskontext |
useAction | Einzelne Aktions-Dispatch-Funktion abrufen |
useOptionalValidation | Nicht-werfende Variante von useValidation |
useUIStream | Spezifikationen von einem API-Endpunkt streamen |
createStateStore | Framework-agnostischen In-Memory-StateStore erstellen |
StateStore | Schnittstelle zur Anbindung externer Zustandsverwaltung |
Components | Typisierte Komponenten-Map (katalogbewusst) |
Actions | Typisierte Aktions-Map (katalogbewusst) |
ComponentContext | Typisierter Komponentenkontext (katalogbewusst) |
flatToTree | Flache Element-Map in eine Baumstruktur umwandeln |
Gestaltungsrichtlinien für Terminal-UI
- Verwenden Sie Box für das Layout (flexDirection, padding, gap). Standardmäßig ist flexDirection row.
- Die Terminalbreite beträgt ~80-120 Spalten. Bevorzugen Sie vertikale Layouts (flexDirection: column) für die Hauptstruktur.
- Verwenden Sie borderStyle an Box für visuelle Gruppierung (single, double, round, bold).
- Verwenden Sie benannte Terminalfarben: red, green, yellow, blue, magenta, cyan, white, gray.
- Verwenden Sie Heading für Abschnittstitel, Divider zum Trennen von Abschnitten, Badge für den Status, KeyValue für beschriftete Daten, Card für umrandete Gruppen.
- Verwenden Sie Tabs für Multi-View-UI mit sichtbaren Bedingungen auf dem untergeordneten Inhalt.
- Verwenden Sie Sparkline für Inline-Trends und BarChart zum Vergleichen von Werten.