@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/src/docs/element-page.ts

@@ -0,0 +1,281 @@
+import { sortStringsBy, toCamelIdentifier, upperFirst } from "@gtkx/utils";
+import type { GirClass } from "../gir/class.js";
+import type { Library } from "../gir/library.js";
+import { ancestorChain } from "../gir/ancestry.js";
+import { type GirNamespace, namespaceDirectory } from "../gir/namespace.js";
+import { type GirProperty, isConstructableProperty } from "../gir/property.js";
+import { elementPropTypeFor } from "../store/jsx/element-prop-imports.js";
+import { buildGirIndex, type GirIndex } from "../store/jsx/gir-index.js";
+import {
+    getGlibName,
+    type GlibNamedClass,
+    implementedInterfaces,
+    newlyImplementedInterfaces,
+    signalHandlerName,
+} from "../store/jsx/intrinsic-elements.js";
+import { isObjectProp } from "../store/jsx/props.js";
+import {
+    classMethodEntries,
+    docMarkdown,
+    docsDefaultValue,
+    firstSentence,
+    implementsLine,
+    joinSections,
+    metaBlock,
+    methodsSectionBlocks,
+    originSignatureBlocks,
+    renderDocsSignalSignature,
+    renderDocsType,
+} from "./render.js";
+
+type ElementPageContext = {
+    library: Library;
+    girIndex: GirIndex;
+    linkFor: (glibName: string) => string | undefined;
+};
+
+type MemberOwner = {
+    klass: GirClass;
+    namespace: GirNamespace;
+    origin: string | undefined;
+    glibName: string | undefined;
+};
+
+type PropEntry = {
+    name: string;
+    meta: string;
+    doc: string;
+};
+
+type SignalEntry = {
+    name: string;
+    signature: string;
+    doc: string;
+    origin: string | undefined;
+};
+
+const createElementPageContext = (
+    library: Library,
+    linkFor: (glibName: string) => string | undefined,
+): ElementPageContext => ({ library, girIndex: buildGirIndex(library), linkFor });
+
+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).toReversed();
+
+    if (ancestors.length === 0) {
+        return [];
+    }
+
+    const parts = ancestors.map((ancestor) => {
+        const glib = getGlibName(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) => getGlibName(iface.klass))
+        .filter((name): name is string => name !== undefined);
+
+    lines.push(...implementsLine(interfaces));
+
+    return lines;
+};
+
+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 && elementPropTypeFor(glibName) !== undefined,
+    ).map((iface) => {
+        const glibName = getGlibName(iface.klass);
+
+        return { klass: iface.klass, namespace: iface.namespace, origin: glibName, glibName };
+    }),
+];
+
+const propertyEntry = (
+    context: ElementPageContext,
+    owner: MemberOwner,
+    property: GirProperty,
+    jsName: string,
+): PropEntry => {
+    const isObject = isObjectProp(
+        { library: context.library, klass: owner.klass, namespace: owner.namespace },
+        property,
+        jsName,
+    );
+
+    const baseType = renderDocsType(context.library, property.type, false);
+    const type = isObject ? `${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 propJsName = (property: GirProperty, seen: Set<string>): string | undefined => {
+    if (!property.introspectable) {
+        return undefined;
+    }
+
+    const jsName = toCamelIdentifier(property.name);
+
+    if (seen.has(jsName)) {
+        return undefined;
+    }
+
+    seen.add(jsName);
+
+    return jsName;
+};
+
+const ownerPropEntries = (context: ElementPageContext, owner: MemberOwner, seen: Set<string>): PropEntry[] => {
+    const entries: PropEntry[] = [];
+
+    for (const property of owner.klass.properties) {
+        const jsName = propJsName(property, seen);
+
+        if (jsName !== undefined) {
+            entries.push(propertyEntry(context, owner, property, jsName));
+        }
+    }
+
+    return entries;
+};
+
+const propertyEntries = (entry: GlibNamedClass, context: ElementPageContext, seen: Set<string>): PropEntry[] => {
+    const entries: PropEntry[] = [];
+
+    for (const owner of memberOwners(entry, context)) {
+        entries.push(...ownerPropEntries(context, owner, seen));
+    }
+
+    return entries;
+};
+
+const propsSection = (entry: GlibNamedClass, context: ElementPageContext, selfType: string): string[] => {
+    const seen: Set<string> = new Set();
+    const entries = propertyEntries(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))];
+};
+
+const ownerSignalEntries = (
+    context: ElementPageContext,
+    owner: MemberOwner,
+    selfType: string,
+    seen: Set<string>,
+): SignalEntry[] => {
+    const entries: SignalEntry[] = [];
+
+    for (const signal of owner.klass.signals) {
+        const name = signalHandlerName(signal.name);
+
+        if (seen.has(name)) {
+            continue;
+        }
+
+        seen.add(name);
+
+        entries.push({
+            name,
+            signature: renderDocsSignalSignature(context.library, signal, selfType),
+            doc: docMarkdown(signal.doc),
+            origin: owner.origin,
+        });
+    }
+
+    return entries;
+};
+
+const signalsSection = (entry: GlibNamedClass, context: ElementPageContext, selfType: string): string[] => {
+    const seen: Set<string> = new Set();
+    const entries: SignalEntry[] = [];
+
+    for (const owner of memberOwners(entry, context)) {
+        entries.push(...ownerSignalEntries(context, owner, selfType, seen));
+    }
+
+    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 importPath = `@gtkx/gi/${namespaceDirectory(entry.namespace)}`;
+
+    const intro =
+        `Methods are called on the \`${selfType}\` instance, obtained with the \`ref\` prop or ` +
+        `imported from \`${importPath}\`. Methods inherited from ancestors are documented on their own pages.`;
+
+    return methodsSectionBlocks(entries, intro);
+};
+
+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),
+        ...propsSection(entry, context, selfType),
+        ...signalsSection(entry, context, selfType),
+        ...methodsSection(entry, context, selfType),
+    ]);
+};
+
+export { createElementPageContext, renderElementPage, type ElementPageContext };

package/src/docs/pipeline.ts

@@ -0,0 +1,241 @@
+import { sortStringsBy } from "@gtkx/utils";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { computeGiFingerprint, FINGERPRINT_FILENAME, isGiStoreFresh } from "../fingerprint.js";
+import { Library } from "../gir/library.js";
+import { namespaceDirectory } from "../gir/namespace.js";
+import { type ElementProps, setElementProps } from "../store/jsx/element-prop-imports.js";
+import { collectIntrinsicElementClasses, type GlibNamedClass } from "../store/jsx/intrinsic-elements.js";
+import { createElementPageContext, type ElementPageContext, renderElementPage } from "./element-page.js";
+import { elementSlug, firstSentence, namespaceOrder } from "./render.js";
+
+type DocsElementLink = {
+    text: string;
+    link: string;
+};
+
+type DocsNamespace = {
+    name: string;
+    directory: string;
+    link: string;
+    elements: DocsElementLink[];
+};
+
+type DocsOptions = {
+    libraries: string[];
+    girPath: string[];
+    outDir: string;
+    basePath?: string;
+    props?: ElementProps;
+    force?: boolean;
+};
+
+type DocsManifest = {
+    namespaces: DocsNamespace[];
+};
+
+type GeneratedDocs = {
+    pages: { path: string; content: string }[];
+    namespaces: DocsNamespace[];
+};
+
+type Page = { path: string; content: string };
+type NamespacePages = { docs: DocsNamespace; pages: Page[] };
+
+type DocsResult = {
+    regenerated: boolean;
+    namespaces: DocsNamespace[];
+};
+
+const MANIFEST_FILENAME = "manifest.json";
+
+const namespaceIndexPage = (namespace: DocsNamespace, elements: GlibNamedClass[]): string => {
+    const rows = elements.map((entry, index) => {
+        const link = namespace.elements[index]?.link ?? "";
+        const description = firstSentence(entry.klass.doc).replaceAll("|", String.raw`\|`);
+
+        return `| [${entry.glibName}](${link}) | ${description} |`;
+    });
+
+    const description =
+        `Reference pages for the ${String(namespace.elements.length)} JSX elements in ` +
+        `the ${namespace.name} namespace.`;
+
+    return [
+        "---",
+        `description: ${JSON.stringify(description)}`,
+        "---",
+        "",
+        `# ${namespace.name} elements`,
+        "",
+        `Elements in this namespace are imported from \`@gtkx/jsx/${namespace.directory}\`; the matching ` +
+        `classes, enums, and functions are imported from \`@gtkx/gi/${namespace.directory}\`.`,
+        "",
+        "| Element | Description |",
+        "| --- | --- |",
+        ...rows,
+        "",
+    ].join("\n");
+};
+
+const rootIndexPage = (namespaces: DocsNamespace[], libraries: string[]): string => {
+    const rows = namespaces.map(
+        (ns) => `| [${ns.name}](${ns.link}) | \`@gtkx/jsx/${ns.directory}\` | ${String(ns.elements.length)} |`,
+    );
+
+    const librariesList = libraries.map((library) => `\`${library}\``).join(", ");
+
+    return [
+        "---",
+        "description: \"Generated reference documentation for every JSX element in this project's GIR libraries.\"",
+        "---",
+        "",
+        "# Element Reference",
+        "",
+        "This reference documents every JSX element generated from the GObject-Introspection data for " +
+        `${librariesList}, together with the namespaces they pull in. It is produced by \`gtkx docs\` ` +
+        "using the same pipeline that generates the `@gtkx/jsx` and `@gtkx/gi` bindings, so every page " +
+        "matches the types your editor sees.",
+        "",
+        "Each element page lists:",
+        "",
+        "- **Props** derived from GObject properties, plus the element props GTKX adds (such as `children` " +
+        "and named slots), with types, defaults, and upstream documentation.",
+        "- **Signals** as `on<Signal>` handler props with their exact handler signatures.",
+        "- **Methods** available on the underlying instance through the `ref` prop.",
+        "",
+        "## Namespaces",
+        "",
+        "| Namespace | Import | Elements |",
+        "| --- | --- | --- |",
+        ...rows,
+        "",
+    ].join("\n");
+};
+
+const groupElementsByNamespace = (elements: GlibNamedClass[]): Map<string, GlibNamedClass[]> => {
+    const byNamespace: Map<string, GlibNamedClass[]> = new Map();
+
+    for (const entry of elements) {
+        const list = byNamespace.get(entry.namespace.name) ?? [];
+        list.push(entry);
+        byNamespace.set(entry.namespace.name, list);
+    }
+
+    return byNamespace;
+};
+
+const buildElementLinks = (elements: GlibNamedClass[], basePath: string): Map<string, string> => {
+    const linkByGlibName: Map<string, string> = new Map();
+
+    for (const entry of elements) {
+        const directory = namespaceDirectory(entry.namespace);
+        const link = `${basePath}/${directory}/${elementSlug(entry.klass.name)}`;
+
+        if (linkByGlibName.values().some((existing) => existing === link)) {
+            throw new Error(`Docs page slug collision for ${entry.glibName} at ${link}`);
+        }
+
+        linkByGlibName.set(entry.glibName, link);
+    }
+
+    return linkByGlibName;
+};
+
+const namespacePages = (input: {
+    name: string;
+    elements: GlibNamedClass[];
+    basePath: string;
+    linkByGlibName: Map<string, string>;
+    pageContext: ElementPageContext;
+}): NamespacePages => {
+    const { name, elements, basePath, linkByGlibName, pageContext } = input;
+    const directory = name.toLowerCase();
+
+    const docs: DocsNamespace = {
+        name,
+        directory,
+        link: `${basePath}/${directory}/`,
+        elements: elements.map((entry) => ({ text: entry.glibName, link: linkByGlibName.get(entry.glibName) ?? "" })),
+    };
+
+    const pages: Page[] = elements.map((entry) => ({
+        path: `${directory}/${elementSlug(entry.klass.name)}.md`,
+        content: renderElementPage(entry, pageContext),
+    }));
+
+    pages.push({ path: `${directory}/index.md`, content: namespaceIndexPage(docs, elements) });
+
+    return { docs, pages };
+};
+
+const generatePages = (options: DocsOptions, basePath: string, library: Library): GeneratedDocs => {
+    const intrinsicElements = collectIntrinsicElementClasses(library);
+    const byNamespace = groupElementsByNamespace(intrinsicElements);
+    const linkByGlibName = buildElementLinks(intrinsicElements, basePath);
+    const pageContext = createElementPageContext(library, (glibName: string) => linkByGlibName.get(glibName));
+    const pages: Page[] = [];
+    const namespaces: DocsNamespace[] = [];
+    const orderedNames = sortStringsBy(byNamespace.keys(), namespaceOrder);
+
+    for (const name of orderedNames) {
+        const elements = sortStringsBy(byNamespace.get(name) ?? [], (entry) => entry.glibName);
+        const result = namespacePages({ name, elements, basePath, linkByGlibName, pageContext });
+        pages.push(...result.pages);
+        namespaces.push(result.docs);
+    }
+
+    pages.push({ path: "index.md", content: rootIndexPage(namespaces, options.libraries) });
+
+    return { pages, namespaces };
+};
+
+const cachedDocsResult = (options: DocsOptions, manifestPath: string): DocsResult | undefined => {
+    if (options.force === true || !isGiStoreFresh(options.outDir, options.libraries, options.girPath)) {
+        return undefined;
+    }
+
+    if (!existsSync(manifestPath)) {
+        return undefined;
+    }
+
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as DocsManifest;
+
+    return { regenerated: false, namespaces: manifest.namespaces };
+};
+
+const writePages = (outDir: string, pages: Page[]): void => {
+    for (const page of pages) {
+        const target = join(outDir, page.path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, page.content);
+    }
+};
+
+const writeDocs = (options: DocsOptions): DocsResult => {
+    setElementProps(options.props ?? {});
+    const basePath = options.basePath ?? "/reference";
+    const manifestPath = join(options.outDir, MANIFEST_FILENAME);
+    const cached = cachedDocsResult(options, manifestPath);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const library = Library.load(options.libraries, options.girPath);
+    const { pages, namespaces } = generatePages(options, basePath, library);
+    rmSync(options.outDir, { recursive: true, force: true });
+    mkdirSync(options.outDir, { recursive: true });
+    writePages(options.outDir, pages);
+    const manifest: DocsManifest = { namespaces };
+    writeFileSync(manifestPath, JSON.stringify(manifest));
+
+    writeFileSync(
+        join(options.outDir, FINGERPRINT_FILENAME),
+        JSON.stringify(computeGiFingerprint(library.girFiles, options.libraries, options.girPath)),
+    );
+
+    return { regenerated: true, namespaces };
+};
+
+export { writeDocs, type DocsElementLink, type DocsNamespace, type DocsOptions, type DocsResult };