@gtkx/codegen 0.21.0 → 1.0.0-rc.1

package/src/docs/api-reference.ts

@@ -0,0 +1,361 @@
+import type { ElementProp } from "@gtkx/config";
+import { sortStrings, sortStringsBy, toPascalCase } from "@gtkx/utils";
+import { Library } from "../gir/library.js";
+import { type GirNamespace, namespaceDirectory } from "../gir/namespace.js";
+import { dedupeCallables, isEmittableCallable } from "../store/gi/callables.js";
+import { isClassStructRecord } from "../store/gi/class-struct-record.js";
+import { namespaceFunctionExportName } from "../store/gi/function.js";
+import { collectIntrinsicElementClasses, type GlibNamedClass } from "../store/react/intrinsic-elements.js";
+import { createElementPageContext, type ElementPageContext, renderElementPage } from "./element-page.js";
+import { docsSignatureContext, firstSentence, namespaceOrder } from "./render.js";
+import { type GiSymbolEntry, renderSymbolPage, type SymbolPageOptions } from "./symbol-page.js";
+
+export type ApiReferenceOptions = {
+    libraries: string[];
+    girPath: string[];
+    elementProps?: Record<string, ElementProp[]>;
+};
+
+export type ApiSymbolKind = GiSymbolEntry["kind"] | "element";
+
+export const API_SYMBOL_KINDS: ApiSymbolKind[] = [
+    "element",
+    "class",
+    "interface",
+    "record",
+    "enum",
+    "callback",
+    "alias",
+    "function",
+    "constant",
+];
+
+export type ApiSymbol = {
+    namespace: string;
+    name: string;
+    kind: ApiSymbolKind;
+    summary: string;
+};
+
+export type ApiNamespaceSummary = {
+    name: string;
+    importPath: string;
+    symbols: number;
+    elements: number;
+};
+
+export type ApiLookupResult =
+    | { outcome: "page"; symbol: ApiSymbol; markdown: string }
+    | { outcome: "ambiguous"; candidates: ApiSymbol[] }
+    | { outcome: "notFound" };
+
+export type ApiSearchOptions = {
+    query: string;
+    namespace?: string;
+    kinds?: ApiSymbolKind[];
+    limit?: number;
+};
+
+type ElementEntry = {
+    kind: "element";
+    namespace: GirNamespace;
+    name: string;
+    doc: string | undefined;
+    element: GlibNamedClass;
+};
+
+type SymbolEntry = GiSymbolEntry | ElementEntry;
+
+const KIND_SECTION_TITLES: Record<ApiSymbolKind, string> = {
+    element: "JSX elements",
+    class: "Classes",
+    interface: "Interfaces",
+    record: "Records",
+    enum: "Enums",
+    callback: "Callbacks",
+    alias: "Aliases",
+    function: "Functions",
+    constant: "Constants",
+};
+
+const DEFAULT_SEARCH_LIMIT = 20;
+
+const compareNames = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
+
+class ApiReference {
+    private library: Library;
+    private libraries: string[];
+    private elementContext: ElementPageContext;
+    private entries: SymbolEntry[] = [];
+    private byQualified = new Map<string, SymbolEntry[]>();
+    private byName = new Map<string, SymbolEntry[]>();
+    private byNamespace = new Map<string, SymbolEntry[]>();
+    private elementsByClass = new Map<string, string>();
+
+    constructor(options: ApiReferenceOptions) {
+        this.libraries = options.libraries;
+        this.library = Library.load(options.libraries, options.girPath);
+        this.elementContext = createElementPageContext(this.library, options.elementProps ?? {}, () => undefined);
+        this.buildIndex();
+    }
+
+    get girFiles(): string[] {
+        return this.library.girFiles;
+    }
+
+    private add(entry: SymbolEntry): void {
+        this.entries.push(entry);
+        const push = (map: Map<string, SymbolEntry[]>, key: string): void => {
+            const list = map.get(key) ?? [];
+            list.push(entry);
+            map.set(key, list);
+        };
+        push(this.byQualified, `${entry.namespace.name}.${entry.name}`.toLowerCase());
+        push(this.byName, entry.name.toLowerCase());
+        push(this.byNamespace, entry.namespace.name);
+    }
+
+    private buildIndex(): void {
+        for (const namespace of this.library.namespaces.values()) {
+            this.indexNamespace(namespace);
+        }
+        for (const element of collectIntrinsicElementClasses(this.library)) {
+            this.add({
+                kind: "element",
+                namespace: element.namespace,
+                name: element.glibName,
+                doc: element.klass.doc,
+                element,
+            });
+            this.elementsByClass.set(`${element.namespace.name}.${element.klass.name}`, element.glibName);
+        }
+    }
+
+    private indexNamespace(namespace: GirNamespace): void {
+        const entries = [
+            ...classEntries(namespace),
+            ...recordEntries(this.library, namespace),
+            ...valueEntries(namespace),
+        ];
+        for (const entry of entries) {
+            this.add(entry);
+        }
+        this.indexFunctions(namespace);
+    }
+
+    private indexFunctions(namespace: GirNamespace): void {
+        if (namespace.sharedLibrary === undefined) return;
+        const docsContext = docsSignatureContext(namespace, this.library);
+        for (const fn of dedupeCallables(namespace.functions)) {
+            if (!isEmittableCallable(docsContext, fn)) continue;
+            const cIdentifier = fn.cIdentifier;
+            if (cIdentifier === undefined) continue;
+            const name = namespaceFunctionExportName(cIdentifier, fn.name, namespace.cSymbolPrefixes);
+            this.add({ kind: "function", namespace, name, doc: fn.doc, fn });
+        }
+    }
+
+    private toApiSymbol(entry: SymbolEntry): ApiSymbol {
+        return {
+            namespace: entry.namespace.name,
+            name: entry.name,
+            kind: entry.kind,
+            summary: firstSentence(entry.doc),
+        };
+    }
+
+    private symbolPageOptions(): SymbolPageOptions {
+        return {
+            library: this.library,
+            elementNameFor: (namespaceName, className) => this.elementsByClass.get(`${namespaceName}.${className}`),
+        };
+    }
+
+    private renderPage(entry: SymbolEntry): string {
+        if (entry.kind === "element") return renderElementPage(entry.element, this.elementContext);
+        return renderSymbolPage(entry, this.symbolPageOptions());
+    }
+
+    private findNamespace(name: string): GirNamespace | undefined {
+        const lower = name.toLowerCase();
+        for (const namespace of this.library.namespaces.values()) {
+            if (namespace.name.toLowerCase() === lower) return namespace;
+        }
+        return undefined;
+    }
+
+    lookup(query: string, kind?: ApiSymbolKind): ApiLookupResult {
+        const trimmed = query.trim();
+        if (trimmed.length === 0) return { outcome: "notFound" };
+        const qualified = trimmed.includes(".");
+        const map = qualified ? this.byQualified : this.byName;
+        let candidates = map.get(trimmed.toLowerCase()) ?? [];
+        if (kind !== undefined) candidates = candidates.filter((entry) => entry.kind === kind);
+        if (candidates.length > 1) {
+            const exact = candidates.filter((entry) =>
+                qualified ? `${entry.namespace.name}.${entry.name}` === trimmed : entry.name === trimmed,
+            );
+            if (exact.length > 0) candidates = exact;
+        }
+        const entry = candidates[0];
+        if (entry === undefined) return { outcome: "notFound" };
+        if (candidates.length > 1) {
+            return { outcome: "ambiguous", candidates: candidates.map((candidate) => this.toApiSymbol(candidate)) };
+        }
+        return { outcome: "page", symbol: this.toApiSymbol(entry), markdown: this.renderPage(entry) };
+    }
+
+    search(options: ApiSearchOptions): ApiSymbol[] {
+        const query = options.query.trim().toLowerCase();
+        if (query.length === 0) return [];
+        const limit = Math.max(1, Math.floor(options.limit ?? DEFAULT_SEARCH_LIMIT));
+        const namespaceFilter = options.namespace?.toLowerCase();
+        const scored: { score: number; entry: SymbolEntry }[] = [];
+        for (const entry of this.entries) {
+            if (namespaceFilter !== undefined && entry.namespace.name.toLowerCase() !== namespaceFilter) continue;
+            if (options.kinds !== undefined && !options.kinds.includes(entry.kind)) continue;
+            const score = searchScore(entry, query);
+            if (score === 0) continue;
+            scored.push({ score, entry });
+        }
+        scored.sort(
+            (a, b) =>
+                b.score - a.score ||
+                a.entry.name.length - b.entry.name.length ||
+                compareNames(a.entry.name, b.entry.name) ||
+                compareNames(namespaceOrder(a.entry.namespace.name), namespaceOrder(b.entry.namespace.name)) ||
+                compareNames(a.entry.kind, b.entry.kind),
+        );
+        return scored.slice(0, limit).map((item) => this.toApiSymbol(item.entry));
+    }
+
+    namespaces(): ApiNamespaceSummary[] {
+        const summaries = [...this.byNamespace.entries()].map(([name, entries]) => ({
+            name,
+            importPath: `@gtkx/gi/${namespaceDirectory({ name })}`,
+            symbols: entries.filter((entry) => entry.kind !== "element").length,
+            elements: entries.filter((entry) => entry.kind === "element").length,
+        }));
+        return sortStringsBy(summaries, (summary) => namespaceOrder(summary.name));
+    }
+
+    symbolNames(namespaceName: string): string[] {
+        const namespace = this.findNamespace(namespaceName);
+        if (namespace === undefined) return [];
+        const entries = this.byNamespace.get(namespace.name) ?? [];
+        return sortStrings(entries.map((entry) => entry.name));
+    }
+
+    overview(): string {
+        const rows = this.namespaces().map(
+            (summary) => `| ${summary.name} | \`${summary.importPath}\` | ${summary.symbols} | ${summary.elements} |`,
+        );
+        const librariesList = this.libraries.map((library) => `\`${library}\``).join(", ");
+        return [
+            "# API Reference",
+            "",
+            `Generated bindings for ${librariesList} and the namespaces they pull in. Classes, interfaces, records, enums, callbacks, aliases, functions, and constants are imported from \`@gtkx/gi/<namespace>\`; JSX elements are imported from \`@gtkx/jsx/<namespace>\`.`,
+            "",
+            "Every symbol has a reference page addressed by its qualified name (for example `Gtk.Button`, `Gtk.Orientation`, `GLib.idleAdd`) and every JSX element by its element name (for example `GtkButton`).",
+            "",
+            "| Namespace | Import | Symbols | JSX elements |",
+            "| --- | --- | --- | --- |",
+            ...rows,
+            "",
+        ].join("\n");
+    }
+
+    namespaceOverview(name: string): string | undefined {
+        const namespace = this.findNamespace(name);
+        if (namespace === undefined) return undefined;
+        const entries = this.byNamespace.get(namespace.name) ?? [];
+        const directory = namespaceDirectory(namespace);
+        const lines = [
+            `# ${namespace.name}`,
+            "",
+            `\`\`\`ts\nimport * as ${namespace.name} from "@gtkx/gi/${directory}";\n\`\`\``,
+        ];
+        for (const kind of API_SYMBOL_KINDS) {
+            const names = entries.filter((entry) => entry.kind === kind).map((entry) => entry.name);
+            if (names.length === 0) continue;
+            lines.push(
+                "",
+                `## ${KIND_SECTION_TITLES[kind]} (${names.length})`,
+                "",
+                sortStrings(names)
+                    .map((symbolName) => `\`${symbolName}\``)
+                    .join(", "),
+            );
+        }
+        lines.push("");
+        return lines.join("\n");
+    }
+}
+
+export type { ApiReference };
+
+export const loadApiReference = (options: ApiReferenceOptions): ApiReference => new ApiReference(options);
+
+const classEntries = (namespace: GirNamespace): GiSymbolEntry[] => {
+    const entries: GiSymbolEntry[] = [];
+    for (const klass of [...namespace.classes, ...namespace.interfaces]) {
+        if (!klass.introspectable || klass.name.length === 0) continue;
+        const kind = klass.isInterface ? "interface" : "class";
+        entries.push({ kind, namespace, name: toPascalCase(klass.name), doc: klass.doc, klass });
+    }
+    return entries;
+};
+
+const recordEntries = (library: Library, namespace: GirNamespace): GiSymbolEntry[] => {
+    const entries: GiSymbolEntry[] = [];
+    for (const record of namespace.records) {
+        if (!record.introspectable || record.isVtable || record.name.length === 0) continue;
+        if (isClassStructRecord(library, namespace.name, record)) continue;
+        entries.push({ kind: "record", namespace, name: record.name, doc: record.doc, record });
+    }
+    return entries;
+};
+
+const valueEntries = (namespace: GirNamespace): GiSymbolEntry[] => [
+    ...namespace.enums
+        .filter((enumeration) => enumeration.introspectable)
+        .map<GiSymbolEntry>((enumeration) => ({
+            kind: "enum",
+            namespace,
+            name: enumeration.name,
+            doc: enumeration.doc,
+            enumeration,
+        })),
+    ...namespace.callbacks
+        .filter((callback) => callback.introspectable)
+        .map<GiSymbolEntry>((callback) => ({
+            kind: "callback",
+            namespace,
+            name: callback.name,
+            doc: callback.doc,
+            callback,
+        })),
+    ...namespace.aliases.map<GiSymbolEntry>((alias) => ({
+        kind: "alias",
+        namespace,
+        name: alias.name,
+        doc: alias.doc,
+        alias,
+    })),
+    ...namespace.constants.map<GiSymbolEntry>((constant) => ({
+        kind: "constant",
+        namespace,
+        name: constant.name,
+        doc: constant.doc,
+        constant,
+    })),
+];
+
+const searchScore = (entry: SymbolEntry, query: string): number => {
+    const name = entry.name.toLowerCase();
+    const qualified = `${entry.namespace.name.toLowerCase()}.${name}`;
+    if (name === query || qualified === query) return 3;
+    if (name.startsWith(query)) return 2;
+    if (name.includes(query) || qualified.includes(query)) return 1;
+    return 0;
+};

package/src/docs/element-page.ts

@@ -0,0 +1,290 @@
+import type { ContainerProp, ElementProp } from "@gtkx/config";
+import { sortStringsBy, toCamelIdentifier, upperFirst } from "@gtkx/utils";
+import { ancestorChain } from "../gir/ancestry.js";
+import type { GirClass } from "../gir/class.js";
+import type { Library } from "../gir/library.js";
+import { type GirNamespace, namespaceDirectory } from "../gir/namespace.js";
+import type { GirSignal } from "../gir/parameter.js";
+import { type GirProperty, isConstructableProperty } from "../gir/property.js";
+import { createElementPropTypegen, type ElementPropTypegen } from "../store/react/element-prop-types.js";
+import { assembleElementProps } from "../store/react/element-props.js";
+import { buildGirIndex, type GirIndex } from "../store/react/gir-index.js";
+import {
+    type GlibNamedClass,
+    glibNameOf,
+    implementedInterfaces,
+    newlyImplementedInterfaces,
+    signalHandlerName,
+} from "../store/react/intrinsic-elements.js";
+import { isObjectProp } from "../store/react/props.js";
+import {
+    classMethodEntries,
+    docMarkdown,
+    docsDefaultValue,
+    firstSentence,
+    joinSections,
+    metaBlock,
+    methodsSectionBlocks,
+    originSignatureBlocks,
+    renderDocsSignalSignature,
+    renderDocsType,
+} from "./render.js";
+
+export type ElementPageContext = {
+    library: Library;
+    girIndex: GirIndex;
+    typegen: ElementPropTypegen;
+    elementProps: Record<string, ElementProp[]>;
+    linkFor: (glibName: string) => string | undefined;
+};
+
+export const createElementPageContext = (
+    library: Library,
+    elementProps: Record<string, ElementProp[]>,
+    linkFor: (glibName: string) => string | undefined,
+): ElementPageContext => {
+    const girIndex = buildGirIndex(library);
+    const applied = assembleElementProps(girIndex, elementProps);
+    return {
+        library,
+        girIndex,
+        typegen: createElementPropTypegen(girIndex, applied),
+        elementProps: applied,
+        linkFor,
+    };
+};
+
+type MemberOwner = {
+    klass: GirClass;
+    namespace: GirNamespace;
+    origin: string | undefined;
+    glibName: string | undefined;
+};
+
+type PropEntry = {
+    name: string;
+    meta: string;
+    doc: string;
+};
+
+const frontmatter = (entry: GlibNamedClass): string => {
+    const sentence = firstSentence(entry.klass.doc);
+    const description = sentence.length > 0 ? sentence : `API reference for the ${entry.glibName} element.`;
+    return `---\ndescription: ${JSON.stringify(description)}\n---`;
+};
+
+const importBlock = (entry: GlibNamedClass): string =>
+    `\`\`\`tsx\nimport { ${entry.glibName} } from "@gtkx/jsx/${namespaceDirectory(entry.namespace)}";\n\`\`\``;
+
+const glibLabel = (context: ElementPageContext, glibName: string): string => {
+    const link = context.linkFor(glibName);
+    return link === undefined ? `\`${glibName}\`` : `[${glibName}](${link})`;
+};
+
+const hierarchySection = (entry: GlibNamedClass, context: ElementPageContext): string[] => {
+    const ancestors = [...ancestorChain(context.library, entry.klass, entry.namespace.name)].slice(1).reverse();
+    if (ancestors.length === 0) return [];
+    const parts = ancestors.map((ancestor) => {
+        const glib = glibNameOf(ancestor.klass);
+        return glib === undefined ? `\`${ancestor.namespaceName}.${ancestor.klass.name}\`` : glibLabel(context, glib);
+    });
+    parts.push(`**${entry.glibName}**`);
+    const lines = [`## Hierarchy`, parts.join(" → ")];
+    const interfaces = implementedInterfaces(entry.klass, entry.namespace, context.library)
+        .map((iface) => glibNameOf(iface.klass))
+        .filter((name): name is string => name !== undefined);
+    if (interfaces.length > 0) {
+        lines.push(`Implements ${interfaces.map((name) => `\`${name}\``).join(", ")}.`);
+    }
+    return lines;
+};
+
+const callName = (call: ContainerProp["append"]): string | undefined =>
+    call === undefined ? undefined : typeof call === "string" ? call : call.method;
+
+const containerLine = (prop: ContainerProp, context: ElementPageContext): string => {
+    const child = glibLabel(context, prop.child);
+    const attach = callName(prop.append);
+    const detail: string[] = [];
+    if (attach !== undefined) detail.push(`attached with \`${attach}()\``);
+    if (prop.autowrap !== undefined) {
+        detail.push(`children are wrapped in a ${glibLabel(context, prop.autowrap)} before attaching`);
+    }
+    const suffix = detail.length > 0 ? ` (${detail.join("; ")})` : "";
+    if (prop.prop === "children") return `- \`children\` accepts ${child} elements${suffix}.`;
+    return `- \`${prop.prop}\` is a slot accepting ${child} elements${suffix}.`;
+};
+
+const childrenSection = (entry: GlibNamedClass, context: ElementPageContext): string[] => {
+    const lines: string[] = [];
+    const seen = new Set<string>();
+    for (const owner of memberOwners(entry, context)) {
+        if (owner.glibName === undefined) continue;
+        const overlays = context.elementProps[owner.glibName] ?? [];
+        const containers = overlays.filter(
+            (prop): prop is ContainerProp => prop.kind === "container" && !seen.has(prop.prop),
+        );
+        for (const prop of containers) lines.push(containerLine(prop, context));
+        for (const prop of containers) seen.add(prop.prop);
+    }
+    if (!seen.has("children") && context.typegen.acceptsChildren(entry.glibName)) {
+        lines.push("- `children` accepts child elements.");
+    }
+    if (lines.length === 0) return [];
+    return ["## Children", lines.join("\n")];
+};
+
+const memberOwners = (entry: GlibNamedClass, context: ElementPageContext): MemberOwner[] => [
+    { klass: entry.klass, namespace: entry.namespace, origin: undefined, glibName: entry.glibName },
+    ...newlyImplementedInterfaces(
+        entry.klass,
+        entry.namespace,
+        context.library,
+        (glibName) => glibName !== undefined && context.typegen.containerPropNamesFor(glibName).length > 0,
+    ).map((iface) => {
+        const glibName = glibNameOf(iface.klass);
+        return { klass: iface.klass, namespace: iface.namespace, origin: glibName, glibName };
+    }),
+];
+
+const propertyEntry = (
+    context: ElementPageContext,
+    owner: MemberOwner,
+    property: GirProperty,
+    jsName: string,
+): PropEntry => {
+    const object = isObjectProp(
+        { library: context.library, klass: owner.klass, namespace: owner.namespace },
+        property,
+        jsName,
+    );
+    const baseType = renderDocsType(context.library, property.type, false);
+    const type = object ? `${baseType} | ReactElement` : baseType;
+    const meta: string[] = [`\`${type}\``];
+    if (property.defaultValue !== undefined) meta.push(`default \`${docsDefaultValue(property.defaultValue)}\``);
+    if (property.constructOnly) meta.push("construct-only");
+    if (!isConstructableProperty(property)) meta.push(`read-only, observe with \`onNotify${upperFirst(jsName)}\``);
+    if (owner.origin !== undefined) meta.push(`from \`${owner.origin}\``);
+    return { name: jsName, meta: meta.join(" · "), doc: docMarkdown(property.doc) };
+};
+
+const overlayNote = (overlays: ElementProp[], name: string): string | undefined => {
+    for (const overlay of overlays) {
+        if (overlay.kind === "container" || overlay.prop !== name) continue;
+        if (overlay.kind === "value") return `Applied with \`${callName(overlay.call)}()\`.`;
+        if (overlay.kind === "list") {
+            const applied = (Array.isArray(overlay.add) ? overlay.add : [overlay.add])
+                .map((call) => `\`${callName(call)}()\``)
+                .join(", ");
+            return `Array prop; items are applied with ${applied}.`;
+        }
+        if (overlay.kind === "controlled-text") {
+            return "Controlled: the element is synced to the prop value whenever that value changes; text the user has typed is preserved rather than reverted on every render.";
+        }
+    }
+    return undefined;
+};
+
+const cleanOverlayType = (type: string): string => type.replace(/\s*\|\s*undefined$/, "").replaceAll("$.", ".");
+
+const overlayEntries = (entry: GlibNamedClass, context: ElementPageContext, seen: Set<string>): PropEntry[] => {
+    const overlays = context.elementProps[entry.glibName] ?? [];
+    const entries: PropEntry[] = [];
+    const lines = context.typegen.classPropLines(entry.glibName, entry.klass, entry.namespace, new Map());
+    for (const line of lines) {
+        const match = line.match(/^([A-Za-z0-9_]+)\?: (.*);$/);
+        if (match === null) continue;
+        const [, name = "", rawType = ""] = match;
+        if (seen.has(name)) continue;
+        seen.add(name);
+        const note = overlayNote(overlays, name) ?? "Element prop managed by GTKX.";
+        entries.push({ name, meta: `\`${cleanOverlayType(rawType)}\``, doc: note });
+    }
+    return entries;
+};
+
+const withOverlayNote = (propEntry: PropEntry, note: string | undefined): PropEntry => {
+    if (note === undefined) return propEntry;
+    return { ...propEntry, doc: propEntry.doc.length > 0 ? `${note}\n\n${propEntry.doc}` : note };
+};
+
+const propertyEntries = (entry: GlibNamedClass, context: ElementPageContext, seen: Set<string>): PropEntry[] => {
+    const owners = memberOwners(entry, context);
+    const overlays = owners.flatMap((owner) =>
+        owner.glibName === undefined ? [] : (context.elementProps[owner.glibName] ?? []),
+    );
+    const entries: PropEntry[] = [];
+    for (const owner of owners) {
+        for (const property of owner.klass.properties) {
+            if (!property.introspectable) continue;
+            const jsName = toCamelIdentifier(property.name);
+            if (seen.has(jsName)) continue;
+            seen.add(jsName);
+            const propEntry = propertyEntry(context, owner, property, jsName);
+            entries.push(withOverlayNote(propEntry, overlayNote(overlays, jsName)));
+        }
+    }
+    return entries;
+};
+
+const propsSection = (entry: GlibNamedClass, context: ElementPageContext, selfType: string): string[] => {
+    const seen = new Set<string>();
+    const entries = [...propertyEntries(entry, context, seen), ...overlayEntries(entry, context, seen)];
+    const intro = [
+        `\`ref\` receives the \`${selfType}\` instance.`,
+        `Every mutable property also has an \`onNotify<Prop>\` handler prop called with the new value when the property changes.`,
+        `Props inherited from ancestor elements are documented on their own pages.`,
+    ].join(" ");
+    if (entries.length === 0) return ["## Props", intro];
+    const sorted = sortStringsBy(entries, (item) => item.name);
+    return ["## Props", intro, ...sorted.map((item) => metaBlock(item.name, item.meta, item.doc))];
+};
+
+type SignalEntry = {
+    name: string;
+    signature: string;
+    doc: string;
+    origin: string | undefined;
+};
+
+const signalsSection = (entry: GlibNamedClass, context: ElementPageContext, selfType: string): string[] => {
+    const seen = new Set<string>();
+    const entries: SignalEntry[] = [];
+    const acceptSignal = (signal: GirSignal, origin: string | undefined): void => {
+        const name = signalHandlerName(signal.name);
+        if (seen.has(name)) return;
+        seen.add(name);
+        entries.push({
+            name,
+            signature: renderDocsSignalSignature(context.library, signal, selfType),
+            doc: docMarkdown(signal.doc),
+            origin,
+        });
+    };
+    for (const owner of memberOwners(entry, context)) {
+        for (const signal of owner.klass.signals) acceptSignal(signal, owner.origin);
+    }
+    if (entries.length === 0) return [];
+    return ["## Signals", ...originSignatureBlocks(entries)];
+};
+
+const methodsSection = (entry: GlibNamedClass, context: ElementPageContext, selfType: string): string[] => {
+    const entries = classMethodEntries(context.library, entry.namespace, entry.klass);
+    const intro = `Methods are called on the \`${selfType}\` instance, obtained with the \`ref\` prop or imported from \`@gtkx/gi/${namespaceDirectory(entry.namespace)}\`. Methods inherited from ancestors are documented on their own pages.`;
+    return methodsSectionBlocks(entries, intro);
+};
+
+export const renderElementPage = (entry: GlibNamedClass, context: ElementPageContext): string => {
+    const selfType = `${entry.namespace.name}.${entry.klass.name}`;
+    return joinSections([
+        frontmatter(entry),
+        `# ${entry.glibName}`,
+        docMarkdown(entry.klass.doc),
+        importBlock(entry),
+        ...hierarchySection(entry, context),
+        ...childrenSection(entry, context),
+        ...propsSection(entry, context, selfType),
+        ...signalsSection(entry, context, selfType),
+        ...methodsSection(entry, context, selfType),
+    ]);
+};