@riducms/plugin-graphql 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haniel Ubogu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# `@riducms/plugin-graphql`
+
+The admin GraphQL playground for Ridu's Go GraphQL plugin. Admins open **GraphQL** in the
+sidebar to write operations with schema-aware completion and validation, run them under the current
+admin access rules, inspect responses, and browse the schema docs.
+
+Install it with the Go plugin:
+
+```sh
+ridu add graphql \
+  --go-package github.com/riducms/ridu/plugins/graphql \
+  --admin-package @riducms/plugin-graphql
+bun run dev
+```
+
+The generated registry imports `graphqlAdminPlugin`; do not register it again. The Go plugin serves
+the schema and endpoint through the `graphql-playground` admin loader, so the playground works with
+a custom `Path` and never needs public introspection. Set `DisablePlayground` on the Go plugin to
+remove the route and loader, then remove this package.
+
+The editor, GraphQL language tools, and docs explorer load only when the playground opens. Its
+`ridu-graphql*` presentation is semantic SCSS in the shared component layer; applications can
+override those hooks.
+
+See the [GraphQL guide](../../website/src/content/docs/graphql.md#playground) for setup, keyboard
+shortcuts, and security.

package/package.json

@@ -0,0 +1,52 @@
+{
+	"bugs": {
+		"url": "https://github.com/riducms/ridu/issues"
+	},
+	"dependencies": {
+		"@codemirror/autocomplete": "^6.20.3",
+		"@codemirror/commands": "^6.11.1",
+		"@codemirror/lang-json": "^6.0.2",
+		"@codemirror/language": "^6.12.4",
+		"@codemirror/lint": "^6.9.7",
+		"@codemirror/state": "^6.7.5",
+		"@codemirror/view": "^6.43.12",
+		"@lezer/highlight": "^1.2.3",
+		"@riducms/plugin": "0.5.0",
+		"@riducms/protocol": "0.5.0",
+		"@riducms/sdk": "0.5.0",
+		"@riducms/ui": "0.5.0",
+		"cm6-graphql": "^0.2.2",
+		"graphql": "^16.14.2",
+		"svelte": "^5.56.8"
+	},
+	"description": "GraphQL playground for Ridu's official GraphQL plugin.",
+	"devDependencies": {
+		"@riducms/build": "0.5.0"
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": [
+		"src",
+		"LICENSE"
+	],
+	"homepage": "https://riducms.com",
+	"license": "MIT",
+	"name": "@riducms/plugin-graphql",
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	},
+	"repository": {
+		"directory": "packages/plugin-graphql",
+		"type": "git",
+		"url": "git+https://github.com/riducms/ridu.git"
+	},
+	"scripts": {
+		"build": "vite build",
+		"check": "svelte-check --tsconfig ./tsconfig.json",
+		"test": "bun test"
+	},
+	"type": "module",
+	"version": "0.5.0"
+}

package/src/editor.ts

@@ -0,0 +1,211 @@
+import { autocompletion, closeBrackets, closeBracketsKeymap } from "@codemirror/autocomplete";
+import { defaultKeymap, history, historyKeymap } from "@codemirror/commands";
+import { json } from "@codemirror/lang-json";
+import {
+	bracketMatching,
+	HighlightStyle,
+	indentOnInput,
+	syntaxHighlighting,
+} from "@codemirror/language";
+import { lintGutter } from "@codemirror/lint";
+import { Compartment, EditorState, type Extension } from "@codemirror/state";
+import {
+	drawSelection,
+	EditorView,
+	highlightActiveLineGutter,
+	keymap,
+	lineNumbers,
+	placeholder,
+} from "@codemirror/view";
+import { tags } from "@lezer/highlight";
+import { graphql, updateSchema } from "cm6-graphql";
+import type { GraphQLSchema } from "graphql";
+
+// Matches the admin's code editor so the playground reads as part of the same interface.
+const highlighting = HighlightStyle.define([
+	{ tag: [tags.keyword, tags.bool, tags.null], color: "var(--code-keyword)" },
+	{ tag: [tags.string, tags.special(tags.string)], color: "var(--code-string)" },
+	{ tag: [tags.number, tags.literal], color: "var(--code-number)" },
+	{ tag: [tags.propertyName, tags.attributeName], color: "var(--code-property)" },
+	{ tag: tags.comment, color: "var(--code-comment)", fontStyle: "italic" },
+	{ tag: [tags.typeName, tags.className], color: "var(--code-type)" },
+	{ tag: [tags.variableName, tags.definition(tags.variableName)], color: "var(--syntax-variable)" },
+]);
+
+// CodeMirror injects unlayered base CSS; its theme API overrides those defaults with Ridu tokens.
+const theme = EditorView.theme({
+	"&": { height: "100%", fontSize: "13px", backgroundColor: "transparent" },
+	"&.cm-focused": { outline: "none" },
+	".cm-scroller": { fontFamily: "var(--font-mono)", lineHeight: "20px", overflow: "auto" },
+	".cm-content": { padding: "12px 0", caretColor: "var(--foreground)" },
+	".cm-line": { paddingInline: "10px 16px" },
+	// The gutter stays in place while long lines scroll sideways, so it must be opaque.
+	".cm-gutters": {
+		backgroundColor: "var(--background-surface, var(--card))",
+		color: "var(--foreground-faint, var(--muted-foreground))",
+		border: "0",
+	},
+	".cm-lineNumbers .cm-gutterElement": { padding: "0 8px 0 12px" },
+	".cm-activeLineGutter": { backgroundColor: "transparent", color: "var(--foreground)" },
+	".cm-selectionBackground": { backgroundColor: "var(--control-surface-hover)" },
+	"&.cm-focused .cm-selectionBackground": {
+		backgroundColor: "color-mix(in srgb, var(--foreground) 20%, transparent)",
+	},
+	".cm-cursor": { borderLeftColor: "var(--foreground)" },
+	".cm-matchingBracket": { outline: "1px solid var(--muted-foreground)" },
+	".cm-placeholder": { color: "var(--muted-foreground)" },
+	".cm-tooltip": {
+		backgroundColor: "var(--popover)",
+		color: "var(--popover-foreground)",
+		border: "1px solid var(--border)",
+		borderRadius: "var(--radius)",
+		boxShadow: "var(--shadow-popover)",
+	},
+	".cm-tooltip-autocomplete > ul > li[aria-selected]": {
+		backgroundColor: "var(--control-surface-hover)",
+		color: "var(--foreground)",
+	},
+	".cm-diagnostic-error": { borderLeftColor: "var(--destructive)" },
+});
+
+interface EditorOptions {
+	doc: string;
+	label: string;
+	onChange?: (value: string) => void;
+	/** Runs the current operation; bound to Ctrl/⌘+Enter in every playground editor. */
+	onRun?: () => void;
+	placeholder?: string;
+}
+
+interface EditorPresentation {
+	label: string;
+	placeholder?: string;
+}
+
+const editorConfigurations = new WeakMap<
+	EditorView,
+	{ compartment: Compartment; readOnly: boolean }
+>();
+
+function presentationExtensions(options: EditorPresentation, readOnly: boolean): Extension {
+	return [
+		EditorState.readOnly.of(readOnly),
+		EditorView.editable.of(!readOnly),
+		EditorView.contentAttributes.of({
+			"aria-label": options.label,
+			"aria-readonly": String(readOnly),
+			spellcheck: "false",
+			...(readOnly ? { tabindex: "0" } : {}),
+		}),
+		...(options.placeholder ? [placeholder(options.placeholder)] : []),
+	];
+}
+
+function baseExtensions(
+	options: EditorOptions,
+	readOnly: boolean,
+	configuration: Compartment
+): Extension[] {
+	const run = options.onRun;
+	return [
+		theme,
+		syntaxHighlighting(highlighting),
+		lineNumbers(),
+		highlightActiveLineGutter(),
+		drawSelection(),
+		bracketMatching(),
+		configuration.of(presentationExtensions(options, readOnly)),
+		keymap.of([
+			...(run
+				? [
+						{
+							key: "Mod-Enter",
+							run: () => {
+								run();
+								return true;
+							},
+						},
+					]
+				: []),
+		]),
+		...(readOnly
+			? []
+			: [
+					history(),
+					indentOnInput(),
+					closeBrackets(),
+					keymap.of([...closeBracketsKeymap, ...defaultKeymap, ...historyKeymap]),
+				]),
+		EditorView.updateListener.of((update) => {
+			if (update.docChanged) options.onChange?.(update.state.doc.toString());
+		}),
+	];
+}
+
+export interface QueryEditorOptions extends EditorOptions {
+	schema: GraphQLSchema | undefined;
+	/** Opens the docs explorer at a type, from Ctrl/⌘+click or a completion's details. */
+	onShowInDocs: (type: string) => void;
+}
+
+/** The GraphQL editor: schema-aware completion, validation, and jump-to-docs. */
+export function createQueryEditor(parent: HTMLElement, options: QueryEditorOptions) {
+	const configuration = new Compartment();
+	const view = new EditorView({
+		parent,
+		state: EditorState.create({
+			doc: options.doc,
+			extensions: [
+				...baseExtensions(options, false, configuration),
+				graphql(options.schema, {
+					onShowInDocs: (field, type, parentType) => {
+						const target = parentType ?? type ?? field;
+						if (target) options.onShowInDocs(target);
+					},
+				}),
+				autocompletion({ activateOnTyping: true }),
+				lintGutter(),
+			],
+		}),
+	});
+	editorConfigurations.set(view, { compartment: configuration, readOnly: false });
+	return view;
+}
+
+export function setQuerySchema(view: EditorView, schema: GraphQLSchema | undefined) {
+	updateSchema(view, schema);
+}
+
+/** A JSON editor for variables, or a read-only viewer for responses. */
+export function createJSONEditor(
+	parent: HTMLElement,
+	options: EditorOptions & { readOnly: boolean }
+) {
+	const configuration = new Compartment();
+	const view = new EditorView({
+		parent,
+		state: EditorState.create({
+			doc: options.doc,
+			extensions: [...baseExtensions(options, options.readOnly, configuration), json()],
+		}),
+	});
+	editorConfigurations.set(view, { compartment: configuration, readOnly: options.readOnly });
+	return view;
+}
+
+/** Updates translated editor chrome without recreating the editor or losing its history. */
+export function configureEditor(view: EditorView, options: EditorPresentation) {
+	const configuration = editorConfigurations.get(view);
+	if (configuration === undefined) return;
+	view.dispatch({
+		effects: configuration.compartment.reconfigure(
+			presentationExtensions(options, configuration.readOnly)
+		),
+	});
+}
+
+/** Replaces the whole document when an externally owned value changes. */
+export function replaceDocument(view: EditorView, text: string) {
+	if (view.state.doc.toString() === text) return;
+	view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: text } });
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+import { withAdminLoader } from "@riducms/plugin";
+import { defineAdminPlugin } from "@riducms/plugin/authoring/v1";
+
+import { playgroundLoader } from "./loader";
+import { graphqlMessages } from "./messages";
+import PlaygroundRoute from "./playground-route.svelte";
+
+/** The admin companion of `github.com/riducms/ridu/plugins/graphql`: the GraphQL playground. */
+export const graphqlAdminPlugin = defineAdminPlugin({
+	key: "graphql",
+	pairingVersion: 1,
+	routes: [
+		{
+			path: "graphql",
+			navigation: { label: "GraphQL", labelKey: "plugin.graphql:navigation" },
+			...withAdminLoader(playgroundLoader, PlaygroundRoute),
+		},
+	],
+	messages: graphqlMessages,
+});
+
+export { graphqlMessages } from "./messages";

package/src/loader.ts

@@ -0,0 +1,26 @@
+import type { SchemaAdminLoader } from "@riducms/protocol";
+import { createAdminLoader } from "@riducms/sdk";
+
+/** What the Go plugin's playground loader returns. */
+export interface PlaygroundData {
+	/** Same-origin path of the GraphQL transport, such as `/api/graphql`. */
+	endpoint: string;
+	/** The transport's SDL, identical to the file `ridu generate` writes. */
+	schema: string;
+}
+
+// Mirrors the Go loader's manifest contract property for property. The admin build compares the
+// two exactly, so a mismatch fails before the playground can request data.
+const playgroundContract: SchemaAdminLoader = {
+	key: "graphql-playground",
+	input: { kind: "object" },
+	output: {
+		kind: "object",
+		fields: { endpoint: { kind: "string" }, schema: { kind: "string" } },
+	},
+};
+
+/** Reads the playground's endpoint and schema through the admin's existing access policy. */
+export const playgroundLoader = createAdminLoader<Record<string, never>, PlaygroundData>(
+	playgroundContract
+);

package/src/messages.ts

@@ -0,0 +1,115 @@
+import { defineAdminMessages } from "@riducms/plugin";
+
+/** English fallback text for the playground, translatable under `plugin.graphql:<key>`. */
+export const graphqlMessages = defineAdminMessages({
+	fallback: {
+		navigation: "GraphQL",
+		title: "GraphQL playground",
+		loading: "Loading the playground…",
+		loadFailed: "The playground could not be loaded.",
+		reload: "Reload page",
+		description: "Operations use your current admin access.",
+		run: "Run",
+		runShortcut: "Ctrl+Enter",
+		cancel: "Cancel",
+		docs: "Docs",
+		closeDocs: "Close docs",
+		query: "Query",
+		variables: "Variables",
+		variablesPlaceholder: 'Variables as JSON, such as { "limit": 5 }',
+		response: "Response",
+		noResponse: "Run an operation to see its response here.",
+		running: "Running…",
+		status: "{status} · {duration} ms",
+		responseReady: "Response received: {status}.",
+		invalidVariables: "Variables must be a single JSON object.",
+		requestFailed: "The request could not be sent: {message}",
+		schemaUnavailable:
+			"The schema could not be read, so suggestions and docs are unavailable. Operations still run.",
+		searchSchema: "Search types and fields",
+		noMatches: "No types or fields match.",
+		rootTypes: "Root types",
+		back: "Back",
+		fields: "Fields",
+		arguments: "Arguments",
+		values: "Values",
+		members: "Possible types",
+		defaultValue: "Default: {value}",
+		deprecated: "Deprecated: {reason}",
+		typeNotFound: "{type} is not in this schema.",
+	},
+	translations: {
+		fr: {
+			navigation: "GraphQL",
+			title: "Bac à sable GraphQL",
+			loading: "Chargement du bac à sable…",
+			loadFailed: "Impossible de charger le bac à sable.",
+			reload: "Recharger la page",
+			description: "Les opérations utilisent vos accès d’administration actuels.",
+			run: "Exécuter",
+			runShortcut: "Ctrl+Entrée",
+			cancel: "Annuler",
+			docs: "Documentation",
+			closeDocs: "Fermer la documentation",
+			query: "Requête",
+			variables: "Variables",
+			variablesPlaceholder: 'Variables en JSON, par exemple { "limit": 5 }',
+			response: "Réponse",
+			noResponse: "Exécutez une opération pour afficher sa réponse ici.",
+			running: "Exécution…",
+			status: "{status} · {duration} ms",
+			responseReady: "Réponse reçue : {status}.",
+			invalidVariables: "Les variables doivent former un seul objet JSON.",
+			requestFailed: "Impossible d’envoyer la requête : {message}",
+			schemaUnavailable:
+				"Le schéma est illisible : les suggestions et la documentation sont indisponibles. Les opérations s’exécutent toujours.",
+			searchSchema: "Rechercher des types et des champs",
+			noMatches: "Aucun type ni champ ne correspond.",
+			rootTypes: "Types racines",
+			back: "Retour",
+			fields: "Champs",
+			arguments: "Arguments",
+			values: "Valeurs",
+			members: "Types possibles",
+			defaultValue: "Par défaut : {value}",
+			deprecated: "Obsolète : {reason}",
+			typeNotFound: "{type} ne figure pas dans ce schéma.",
+		},
+		ar: {
+			navigation: "GraphQL",
+			title: "ساحة تجربة GraphQL",
+			loading: "جارٍ تحميل ساحة التجربة…",
+			loadFailed: "تعذر تحميل ساحة التجربة.",
+			reload: "إعادة تحميل الصفحة",
+			description: "تستخدم العمليات صلاحيات الإدارة الحالية.",
+			run: "تشغيل",
+			runShortcut: "Ctrl+Enter",
+			cancel: "إلغاء",
+			docs: "التوثيق",
+			closeDocs: "إغلاق التوثيق",
+			query: "الاستعلام",
+			variables: "المتغيرات",
+			variablesPlaceholder: 'المتغيرات بصيغة JSON، مثل { "limit": 5 }',
+			response: "الاستجابة",
+			noResponse: "شغّل عملية لعرض استجابتها هنا.",
+			running: "جارٍ التشغيل…",
+			status: "{status} · {duration} مللي ثانية",
+			responseReady: "تم استلام الاستجابة: {status}.",
+			invalidVariables: "يجب أن تكون المتغيرات كائن JSON واحدًا.",
+			requestFailed: "تعذر إرسال الطلب: {message}",
+			schemaUnavailable:
+				"تعذرت قراءة المخطط، لذا لا تتوفر الاقتراحات والتوثيق. لا تزال العمليات تعمل.",
+			searchSchema: "البحث في الأنواع والحقول",
+			noMatches: "لا توجد أنواع أو حقول مطابقة.",
+			rootTypes: "الأنواع الجذرية",
+			back: "رجوع",
+			fields: "الحقول",
+			arguments: "الوسائط",
+			values: "القيم",
+			members: "الأنواع الممكنة",
+			defaultValue: "الافتراضي: {value}",
+			deprecated: "مُهمَل: {reason}",
+			typeNotFound: "{type} غير موجود في هذا المخطط.",
+		},
+	},
+});

package/src/operation.ts

@@ -0,0 +1,90 @@
+import { isRecord } from "@riducms/protocol";
+import { Kind, parse, type OperationDefinitionNode } from "graphql";
+
+export interface OperationRequest {
+	query: string;
+	variables?: Record<string, unknown>;
+	operationName?: string;
+}
+
+export interface OperationResponse {
+	status: number;
+	durationMs: number;
+	/** The response body, indented when it is JSON. */
+	body: string;
+}
+
+export type VariablesResult = { ok: true; value?: Record<string, unknown> } | { ok: false };
+
+/** Variables are optional; when present they must be one JSON object. */
+export function parseVariables(text: string): VariablesResult {
+	if (text.trim() === "") return { ok: true };
+	try {
+		const value: unknown = JSON.parse(text);
+		if (isRecord(value)) return { ok: true, value };
+	} catch {
+		// Reported below as invalid variables.
+	}
+	return { ok: false };
+}
+
+/**
+ * GraphQL needs an operation name when a document holds several operations. Pick the operation
+ * under the cursor, as GraphiQL does. A document that does not parse is sent unchanged so the
+ * server reports the syntax error in its usual response shape.
+ */
+export function operationNameAt(query: string, offset: number): string | undefined {
+	let operations: OperationDefinitionNode[];
+	try {
+		operations = parse(query).definitions.filter(
+			(definition): definition is OperationDefinitionNode =>
+				definition.kind === Kind.OPERATION_DEFINITION
+		);
+	} catch {
+		return undefined;
+	}
+	let selected = operations[0];
+	for (const operation of operations) {
+		if (operation.loc === undefined) continue;
+		if (offset >= operation.loc.start && offset < operation.loc.end) {
+			selected = operation;
+			break;
+		}
+		if (offset >= operation.loc.end) selected = operation;
+	}
+	return operations.length > 1 ? selected?.name?.value : undefined;
+}
+
+/**
+ * Send one operation with the current admin credentials. The admin is served by the same Go binary
+ * as the API, so same-origin credentials authenticate the request when present.
+ */
+export async function executeOperation(
+	endpoint: string,
+	request: OperationRequest,
+	signal: AbortSignal,
+	fetchOperation: typeof fetch = fetch
+): Promise<OperationResponse> {
+	const started = performance.now();
+	const response = await fetchOperation(endpoint, {
+		method: "POST",
+		credentials: "same-origin",
+		headers: { accept: "application/json", "content-type": "application/json" },
+		body: JSON.stringify(request),
+		signal,
+	});
+	const text = await response.text();
+	return {
+		status: response.status,
+		durationMs: Math.round(performance.now() - started),
+		body: indentJSON(text),
+	};
+}
+
+function indentJSON(text: string) {
+	try {
+		return JSON.stringify(JSON.parse(text), null, 2);
+	} catch {
+		return text;
+	}
+}