@gtkx/codegen 1.0.0-rc.4 → 1.0.0

package/src/docs/element-page.ts

@@ -1,11 +1,12 @@
-import { sortStringsBy, toCamelIdentifier, upperFirst } from "@gtkx/utils";
+import { toCamelIdentifier, upperFirst } from "@gtkx/utils";
 import type { GirClass } from "../gir/class.js";
 import type { Library } from "../gir/library.js";
+import type { HandwrittenProp } from "./handwritten-props.js";
 import { ancestorChain } from "../gir/ancestry.js";
 import { type GirNamespace, namespaceDirectory } from "../gir/namespace.js";
 import { type GirProperty, isConstructableProperty } from "../gir/property.js";
+import { annotationSpec } from "../store/gi/doc-spec.js";
 import { elementPropTypeFor } from "../store/jsx/element-prop-imports.js";
-import { buildGirIndex, type GirIndex } from "../store/jsx/gir-index.js";
 import {
     getGlibName,
     type GlibNamedClass,
@@ -15,23 +16,30 @@ import {
 } from "../store/jsx/intrinsic-elements.js";
 import { isOmittedProp } from "../store/jsx/omitted-props.js";
 import { isObjectProp } from "../store/jsx/props.js";
+import { handwrittenPropsFor } from "./handwritten-props.js";
 import {
+    annotationNotes,
     classMethodEntries,
     docMarkdown,
-    docsDefaultValue,
     firstSentence,
     implementsLine,
     joinSections,
-    metaBlock,
+    type MetaDocEntry,
     methodsSectionBlocks,
     originSignatureBlocks,
+    type OriginSignatureEntry,
+    propertyMetaLine,
     renderDocsSignalSignature,
     renderDocsType,
+    signalTags,
+    sortedMetaBlocks,
 } from "./render.js";
 
+/** Shared state an element's reference page renders from. */
 type ElementPageContext = {
+    /** Parsed GIR the element, its ancestors, and the interfaces it implements are read from. */
     library: Library;
-    girIndex: GirIndex;
+    /** Resolves a GLib type name to the URL of its page, undefined when it has none. */
     linkFor: (glibName: string) => string | undefined;
 };
 
@@ -42,24 +50,6 @@ type MemberOwner = {
     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.`;
@@ -120,29 +110,45 @@ const propertyEntry = (
     owner: MemberOwner,
     property: GirProperty,
     jsName: string,
-): PropEntry => {
+): MetaDocEntry => {
     const isObject = isObjectProp(context.library, property);
     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)}\``);
-    }
+    const accessNotes = isConstructableProperty(property)
+        ? []
+        : [`read-only, observe with \`onNotify${upperFirst(jsName)}\``];
 
-    if (property.constructOnly) {
-        meta.push("construct-only");
-    }
+    return {
+        name: jsName,
+        meta: propertyMetaLine({ type, property, accessNotes, origin: owner.origin }),
+        doc: docMarkdown(property.doc),
+        tags: annotationSpec(property.annotations),
+    };
+};
 
-    if (!isConstructableProperty(property)) {
-        meta.push(`read-only, observe with \`onNotify${upperFirst(jsName)}\``);
+const handwrittenPropMeta = (prop: HandwrittenProp, owner: MemberOwner): string =>
+    [`\`${prop.type}\``, ...(owner.origin === undefined ? [] : [`from \`${owner.origin}\``])].join(" · ");
+
+const handwrittenPropEntries = (owner: MemberOwner, seen: Set<string>): MetaDocEntry[] => {
+    const declared = owner.glibName === undefined ? undefined : elementPropTypeFor(owner.glibName);
+
+    if (declared === undefined) {
+        return [];
     }
 
-    if (owner.origin !== undefined) {
-        meta.push(`from \`${owner.origin}\``);
+    const entries: MetaDocEntry[] = [];
+
+    for (const prop of handwrittenPropsFor(declared)) {
+        if (seen.has(prop.name)) {
+            continue;
+        }
+
+        seen.add(prop.name);
+        entries.push({ name: prop.name, meta: handwrittenPropMeta(prop, owner), doc: prop.doc });
     }
 
-    return { name: jsName, meta: meta.join(" · "), doc: docMarkdown(property.doc) };
+    return entries;
 };
 
 const propJsName = (property: GirProperty, owner: MemberOwner, seen: Set<string>): string | undefined => {
@@ -161,8 +167,8 @@ const propJsName = (property: GirProperty, owner: MemberOwner, seen: Set<string>
     return jsName;
 };
 
-const ownerPropEntries = (context: ElementPageContext, owner: MemberOwner, seen: Set<string>): PropEntry[] => {
-    const entries: PropEntry[] = [];
+const ownerPropEntries = (context: ElementPageContext, owner: MemberOwner, seen: Set<string>): MetaDocEntry[] => {
+    const entries: MetaDocEntry[] = [...handwrittenPropEntries(owner, seen)];
 
     for (const property of owner.klass.properties) {
         const jsName = propJsName(property, owner, seen);
@@ -175,8 +181,8 @@ const ownerPropEntries = (context: ElementPageContext, owner: MemberOwner, seen:
     return entries;
 };
 
-const propertyEntries = (entry: GlibNamedClass, context: ElementPageContext, seen: Set<string>): PropEntry[] => {
-    const entries: PropEntry[] = [];
+const propertyEntries = (entry: GlibNamedClass, context: ElementPageContext, seen: Set<string>): MetaDocEntry[] => {
+    const entries: MetaDocEntry[] = [];
 
     for (const owner of memberOwners(entry, context)) {
         entries.push(...ownerPropEntries(context, owner, seen));
@@ -200,9 +206,7 @@ const propsSection = (entry: GlibNamedClass, context: ElementPageContext, selfTy
         return ["## Props", intro];
     }
 
-    const sorted = sortStringsBy(entries, (item) => item.name);
-
-    return ["## Props", intro, ...sorted.map((item) => metaBlock(item.name, item.meta, item.doc))];
+    return ["## Props", intro, ...sortedMetaBlocks(entries)];
 };
 
 const ownerSignalEntries = (
@@ -210,8 +214,8 @@ const ownerSignalEntries = (
     owner: MemberOwner,
     selfType: string,
     seen: Set<string>,
-): SignalEntry[] => {
-    const entries: SignalEntry[] = [];
+): OriginSignatureEntry[] => {
+    const entries: OriginSignatureEntry[] = [];
 
     for (const signal of owner.klass.signals) {
         const name = signalHandlerName(signal.name);
@@ -226,6 +230,7 @@ const ownerSignalEntries = (
             name,
             signature: renderDocsSignalSignature(context.library, signal, selfType),
             doc: docMarkdown(signal.doc),
+            tags: signalTags(signal, true),
             origin: owner.origin,
         });
     }
@@ -235,7 +240,7 @@ const ownerSignalEntries = (
 
 const signalsSection = (entry: GlibNamedClass, context: ElementPageContext, selfType: string): string[] => {
     const seen: Set<string> = new Set();
-    const entries: SignalEntry[] = [];
+    const entries: OriginSignatureEntry[] = [];
 
     for (const owner of memberOwners(entry, context)) {
         entries.push(...ownerSignalEntries(context, owner, selfType, seen));
@@ -266,6 +271,7 @@ const renderElementPage = (entry: GlibNamedClass, context: ElementPageContext):
         frontmatter(entry),
         `# ${entry.glibName}`,
         docMarkdown(entry.klass.doc),
+        ...annotationNotes(entry.klass.annotations),
         importBlock(entry),
         ...hierarchySection(entry, context),
         ...propsSection(entry, context, selfType),
@@ -274,4 +280,4 @@ const renderElementPage = (entry: GlibNamedClass, context: ElementPageContext):
     ]);
 };
 
-export { createElementPageContext, renderElementPage, type ElementPageContext };
+export { renderElementPage, type ElementPageContext };

package/src/docs/handwritten-props.ts

@@ -0,0 +1,230 @@
+import type { ModuleExport } from "@gtkx/react/config";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+
+type HandwrittenProp = {
+    name: string;
+    type: string;
+    doc: string;
+};
+
+type AliasSite = {
+    sourceFile: ts.SourceFile;
+    declaration: ts.TypeAliasDeclaration;
+};
+
+type NamedBinding = ts.ImportSpecifier | ts.ExportSpecifier;
+
+const RESOLUTION_OPTIONS: ts.CompilerOptions = {
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    customConditions: ["source"],
+};
+
+const CONTAINING_FILE = fileURLToPath(import.meta.url);
+const WHITESPACE_RUN = /\s+/g;
+const propsByRef: Map<string, HandwrittenProp[]> = new Map();
+
+const moduleFileFor = (specifier: string, containingFile: string): string | undefined =>
+    ts.resolveModuleName(specifier, containingFile, RESOLUTION_OPTIONS, ts.sys).resolvedModule?.resolvedFileName;
+
+const parseModule = (filePath: string): ts.SourceFile =>
+    ts.createSourceFile(filePath, ts.sys.readFile(filePath) ?? "", ts.ScriptTarget.Latest, true);
+
+const specifierText = (node: ts.Expression | undefined): string | undefined =>
+    node !== undefined && ts.isStringLiteral(node) ? node.text : undefined;
+
+const boundName = (elements: readonly NamedBinding[], name: string): string | undefined => {
+    for (const element of elements) {
+        if (element.name.text === name) {
+            return (element.propertyName ?? element.name).text;
+        }
+    }
+
+    return undefined;
+};
+
+const findAliasInModule = (specifier: string, sourceFile: ts.SourceFile, name: string): AliasSite | undefined => {
+    const filePath = moduleFileFor(specifier, sourceFile.fileName);
+
+    return filePath === undefined ? undefined : findAlias(parseModule(filePath), name);
+};
+
+const importedAlias = (
+    statement: ts.ImportDeclaration,
+    sourceFile: ts.SourceFile,
+    name: string,
+): AliasSite | undefined => {
+    const bindings = statement.importClause?.namedBindings;
+    const specifier = specifierText(statement.moduleSpecifier);
+
+    if (specifier === undefined || bindings === undefined || !ts.isNamedImports(bindings)) {
+        return undefined;
+    }
+
+    const imported = boundName(bindings.elements, name);
+
+    return imported === undefined ? undefined : findAliasInModule(specifier, sourceFile, imported);
+};
+
+const exportedAlias = (
+    statement: ts.ExportDeclaration,
+    sourceFile: ts.SourceFile,
+    name: string,
+): AliasSite | undefined => {
+    const specifier = specifierText(statement.moduleSpecifier);
+
+    if (specifier === undefined) {
+        return undefined;
+    }
+
+    const clause = statement.exportClause;
+
+    if (clause === undefined) {
+        return findAliasInModule(specifier, sourceFile, name);
+    }
+
+    const exported = ts.isNamedExports(clause) ? boundName(clause.elements, name) : undefined;
+
+    return exported === undefined ? undefined : findAliasInModule(specifier, sourceFile, exported);
+};
+
+const statementAlias = (statement: ts.Statement, sourceFile: ts.SourceFile, name: string): AliasSite | undefined => {
+    if (ts.isTypeAliasDeclaration(statement)) {
+        return statement.name.text === name ? { sourceFile, declaration: statement } : undefined;
+    }
+
+    if (ts.isImportDeclaration(statement)) {
+        return importedAlias(statement, sourceFile, name);
+    }
+
+    return ts.isExportDeclaration(statement) ? exportedAlias(statement, sourceFile, name) : undefined;
+};
+
+const propType = (type: ts.TypeNode, sourceFile: ts.SourceFile): string => {
+    const parts: readonly ts.TypeNode[] = ts.isUnionTypeNode(type) ? type.types : [type];
+
+    return parts
+        .filter((part) => part.kind !== ts.SyntaxKind.UndefinedKeyword)
+        .map((part) => part.getText(sourceFile).replaceAll(WHITESPACE_RUN, " "))
+        .join(" | ");
+};
+
+const propDoc = (member: ts.TypeElement): string => {
+    const comments = ts
+        .getJSDocCommentsAndTags(member)
+        .map((node) => (ts.isJSDoc(node) ? ts.getTextOfJSDocComment(node.comment) : undefined));
+
+    return comments.filter((text) => text !== undefined).join(" ").replaceAll(WHITESPACE_RUN, " ").trim();
+};
+
+const propertyProp = (member: ts.PropertySignature, sourceFile: ts.SourceFile): HandwrittenProp | undefined => {
+    const { name, type } = member;
+
+    if (type === undefined || !(ts.isIdentifier(name) || ts.isStringLiteral(name))) {
+        return undefined;
+    }
+
+    return { name: name.text, type: propType(type, sourceFile), doc: propDoc(member) };
+};
+
+const indexProp = (member: ts.IndexSignatureDeclaration, sourceFile: ts.SourceFile): HandwrittenProp | undefined => {
+    const keyType = member.parameters[0]?.type;
+
+    if (keyType === undefined) {
+        return undefined;
+    }
+
+    return {
+        name: keyType.getText(sourceFile).replaceAll("`", ""),
+        type: propType(member.type, sourceFile),
+        doc: propDoc(member),
+    };
+};
+
+const memberProp = (member: ts.TypeElement, sourceFile: ts.SourceFile): HandwrittenProp | undefined => {
+    if (ts.isPropertySignature(member)) {
+        return propertyProp(member, sourceFile);
+    }
+
+    return ts.isIndexSignatureDeclaration(member) ? indexProp(member, sourceFile) : undefined;
+};
+
+const literalProps = (type: ts.TypeLiteralNode, sourceFile: ts.SourceFile): HandwrittenProp[] => {
+    const props: HandwrittenProp[] = [];
+
+    for (const member of type.members) {
+        const prop = memberProp(member, sourceFile);
+
+        if (prop !== undefined) {
+            props.push(prop);
+        }
+    }
+
+    return props;
+};
+
+const referenceProps = (type: ts.TypeReferenceNode, sourceFile: ts.SourceFile): HandwrittenProp[] => {
+    if (!ts.isIdentifier(type.typeName)) {
+        return [];
+    }
+
+    const site = findAlias(sourceFile, type.typeName.text);
+
+    return site === undefined ? [] : typeNodeProps(site.declaration.type, site.sourceFile);
+};
+
+const declaredProps = (ref: ModuleExport): HandwrittenProp[] => {
+    const filePath = moduleFileFor(ref.module, CONTAINING_FILE);
+
+    if (filePath === undefined) {
+        throw new Error(`Cannot resolve ${ref.module}, which declares the ${ref.export} element props`);
+    }
+
+    const site = findAlias(parseModule(filePath), ref.export);
+
+    if (site === undefined) {
+        throw new Error(`${ref.module} declares no type named ${ref.export}`);
+    }
+
+    return typeNodeProps(site.declaration.type, site.sourceFile);
+};
+
+const handwrittenPropsFor = (ref: ModuleExport): HandwrittenProp[] => {
+    const key = `${ref.module}#${ref.export}`;
+    const cached = propsByRef.get(key);
+
+    if (cached !== undefined) {
+        return cached;
+    }
+
+    const props = declaredProps(ref);
+    propsByRef.set(key, props);
+
+    return props;
+};
+
+function findAlias(sourceFile: ts.SourceFile, name: string): AliasSite | undefined {
+    for (const statement of sourceFile.statements) {
+        const site = statementAlias(statement, sourceFile, name);
+
+        if (site !== undefined) {
+            return site;
+        }
+    }
+
+    return undefined;
+}
+
+function typeNodeProps(type: ts.TypeNode, sourceFile: ts.SourceFile): HandwrittenProp[] {
+    if (ts.isTypeLiteralNode(type)) {
+        return literalProps(type, sourceFile);
+    }
+
+    if (ts.isIntersectionTypeNode(type)) {
+        return type.types.flatMap((part) => typeNodeProps(part, sourceFile));
+    }
+
+    return ts.isTypeReferenceNode(type) ? referenceProps(type, sourceFile) : [];
+}
+
+export { handwrittenPropsFor, type HandwrittenProp };

package/src/docs/pipeline.ts

@@ -7,7 +7,7 @@ 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 { type OmittedProps, setOmittedProps } from "../store/jsx/omitted-props.js";
-import { createElementPageContext, type ElementPageContext, renderElementPage } from "./element-page.js";
+import { type ElementPageContext, renderElementPage } from "./element-page.js";
 import { elementSlug, firstSentence, namespaceOrder } from "./render.js";
 
 type DocsElementLink = {
@@ -175,7 +175,7 @@ const generatePages = (options: DocsOptions, basePath: string, library: Library)
     const intrinsicElements = collectIntrinsicElementClasses(library);
     const byNamespace = groupElementsByNamespace(intrinsicElements);
     const linkByGlibName = buildElementLinks(intrinsicElements, basePath);
-    const pageContext = createElementPageContext(library, (glibName: string) => linkByGlibName.get(glibName));
+    const pageContext: ElementPageContext = { library, linkFor: (glibName) => linkByGlibName.get(glibName) };
     const pages: Page[] = [];
     const namespaces: DocsNamespace[] = [];
     const orderedNames = sortStringsBy(byNamespace.keys(), namespaceOrder);