@riducms/plugin-graphql 0.5.0

package/src/playground.svelte

@@ -0,0 +1,252 @@
+<script lang="ts">
+	import "./playground.scss";
+
+	import type { EditorView } from "@codemirror/view";
+	import type { AdminExtensionProps, AdminLoaderProps } from "@riducms/plugin";
+	import { Button } from "@riducms/ui";
+	import { buildSchema, type GraphQLSchema } from "graphql";
+	import { untrack } from "svelte";
+
+	import {
+		configureEditor,
+		createJSONEditor,
+		createQueryEditor,
+		replaceDocument,
+		setQuerySchema,
+	} from "./editor";
+	import type { PlaygroundData } from "./loader";
+	import { PlaygroundController } from "./playground-controller.svelte";
+	import SchemaExplorer from "./schema-explorer.svelte";
+	import { starterQuery } from "./starter-query";
+
+	let { data, i18n }: AdminExtensionProps & AdminLoaderProps<PlaygroundData> = $props();
+
+	const schema: GraphQLSchema | undefined = $derived.by(() => {
+		try {
+			return buildSchema(data.schema);
+		} catch {
+			return undefined;
+		}
+	});
+
+	// The endpoint is fixed for the application's lifetime, so the controller keeps its first value.
+	// svelte-ignore state_referenced_locally
+	const controller = new PlaygroundController(data.endpoint, starterQuery(schema));
+	$effect(() => () => controller.dispose());
+
+	let queryView: EditorView | undefined;
+	let variablesView: EditorView | undefined;
+	let responseView: EditorView | undefined;
+
+	const status = $derived.by(() => {
+		const result = controller.result;
+		if (result.kind === "running") return i18n.t("plugin.graphql:running");
+		if (result.kind === "response")
+			return i18n.t("plugin.graphql:status", {
+				status: result.response.status,
+				duration: result.response.durationMs,
+			});
+		return "";
+	});
+	const announcement = $derived.by(() => {
+		const result = controller.result;
+		if (result.kind === "response")
+			return i18n.t("plugin.graphql:responseReady", { status: result.response.status });
+		if (result.kind === "failed")
+			return i18n.t("plugin.graphql:requestFailed", { message: result.message });
+		return "";
+	});
+
+	function responseText() {
+		const result = controller.result;
+		return result.kind === "response" ? result.response.body : "";
+	}
+
+	// Each attachment creates its editor once; later changes flow through the effects below.
+	function mountQuery(node: HTMLElement) {
+		const view = createQueryEditor(node, {
+			doc: controller.query,
+			schema: untrack(() => schema),
+			label: untrack(() => i18n.t("plugin.graphql:query")),
+			onChange: (value) => {
+				controller.query = value;
+			},
+			onRun: run,
+			onShowInDocs: (type) => controller.openDocs(type),
+		});
+		queryView = view;
+		return () => {
+			view.destroy();
+			queryView = undefined;
+		};
+	}
+
+	function mountVariables(node: HTMLElement) {
+		const view = createJSONEditor(node, {
+			doc: controller.variables,
+			readOnly: false,
+			label: untrack(() => i18n.t("plugin.graphql:variables")),
+			placeholder: untrack(() => i18n.t("plugin.graphql:variablesPlaceholder")),
+			onChange: (value) => {
+				controller.variables = value;
+				controller.variablesEdited();
+			},
+			onRun: run,
+		});
+		variablesView = view;
+		return () => {
+			view.destroy();
+			variablesView = undefined;
+		};
+	}
+
+	function mountResponse(node: HTMLElement) {
+		const view = createJSONEditor(node, {
+			doc: untrack(responseText),
+			readOnly: true,
+			label: untrack(() => i18n.t("plugin.graphql:response")),
+			onRun: run,
+		});
+		responseView = view;
+		return () => {
+			view.destroy();
+			responseView = undefined;
+		};
+	}
+
+	// The response and schema belong to different editors and change independently, so each external
+	// synchronization boundary remains explicit rather than coupling their update schedules.
+	$effect(() => {
+		const text = responseText();
+		if (responseView) replaceDocument(responseView, text);
+	});
+	$effect(() => {
+		const current = schema;
+		if (queryView) setQuerySchema(queryView, current);
+	});
+	$effect(() => {
+		const query = i18n.t("plugin.graphql:query");
+		const variables = i18n.t("plugin.graphql:variables");
+		const variablesPlaceholder = i18n.t("plugin.graphql:variablesPlaceholder");
+		const response = i18n.t("plugin.graphql:response");
+		if (queryView) configureEditor(queryView, { label: query });
+		if (variablesView)
+			configureEditor(variablesView, { label: variables, placeholder: variablesPlaceholder });
+		if (responseView) configureEditor(responseView, { label: response });
+	});
+
+	function run() {
+		// The operation under the cursor runs when the document holds several.
+		return controller.run(queryView?.state.selection.main.head ?? 0);
+	}
+
+	function toggleDocs() {
+		if (controller.docs === undefined) controller.openDocs();
+		else controller.closeDocs();
+	}
+</script>
+
+<section class="ridu-graphql" aria-labelledby="ridu-graphql-title">
+	<header class="ridu-graphql__header">
+		<div class="ridu-graphql__intro">
+			<h1 id="ridu-graphql-title" class="ridu-graphql__title">{i18n.t("plugin.graphql:title")}</h1>
+			<p class="ridu-graphql__description">
+				<code dir="ltr">{data.endpoint}</code>
+				<span>{i18n.t("plugin.graphql:description")}</span>
+			</p>
+		</div>
+		<div class="ridu-graphql__actions">
+			{#if schema}
+				<Button
+					variant="outline"
+					aria-expanded={controller.docs !== undefined}
+					aria-controls="ridu-graphql-docs"
+					onclick={toggleDocs}
+				>
+					{i18n.t("plugin.graphql:docs")}
+				</Button>
+			{/if}
+			{#if controller.running}
+				<Button variant="secondary" onclick={() => controller.cancel()}>
+					{i18n.t("plugin.graphql:cancel")}
+				</Button>
+			{/if}
+			<Button onclick={run} disabled={controller.running}>
+				{i18n.t("plugin.graphql:run")}
+				<kbd class="ridu-graphql__shortcut">{i18n.t("plugin.graphql:runShortcut")}</kbd>
+			</Button>
+		</div>
+	</header>
+
+	{#if schema === undefined}
+		<p class="ridu-graphql__notice" role="status">{i18n.t("plugin.graphql:schemaUnavailable")}</p>
+	{/if}
+	{#if controller.variablesInvalid}
+		<p class="ridu-graphql__notice ridu-graphql__notice--error" role="alert">
+			{i18n.t("plugin.graphql:invalidVariables")}
+		</p>
+	{/if}
+
+	<div
+		class="ridu-graphql__workspace"
+		data-docs={controller.docs === undefined ? "closed" : "open"}
+	>
+		<div class="ridu-graphql__request">
+			<section
+				class="ridu-graphql__pane ridu-graphql__pane--query"
+				aria-labelledby="ridu-graphql-query"
+			>
+				<h2 id="ridu-graphql-query" class="ridu-graphql__pane-title">
+					{i18n.t("plugin.graphql:query")}
+				</h2>
+				<div class="ridu-graphql__editor" dir="ltr" {@attach mountQuery}></div>
+			</section>
+			<section
+				class="ridu-graphql__pane ridu-graphql__pane--variables"
+				aria-labelledby="ridu-graphql-variables"
+			>
+				<h2 id="ridu-graphql-variables" class="ridu-graphql__pane-title">
+					{i18n.t("plugin.graphql:variables")}
+				</h2>
+				<div class="ridu-graphql__editor" dir="ltr" {@attach mountVariables}></div>
+			</section>
+		</div>
+
+		<section
+			class="ridu-graphql__pane ridu-graphql__pane--response"
+			aria-labelledby="ridu-graphql-response"
+			aria-busy={controller.running}
+		>
+			<div class="ridu-graphql__pane-heading">
+				<h2 id="ridu-graphql-response" class="ridu-graphql__pane-title">
+					{i18n.t("plugin.graphql:response")}
+				</h2>
+				{#if status}<span class="ridu-graphql__status">{status}</span>{/if}
+			</div>
+			{#if controller.result.kind === "failed"}
+				<p class="ridu-graphql__notice ridu-graphql__notice--error">{announcement}</p>
+			{:else if controller.result.kind === "empty"}
+				<p class="ridu-graphql__empty">{i18n.t("plugin.graphql:noResponse")}</p>
+			{/if}
+			<div
+				class="ridu-graphql__editor"
+				dir="ltr"
+				hidden={controller.result.kind !== "response"}
+				{@attach mountResponse}
+			></div>
+			<p class="ridu-graphql__announcement" aria-live="polite">{announcement}</p>
+		</section>
+
+		{#if schema && controller.docs !== undefined}
+			<SchemaExplorer
+				id="ridu-graphql-docs"
+				{schema}
+				trail={controller.docs}
+				{i18n}
+				onOpen={(type) => controller.openDocs(type)}
+				onBack={() => controller.docsBack()}
+				onClose={() => controller.closeDocs()}
+			/>
+		{/if}
+	</div>
+</section>

package/src/schema-docs.ts

@@ -0,0 +1,171 @@
+import {
+	isEnumType,
+	isInputObjectType,
+	isInterfaceType,
+	isListType,
+	isNonNullType,
+	isObjectType,
+	isUnionType,
+	astFromValue,
+	print,
+	type GraphQLArgument,
+	type GraphQLField,
+	type GraphQLInputField,
+	type GraphQLSchema,
+	type GraphQLType,
+} from "graphql";
+
+/** A type as written in SDL, such as `[Post!]!`, with the named type it links to. */
+export interface TypeReference {
+	label: string;
+	name: string;
+}
+
+export interface DocArgument {
+	name: string;
+	type: TypeReference;
+	description?: string;
+	defaultValue?: string;
+}
+
+export interface DocField {
+	name: string;
+	type: TypeReference;
+	description?: string;
+	deprecation?: string;
+	args: DocArgument[];
+}
+
+export type DocTypeKind = "object" | "interface" | "input" | "enum" | "union" | "scalar";
+
+export interface DocType {
+	name: string;
+	kind: DocTypeKind;
+	description?: string;
+	fields: DocField[];
+	values: { name: string; description?: string }[];
+	members: TypeReference[];
+}
+
+export interface DocRoot {
+	operation: "query" | "mutation" | "subscription";
+	type: string;
+}
+
+/** The entry points shown when the explorer opens. */
+export function schemaRoots(schema: GraphQLSchema): DocRoot[] {
+	const roots: DocRoot[] = [];
+	const query = schema.getQueryType();
+	const mutation = schema.getMutationType();
+	const subscription = schema.getSubscriptionType();
+	if (query) roots.push({ operation: "query", type: query.name });
+	if (mutation) roots.push({ operation: "mutation", type: mutation.name });
+	if (subscription) roots.push({ operation: "subscription", type: subscription.name });
+	return roots;
+}
+
+export function describeType(schema: GraphQLSchema, name: string): DocType | undefined {
+	const type = schema.getType(name);
+	if (type === undefined || type === null) return undefined;
+	const description = type.description ?? undefined;
+	const base = { name: type.name, ...(description ? { description } : {}) };
+	if (isObjectType(type) || isInterfaceType(type))
+		return {
+			...base,
+			kind: isObjectType(type) ? "object" : "interface",
+			fields: Object.values(type.getFields()).map(describeField),
+			values: [],
+			members: [],
+		};
+	if (isInputObjectType(type))
+		return {
+			...base,
+			kind: "input",
+			fields: Object.values(type.getFields()).map(describeInputField),
+			values: [],
+			members: [],
+		};
+	if (isEnumType(type))
+		return {
+			...base,
+			kind: "enum",
+			fields: [],
+			values: type.getValues().map((value) => ({
+				name: value.name,
+				...(value.description ? { description: value.description } : {}),
+			})),
+			members: [],
+		};
+	if (isUnionType(type))
+		return {
+			...base,
+			kind: "union",
+			fields: [],
+			values: [],
+			members: type.getTypes().map((member) => ({ label: member.name, name: member.name })),
+		};
+	return { ...base, kind: "scalar", fields: [], values: [], members: [] };
+}
+
+/** Types and fields whose name contains the search text, for the explorer's search box. */
+export function searchSchema(schema: GraphQLSchema, text: string, limit = 50) {
+	const needle = text.trim().toLowerCase();
+	if (needle === "") return [];
+	const matches: { type: string; field?: string }[] = [];
+	for (const type of Object.values(schema.getTypeMap())) {
+		if (type.name.startsWith("__")) continue;
+		if (type.name.toLowerCase().includes(needle)) matches.push({ type: type.name });
+		if (isObjectType(type) || isInterfaceType(type) || isInputObjectType(type))
+			for (const field of Object.values(type.getFields()))
+				if (field.name.toLowerCase().includes(needle))
+					matches.push({ type: type.name, field: field.name });
+		if (matches.length >= limit) break;
+	}
+	return matches.slice(0, limit);
+}
+
+export function typeReference(type: GraphQLType): TypeReference {
+	if (isNonNullType(type)) {
+		const inner = typeReference(type.ofType);
+		return { label: `${inner.label}!`, name: inner.name };
+	}
+	if (isListType(type)) {
+		const inner = typeReference(type.ofType);
+		return { label: `[${inner.label}]`, name: inner.name };
+	}
+	return { label: type.name, name: type.name };
+}
+
+function describeField(field: GraphQLField<unknown, unknown>): DocField {
+	return {
+		name: field.name,
+		type: typeReference(field.type),
+		...(field.description ? { description: field.description } : {}),
+		...(field.deprecationReason ? { deprecation: field.deprecationReason } : {}),
+		args: field.args.map(describeArgument),
+	};
+}
+
+function describeInputField(field: GraphQLInputField): DocField {
+	return {
+		name: field.name,
+		type: typeReference(field.type),
+		...(field.description ? { description: field.description } : {}),
+		args: [],
+	};
+}
+
+function describeArgument(argument: GraphQLArgument): DocArgument {
+	const defaultValue =
+		argument.defaultValue === undefined
+			? undefined
+			: astFromValue(argument.defaultValue, argument.type);
+	return {
+		name: argument.name,
+		type: typeReference(argument.type),
+		...(argument.description ? { description: argument.description } : {}),
+		...(defaultValue === undefined || defaultValue === null
+			? {}
+			: { defaultValue: print(defaultValue) }),
+	};
+}

package/src/schema-explorer.svelte

@@ -0,0 +1,189 @@
+<script lang="ts">
+	import type { AdminI18n } from "@riducms/plugin";
+	import { Button, Input } from "@riducms/ui";
+	import type { GraphQLSchema } from "graphql";
+	import { tick } from "svelte";
+
+	import { describeType, schemaRoots, searchSchema, type TypeReference } from "./schema-docs";
+
+	let {
+		id,
+		schema,
+		trail,
+		i18n,
+		onOpen,
+		onBack,
+		onClose,
+	}: {
+		id: string;
+		schema: GraphQLSchema;
+		/** Types opened so far; the last one is shown. Empty shows the root types. */
+		trail: readonly string[];
+		i18n: AdminI18n;
+		onOpen: (type: string) => void;
+		onBack: () => void;
+		onClose: () => void;
+	} = $props();
+
+	let search = $state("");
+	let heading: HTMLHeadingElement | undefined;
+
+	const current = $derived(trail.at(-1));
+	const type = $derived(current === undefined ? undefined : describeType(schema, current));
+	const matches = $derived(searchSchema(schema, search));
+
+	// Navigating inside the explorer moves focus to the new heading so keyboard users land on the
+	// content they chose. Opening docs from the editor leaves focus in the editor.
+	async function open(name: string) {
+		search = "";
+		onOpen(name);
+		await tick();
+		heading?.focus();
+	}
+
+	async function back() {
+		onBack();
+		await tick();
+		heading?.focus();
+	}
+</script>
+
+{#snippet reference(target: TypeReference)}
+	<button type="button" class="ridu-graphql-docs__type" onclick={() => open(target.name)}>
+		{target.label}
+	</button>
+{/snippet}
+
+<aside {id} class="ridu-graphql-docs" aria-label={i18n.t("plugin.graphql:docs")}>
+	<header class="ridu-graphql-docs__header">
+		{#if trail.length > 0}
+			<Button variant="ghost" size="sm" onclick={back}>← {i18n.t("plugin.graphql:back")}</Button>
+		{/if}
+		<h2 class="ridu-graphql-docs__title" tabindex="-1" bind:this={heading}>
+			{current ?? i18n.t("plugin.graphql:docs")}
+		</h2>
+		<Button variant="ghost" size="sm" onclick={onClose}>
+			{i18n.t("plugin.graphql:closeDocs")}
+		</Button>
+	</header>
+
+	<Input
+		type="search"
+		class="ridu-graphql-docs__search"
+		placeholder={i18n.t("plugin.graphql:searchSchema")}
+		aria-label={i18n.t("plugin.graphql:searchSchema")}
+		bind:value={search}
+	/>
+
+	<div class="ridu-graphql-docs__body">
+		{#if search.trim() !== ""}
+			{#if matches.length === 0}
+				<p class="ridu-graphql-docs__muted">{i18n.t("plugin.graphql:noMatches")}</p>
+			{:else}
+				<ul class="ridu-graphql-docs__list">
+					{#each matches as match (`${match.type}.${match.field ?? ""}`)}
+						<li>
+							<button
+								type="button"
+								class="ridu-graphql-docs__type"
+								onclick={() => open(match.type)}
+							>
+								{match.field === undefined ? match.type : `${match.type}.${match.field}`}
+							</button>
+						</li>
+					{/each}
+				</ul>
+			{/if}
+		{:else if current === undefined}
+			<h3 class="ridu-graphql-docs__section">{i18n.t("plugin.graphql:rootTypes")}</h3>
+			<ul class="ridu-graphql-docs__list">
+				{#each schemaRoots(schema) as root (root.operation)}
+					<li>
+						<span class="ridu-graphql-docs__keyword">{root.operation}</span>
+						:
+						{@render reference({ label: root.type, name: root.type })}
+					</li>
+				{/each}
+			</ul>
+		{:else if type === undefined}
+			<p class="ridu-graphql-docs__muted">
+				{i18n.t("plugin.graphql:typeNotFound", { type: current })}
+			</p>
+		{:else}
+			<p class="ridu-graphql-docs__kind">{type.kind}</p>
+			{#if type.description}
+				<p class="ridu-graphql-docs__description">{type.description}</p>
+			{/if}
+
+			{#if type.fields.length > 0}
+				<h3 class="ridu-graphql-docs__section">{i18n.t("plugin.graphql:fields")}</h3>
+				<ul class="ridu-graphql-docs__fields">
+					{#each type.fields as field (field.name)}
+						<li class="ridu-graphql-docs__field">
+							<div class="ridu-graphql-docs__signature" dir="ltr">
+								<span class="ridu-graphql-docs__name">{field.name}</span>
+								:
+								{@render reference(field.type)}
+							</div>
+							{#if field.description}
+								<p class="ridu-graphql-docs__description">{field.description}</p>
+							{/if}
+							{#if field.deprecation}
+								<p class="ridu-graphql-docs__warning">
+									{i18n.t("plugin.graphql:deprecated", { reason: field.deprecation })}
+								</p>
+							{/if}
+							{#if field.args.length > 0}
+								<details class="ridu-graphql-docs__arguments">
+									<summary>{i18n.t("plugin.graphql:arguments")} ({field.args.length})</summary>
+									<ul>
+										{#each field.args as argument (argument.name)}
+											<li>
+												<span class="ridu-graphql-docs__name">{argument.name}</span>
+												:
+												{@render reference(argument.type)}
+												{#if argument.defaultValue !== undefined}
+													<span class="ridu-graphql-docs__muted">
+														{i18n.t("plugin.graphql:defaultValue", {
+															value: argument.defaultValue,
+														})}
+													</span>
+												{/if}
+												{#if argument.description}
+													<p class="ridu-graphql-docs__description">{argument.description}</p>
+												{/if}
+											</li>
+										{/each}
+									</ul>
+								</details>
+							{/if}
+						</li>
+					{/each}
+				</ul>
+			{/if}
+
+			{#if type.values.length > 0}
+				<h3 class="ridu-graphql-docs__section">{i18n.t("plugin.graphql:values")}</h3>
+				<ul class="ridu-graphql-docs__list">
+					{#each type.values as value (value.name)}
+						<li>
+							<span class="ridu-graphql-docs__name">{value.name}</span>
+							{#if value.description}
+								<p class="ridu-graphql-docs__description">{value.description}</p>
+							{/if}
+						</li>
+					{/each}
+				</ul>
+			{/if}
+
+			{#if type.members.length > 0}
+				<h3 class="ridu-graphql-docs__section">{i18n.t("plugin.graphql:members")}</h3>
+				<ul class="ridu-graphql-docs__list">
+					{#each type.members as member (member.name)}
+						<li>{@render reference(member)}</li>
+					{/each}
+				</ul>
+			{/if}
+		{/if}
+	</div>
+</aside>

package/src/starter-query.ts

@@ -0,0 +1,53 @@
+import {
+	getNamedType,
+	isLeafType,
+	isListType,
+	isNonNullType,
+	isObjectType,
+	type GraphQLField,
+	type GraphQLObjectType,
+	type GraphQLSchema,
+} from "graphql";
+
+/**
+ * A first query that runs against this application's schema: the first collection list with a few
+ * of its scalar fields. It falls back to `__typename` when the schema has no list query.
+ */
+export function starterQuery(schema: GraphQLSchema | undefined) {
+	const header =
+		"# Press Ctrl+Enter (⌘+Enter on a Mac) to run.\n" + "# Press Ctrl+Space for suggestions.\n";
+	const list = schema === undefined ? undefined : firstListQuery(schema);
+	if (list === undefined) return `${header}query {\n  __typename\n}\n`;
+	const fields = scalarFields(list.document).slice(0, 3);
+	const selection = fields.map((name) => `      ${name}\n`).join("");
+	return `${header}query {\n  ${list.field.name}(limit: 10) {\n    docs {\n${selection}    }\n    totalDocs\n  }\n}\n`;
+}
+
+function firstListQuery(schema: GraphQLSchema) {
+	const query = schema.getQueryType();
+	if (query === null || query === undefined) return undefined;
+	for (const field of Object.values(query.getFields())) {
+		const page = getNamedType(field.type);
+		if (!isObjectType(page) || field.args.some((argument) => isNonNullType(argument.type)))
+			continue;
+		const fields = page.getFields();
+		const docs = fields.docs;
+		if (docs === undefined || fields.totalDocs === undefined) continue;
+		const document = getNamedType(docs.type);
+		if (isObjectType(document) && isListType(unwrapNonNull(docs.type))) return { field, document };
+	}
+	return undefined;
+}
+
+function scalarFields(type: GraphQLObjectType) {
+	return Object.values(type.getFields())
+		.filter(
+			(field: GraphQLField<unknown, unknown>) =>
+				field.args.length === 0 && isLeafType(unwrapNonNull(field.type))
+		)
+		.map((field) => field.name);
+}
+
+function unwrapNonNull<T>(type: T) {
+	return isNonNullType(type) ? type.ofType : type;
+}

package/src/vite-env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module "~icons/*" {
+	import type { Component } from "svelte";
+	const icon: Component<Record<string, unknown>>;
+	export default icon;
+}