@gtkx/codegen 0.21.0 → 1.0.0-rc.2

package/dist/docs/element-page.js

@@ -0,0 +1,156 @@
+import { sortStringsBy, toCamelIdentifier, upperFirst } from "@gtkx/utils";
+import { ancestorChain } from "../gir/ancestry.js";
+import { namespaceDirectory } from "../gir/namespace.js";
+import { isConstructableProperty } from "../gir/property.js";
+import { elementPropTypeFor } from "../store/jsx/element-prop-imports.js";
+import { buildGirIndex } from "../store/jsx/gir-index.js";
+import { getGlibName, 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";
+const createElementPageContext = (library, linkFor) => ({ library, girIndex: buildGirIndex(library), linkFor });
+const frontmatter = (entry) => {
+    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) => `\`\`\`tsx\nimport { ${entry.glibName} } from "@gtkx/jsx/${namespaceDirectory(entry.namespace)}";\n\`\`\``;
+const glibLabel = (context, glibName) => {
+    const link = context.linkFor(glibName);
+    return link === undefined ? `\`${glibName}\`` : `[${glibName}](${link})`;
+};
+const hierarchySection = (entry, context) => {
+    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 !== undefined);
+    lines.push(...implementsLine(interfaces));
+    return lines;
+};
+const memberOwners = (entry, context) => [
+    { 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, owner, property, jsName) => {
+    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 = [`\`${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, seen) => {
+    if (!property.introspectable) {
+        return undefined;
+    }
+    const jsName = toCamelIdentifier(property.name);
+    if (seen.has(jsName)) {
+        return undefined;
+    }
+    seen.add(jsName);
+    return jsName;
+};
+const ownerPropEntries = (context, owner, seen) => {
+    const entries = [];
+    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, context, seen) => {
+    const entries = [];
+    for (const owner of memberOwners(entry, context)) {
+        entries.push(...ownerPropEntries(context, owner, seen));
+    }
+    return entries;
+};
+const propsSection = (entry, context, selfType) => {
+    const seen = 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, owner, selfType, seen) => {
+    const entries = [];
+    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, context, selfType) => {
+    const seen = new Set();
+    const entries = [];
+    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, context, selfType) => {
+    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, context) => {
+    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 };
+//# sourceMappingURL=element-page.js.map

package/dist/docs/element-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-page.js","sourceRoot":"","sources":["../../src/docs/element-page.ts"],"names":[],"mappings":"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","sourcesContent":["import { sortStringsBy, toCamelIdentifier, upperFirst } from \"@gtkx/utils\";\nimport type { GirClass } from \"../gir/class.js\";\nimport type { Library } from \"../gir/library.js\";\nimport { ancestorChain } from \"../gir/ancestry.js\";\nimport { type GirNamespace, namespaceDirectory } from \"../gir/namespace.js\";\nimport { type GirProperty, isConstructableProperty } from \"../gir/property.js\";\nimport { elementPropTypeFor } from \"../store/jsx/element-prop-imports.js\";\nimport { buildGirIndex, type GirIndex } from \"../store/jsx/gir-index.js\";\nimport {\n    getGlibName,\n    type GlibNamedClass,\n    implementedInterfaces,\n    newlyImplementedInterfaces,\n    signalHandlerName,\n} from \"../store/jsx/intrinsic-elements.js\";\nimport { isObjectProp } from \"../store/jsx/props.js\";\nimport {\n    classMethodEntries,\n    docMarkdown,\n    docsDefaultValue,\n    firstSentence,\n    implementsLine,\n    joinSections,\n    metaBlock,\n    methodsSectionBlocks,\n    originSignatureBlocks,\n    renderDocsSignalSignature,\n    renderDocsType,\n} from \"./render.js\";\n\ntype ElementPageContext = {\n    library: Library;\n    girIndex: GirIndex;\n    linkFor: (glibName: string) => string | undefined;\n};\n\ntype MemberOwner = {\n    klass: GirClass;\n    namespace: GirNamespace;\n    origin: string | undefined;\n    glibName: string | undefined;\n};\n\ntype PropEntry = {\n    name: string;\n    meta: string;\n    doc: string;\n};\n\ntype SignalEntry = {\n    name: string;\n    signature: string;\n    doc: string;\n    origin: string | undefined;\n};\n\nconst createElementPageContext = (\n    library: Library,\n    linkFor: (glibName: string) => string | undefined,\n): ElementPageContext => ({ library, girIndex: buildGirIndex(library), linkFor });\n\nconst frontmatter = (entry: GlibNamedClass): string => {\n    const sentence = firstSentence(entry.klass.doc);\n    const description = sentence.length > 0 ? sentence : `API reference for the ${entry.glibName} element.`;\n\n    return `---\\ndescription: ${JSON.stringify(description)}\\n---`;\n};\n\nconst importBlock = (entry: GlibNamedClass): string =>\n    `\\`\\`\\`tsx\\nimport { ${entry.glibName} } from \"@gtkx/jsx/${namespaceDirectory(entry.namespace)}\";\\n\\`\\`\\``;\n\nconst glibLabel = (context: ElementPageContext, glibName: string): string => {\n    const link = context.linkFor(glibName);\n\n    return link === undefined ? `\\`${glibName}\\`` : `[${glibName}](${link})`;\n};\n\nconst hierarchySection = (entry: GlibNamedClass, context: ElementPageContext): string[] => {\n    const ancestors = [...ancestorChain(context.library, entry.klass, entry.namespace.name)].slice(1).toReversed();\n\n    if (ancestors.length === 0) {\n        return [];\n    }\n\n    const parts = ancestors.map((ancestor) => {\n        const glib = getGlibName(ancestor.klass);\n\n        return glib === undefined ? `\\`${ancestor.namespaceName}.${ancestor.klass.name}\\`` : glibLabel(context, glib);\n    });\n\n    parts.push(`**${entry.glibName}**`);\n    const lines = [\"## Hierarchy\", parts.join(\" → \")];\n\n    const interfaces = implementedInterfaces(entry.klass, entry.namespace, context.library)\n        .map((iface) => getGlibName(iface.klass))\n        .filter((name): name is string => name !== undefined);\n\n    lines.push(...implementsLine(interfaces));\n\n    return lines;\n};\n\nconst memberOwners = (entry: GlibNamedClass, context: ElementPageContext): MemberOwner[] => [\n    { klass: entry.klass, namespace: entry.namespace, origin: undefined, glibName: entry.glibName },\n    ...newlyImplementedInterfaces(\n        entry.klass,\n        entry.namespace,\n        context.library,\n        (glibName) => glibName !== undefined && elementPropTypeFor(glibName) !== undefined,\n    ).map((iface) => {\n        const glibName = getGlibName(iface.klass);\n\n        return { klass: iface.klass, namespace: iface.namespace, origin: glibName, glibName };\n    }),\n];\n\nconst propertyEntry = (\n    context: ElementPageContext,\n    owner: MemberOwner,\n    property: GirProperty,\n    jsName: string,\n): PropEntry => {\n    const isObject = isObjectProp(\n        { library: context.library, klass: owner.klass, namespace: owner.namespace },\n        property,\n        jsName,\n    );\n\n    const baseType = renderDocsType(context.library, property.type, false);\n    const type = isObject ? `${baseType} | ReactElement` : baseType;\n    const meta: string[] = [`\\`${type}\\``];\n\n    if (property.defaultValue !== undefined) {\n        meta.push(`default \\`${docsDefaultValue(property.defaultValue)}\\``);\n    }\n\n    if (property.constructOnly) {\n        meta.push(\"construct-only\");\n    }\n\n    if (!isConstructableProperty(property)) {\n        meta.push(`read-only, observe with \\`onNotify${upperFirst(jsName)}\\``);\n    }\n\n    if (owner.origin !== undefined) {\n        meta.push(`from \\`${owner.origin}\\``);\n    }\n\n    return { name: jsName, meta: meta.join(\" · \"), doc: docMarkdown(property.doc) };\n};\n\nconst propJsName = (property: GirProperty, seen: Set<string>): string | undefined => {\n    if (!property.introspectable) {\n        return undefined;\n    }\n\n    const jsName = toCamelIdentifier(property.name);\n\n    if (seen.has(jsName)) {\n        return undefined;\n    }\n\n    seen.add(jsName);\n\n    return jsName;\n};\n\nconst ownerPropEntries = (context: ElementPageContext, owner: MemberOwner, seen: Set<string>): PropEntry[] => {\n    const entries: PropEntry[] = [];\n\n    for (const property of owner.klass.properties) {\n        const jsName = propJsName(property, seen);\n\n        if (jsName !== undefined) {\n            entries.push(propertyEntry(context, owner, property, jsName));\n        }\n    }\n\n    return entries;\n};\n\nconst propertyEntries = (entry: GlibNamedClass, context: ElementPageContext, seen: Set<string>): PropEntry[] => {\n    const entries: PropEntry[] = [];\n\n    for (const owner of memberOwners(entry, context)) {\n        entries.push(...ownerPropEntries(context, owner, seen));\n    }\n\n    return entries;\n};\n\nconst propsSection = (entry: GlibNamedClass, context: ElementPageContext, selfType: string): string[] => {\n    const seen: Set<string> = new Set();\n    const entries = propertyEntries(entry, context, seen);\n\n    const intro = [\n        `\\`ref\\` receives the \\`${selfType}\\` instance.`,\n        \"Every mutable property also has an `onNotify<Prop>` handler prop called with the new value \" +\n        \"when the property changes.\",\n        \"Props inherited from ancestor elements are documented on their own pages.\",\n    ].join(\" \");\n\n    if (entries.length === 0) {\n        return [\"## Props\", intro];\n    }\n\n    const sorted = sortStringsBy(entries, (item) => item.name);\n\n    return [\"## Props\", intro, ...sorted.map((item) => metaBlock(item.name, item.meta, item.doc))];\n};\n\nconst ownerSignalEntries = (\n    context: ElementPageContext,\n    owner: MemberOwner,\n    selfType: string,\n    seen: Set<string>,\n): SignalEntry[] => {\n    const entries: SignalEntry[] = [];\n\n    for (const signal of owner.klass.signals) {\n        const name = signalHandlerName(signal.name);\n\n        if (seen.has(name)) {\n            continue;\n        }\n\n        seen.add(name);\n\n        entries.push({\n            name,\n            signature: renderDocsSignalSignature(context.library, signal, selfType),\n            doc: docMarkdown(signal.doc),\n            origin: owner.origin,\n        });\n    }\n\n    return entries;\n};\n\nconst signalsSection = (entry: GlibNamedClass, context: ElementPageContext, selfType: string): string[] => {\n    const seen: Set<string> = new Set();\n    const entries: SignalEntry[] = [];\n\n    for (const owner of memberOwners(entry, context)) {\n        entries.push(...ownerSignalEntries(context, owner, selfType, seen));\n    }\n\n    if (entries.length === 0) {\n        return [];\n    }\n\n    return [\"## Signals\", ...originSignatureBlocks(entries)];\n};\n\nconst methodsSection = (entry: GlibNamedClass, context: ElementPageContext, selfType: string): string[] => {\n    const entries = classMethodEntries(context.library, entry.namespace, entry.klass);\n    const importPath = `@gtkx/gi/${namespaceDirectory(entry.namespace)}`;\n\n    const intro =\n        `Methods are called on the \\`${selfType}\\` instance, obtained with the \\`ref\\` prop or ` +\n        `imported from \\`${importPath}\\`. Methods inherited from ancestors are documented on their own pages.`;\n\n    return methodsSectionBlocks(entries, intro);\n};\n\nconst renderElementPage = (entry: GlibNamedClass, context: ElementPageContext): string => {\n    const selfType = `${entry.namespace.name}.${entry.klass.name}`;\n\n    return joinSections([\n        frontmatter(entry),\n        `# ${entry.glibName}`,\n        docMarkdown(entry.klass.doc),\n        importBlock(entry),\n        ...hierarchySection(entry, context),\n        ...propsSection(entry, context, selfType),\n        ...signalsSection(entry, context, selfType),\n        ...methodsSection(entry, context, selfType),\n    ]);\n};\n\nexport { createElementPageContext, renderElementPage, type ElementPageContext };\n"]}

package/dist/docs/pipeline.d.ts

@@ -0,0 +1,26 @@
+import { type ElementProps } from "../store/jsx/element-prop-imports.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 DocsResult = {
+    regenerated: boolean;
+    namespaces: DocsNamespace[];
+};
+declare const writeDocs: (options: DocsOptions) => DocsResult;
+export { writeDocs, type DocsElementLink, type DocsNamespace, type DocsOptions, type DocsResult };
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/docs/pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/docs/pipeline.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,YAAY,EAAmB,MAAM,sCAAsC,CAAC;AAK1F,KAAK,eAAe,GAAG;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,KAAK,aAAa,GAAG;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC/B,CAAC;AAEF,KAAK,WAAW,GAAG;IACf,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAcF,KAAK,UAAU,GAAG;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,aAAa,EAAE,CAAC;CAC/B,CAAC;AAuKF,QAAA,MAAM,SAAS,GAAI,SAAS,WAAW,KAAG,UAwBzC,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,CAAC"}

package/dist/docs/pipeline.js

@@ -0,0 +1,156 @@
+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 { setElementProps } from "../store/jsx/element-prop-imports.js";
+import { collectIntrinsicElementClasses } from "../store/jsx/intrinsic-elements.js";
+import { createElementPageContext, renderElementPage } from "./element-page.js";
+import { elementSlug, firstSentence, namespaceOrder } from "./render.js";
+const MANIFEST_FILENAME = "manifest.json";
+const namespaceIndexPage = (namespace, elements) => {
+    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, libraries) => {
+    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) => {
+    const byNamespace = 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, basePath) => {
+    const linkByGlibName = 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) => {
+    const { name, elements, basePath, linkByGlibName, pageContext } = input;
+    const directory = name.toLowerCase();
+    const docs = {
+        name,
+        directory,
+        link: `${basePath}/${directory}/`,
+        elements: elements.map((entry) => ({ text: entry.glibName, link: linkByGlibName.get(entry.glibName) ?? "" })),
+    };
+    const pages = 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, basePath, library) => {
+    const intrinsicElements = collectIntrinsicElementClasses(library);
+    const byNamespace = groupElementsByNamespace(intrinsicElements);
+    const linkByGlibName = buildElementLinks(intrinsicElements, basePath);
+    const pageContext = createElementPageContext(library, (glibName) => linkByGlibName.get(glibName));
+    const pages = [];
+    const namespaces = [];
+    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, manifestPath) => {
+    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"));
+    return { regenerated: false, namespaces: manifest.namespaces };
+};
+const writePages = (outDir, pages) => {
+    for (const page of pages) {
+        const target = join(outDir, page.path);
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, page.content);
+    }
+};
+const writeDocs = (options) => {
+    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 = { 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 };
+//# sourceMappingURL=pipeline.js.map

package/dist/docs/pipeline.js.map

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

package/dist/docs/render.d.ts

@@ -0,0 +1,34 @@
+import type { GirClass } from "../gir/class.js";
+import type { GirFunction } from "../gir/function.js";
+import type { Library } from "../gir/library.js";
+import type { GirNamespace } from "../gir/namespace.js";
+import type { GirCallable } from "../gir/parameter.js";
+import type { TypeId } from "../gir/type-id.js";
+import { ModuleContext } from "../writer/context.js";
+type SignatureEntry = {
+    name: string;
+    signature: string;
+    doc: string;
+};
+type OriginSignatureEntry = SignatureEntry & {
+    origin: string | undefined;
+};
+declare const renderDocsType: (library: Library, ref: TypeId | undefined, isNullable: boolean) => string;
+declare const renderDocsSignalSignature: (library: Library, signal: GirCallable, selfType: string) => string;
+declare const renderDocsSignalHandlerType: (library: Library, signal: GirCallable) => string;
+declare const docsDefaultValue: (value: string) => string;
+declare const docMarkdown: (doc: string | undefined) => string;
+declare const firstSentence: (doc: string | undefined) => string;
+declare const elementSlug: (className: string) => string;
+declare const implementsLine: (names: string[]) => string[];
+declare const joinSections: (sections: string[]) => string;
+declare const metaBlock: (name: string, meta: string, doc: string) => string;
+declare const signatureBlock: (name: string, signature: string, notes: string[]) => string;
+declare const namespaceOrder: (name: string) => string;
+declare const docsSignatureContext: (namespace: GirNamespace, library: Library) => ModuleContext;
+declare const originSignatureBlocks: (entries: OriginSignatureEntry[]) => string[];
+declare const classMethodEntries: (library: Library, namespace: GirNamespace, klass: GirClass) => SignatureEntry[];
+declare const methodsSectionBlocks: (entries: SignatureEntry[], intro: string) => string[];
+declare const instanceMethodEntries: (signatureContext: ModuleContext, klass: GirClass, rename: (fn: GirFunction) => string | undefined) => SignatureEntry[];
+export { renderDocsType, renderDocsSignalSignature, renderDocsSignalHandlerType, docsDefaultValue, docMarkdown, firstSentence, elementSlug, implementsLine, joinSections, metaBlock, signatureBlock, namespaceOrder, docsSignatureContext, originSignatureBlocks, classMethodEntries, methodsSectionBlocks, instanceMethodEntries, type SignatureEntry, type OriginSignatureEntry, };
+//# sourceMappingURL=render.d.ts.map

package/dist/docs/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/docs/render.ts"],"names":[],"mappings":"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"}

package/dist/docs/render.js

@@ -0,0 +1,143 @@
+import { pascalCase, sortStringsBy } from "@gtkx/utils";
+import { collectInheritedMethods, conflictRename } from "../analysis/inheritance.js";
+import { renderHandlerParameters, renderHandlerResultType } from "../analysis/param-structure.js";
+import { recordTypeTarget, renderBaseType } from "../analysis/ts-type.js";
+import { dedupeCallables, instanceScope, renderInstanceMethodSignature } from "../store/gi/callables.js";
+import { methodExportName } from "../store/gi/method.js";
+import { ModuleContext } from "../writer/context.js";
+import { gtkDocToMarkdown } from "../writer/gtk-doc.js";
+const DOCS_DEFAULT_VALUES = { TRUE: "true", FALSE: "false", NULL: "null" };
+const FENCE_LINE = /^\s*(```|~~~)/;
+const HEADING_LINE = /^#{1,5}\s/;
+const LEADING_NAMESPACES = ["Gtk", "Adw"];
+const DOCS_SIGNATURE_NAMESPACE = "$docs";
+const docsTarget = (library) => recordTypeTarget(library, (name) => `${name.namespaceName}.${name.typeName}`, () => "GObject.Type");
+const renderDocsType = (library, ref, isNullable) => {
+    const base = renderBaseType(library, docsTarget(library), ref);
+    return isNullable ? `${base} | null` : base;
+};
+const renderDocsHandlerResultType = (library, signal) => renderHandlerResultType({
+    library,
+    signal,
+    renderType: (ref, nullable) => renderDocsType(library, ref, nullable),
+    includeCallerAllocated: false,
+    optOut: true,
+});
+const renderDocsHandlerParameters = (library, signal) => renderHandlerParameters(signal.parameters, (ref, nullable) => renderDocsType(library, ref, nullable));
+const renderDocsSignalSignature = (library, signal, selfType) => {
+    const params = [...renderDocsHandlerParameters(library, signal), `self: ${selfType}`];
+    return `(${params.join(", ")}) => ${renderDocsHandlerResultType(library, signal)}`;
+};
+const renderDocsSignalHandlerType = (library, signal) => `(${renderDocsHandlerParameters(library, signal).join(", ")}) => ${renderDocsHandlerResultType(library, signal)}`;
+const docsDefaultValue = (value) => DOCS_DEFAULT_VALUES[value] ?? value;
+const stripDocMedia = (markdown) => markdown
+    .replaceAll(/<picture[\s\S]*?<\/picture>/g, "")
+    .replaceAll(/<video[\s\S]*?(?:<\/video>|\/>)/g, "")
+    .replaceAll(/<img[^>]*>/g, "");
+const demoteLine = (line, isInFence) => {
+    if (FENCE_LINE.test(line)) {
+        return { text: line, inFence: !isInFence };
+    }
+    if (isInFence) {
+        return { text: line, inFence: isInFence };
+    }
+    return { text: HEADING_LINE.test(line) ? `#${line}` : line, inFence: isInFence };
+};
+const demoteHeadings = (markdown) => {
+    let isInFence = false;
+    const lines = [];
+    for (const line of markdown.split("\n")) {
+        const result = demoteLine(line, isInFence);
+        isInFence = result.inFence;
+        lines.push(result.text);
+    }
+    return lines.join("\n");
+};
+const docMarkdown = (doc) => doc === undefined || doc.length === 0 ? "" : demoteHeadings(stripDocMedia(gtkDocToMarkdown(doc))).trim();
+const stripMarkdown = (markdown) => markdown
+    .replaceAll(/```[\s\S]*?```/g, " ")
+    .replaceAll(/`([^`]*)`/g, "$1")
+    .replaceAll(/\[([^[\]]*)\]\([^)]*\)/g, "$1")
+    .replaceAll(/[*_#>]/g, "")
+    .replaceAll(/\s+/g, " ")
+    .trim();
+const firstSentence = (doc) => {
+    const text = stripMarkdown(docMarkdown(doc));
+    if (text.length === 0) {
+        return "";
+    }
+    const match = /^.*?[.!?](?=\s|$)/.exec(text);
+    const sentence = match?.[0] ?? text;
+    return sentence.length > 220 ? `${sentence.slice(0, 217)}...` : sentence;
+};
+const elementSlug = (className) => className
+    .replaceAll(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replaceAll(/([A-Z])(?=[A-Z][a-z])/g, "$1-")
+    .toLowerCase();
+const implementsLine = (names) => {
+    if (names.length === 0) {
+        return [];
+    }
+    const quotedNames = names.map((name) => `\`${name}\``).join(", ");
+    return [`Implements ${quotedNames}.`];
+};
+const joinSections = (sections) => `${sections.filter((section) => section.length > 0).join("\n\n")}\n`;
+const metaBlock = (name, meta, doc) => {
+    const lines = [`### \`${name}\``, "", meta];
+    if (doc.length > 0) {
+        lines.push("", doc);
+    }
+    return lines.join("\n");
+};
+const signatureBlock = (name, signature, notes) => {
+    const lines = [`### \`${name}\``, "", `\`\`\`ts\n${signature}\n\`\`\``];
+    for (const note of notes) {
+        if (note.length > 0) {
+            lines.push("", note);
+        }
+    }
+    return lines.join("\n");
+};
+const namespaceOrder = (name) => {
+    const index = LEADING_NAMESPACES.indexOf(name);
+    return index === -1 ? `1${name}` : `0${String(index)}`;
+};
+const docsSignatureContext = (namespace, library) => new ModuleContext({ ...namespace, name: DOCS_SIGNATURE_NAMESPACE }, library);
+const originSignatureBlocks = (entries) => sortStringsBy(entries, (item) => item.name).map((item) => signatureBlock(item.name, item.signature, [
+    item.origin === undefined ? "" : `From \`${item.origin}\`.`,
+    item.doc,
+]));
+const classMethodEntries = (library, namespace, klass) => {
+    const realContext = new ModuleContext(namespace, library);
+    const signatureContext = docsSignatureContext(namespace, library);
+    const className = pascalCase(klass.name);
+    const inherited = collectInheritedMethods(realContext, klass);
+    return instanceMethodEntries(signatureContext, klass, (method) => conflictRename(realContext, method, inherited, className));
+};
+const methodsSectionBlocks = (entries, intro) => entries.length === 0
+    ? []
+    : ["## Methods", intro, ...entries.map((item) => signatureBlock(item.name, item.signature, [item.doc]))];
+const instanceMethodEntries = (signatureContext, klass, rename) => {
+    const deduped = dedupeCallables(klass.methods);
+    const scope = instanceScope(pascalCase(klass.name), {
+        constructors: dedupeCallables(klass.constructors),
+        functions: dedupeCallables(klass.functions),
+        methods: deduped,
+    });
+    const entries = [];
+    for (const method of deduped) {
+        const nameOverride = rename(method);
+        const rendered = renderInstanceMethodSignature(signatureContext, { ...method, doc: undefined }, scope, nameOverride);
+        if (rendered === undefined) {
+            continue;
+        }
+        entries.push({
+            name: nameOverride ?? methodExportName(method),
+            signature: rendered.trim().replace(/;$/, ""),
+            doc: docMarkdown(method.doc),
+        });
+    }
+    return sortStringsBy(entries, (entry) => entry.name);
+};
+export { renderDocsType, renderDocsSignalSignature, renderDocsSignalHandlerType, docsDefaultValue, docMarkdown, firstSentence, elementSlug, implementsLine, joinSections, metaBlock, signatureBlock, namespaceOrder, docsSignatureContext, originSignatureBlocks, classMethodEntries, methodsSectionBlocks, instanceMethodEntries, };
+//# sourceMappingURL=render.js.map