Add prettier plugin to partially format MDX3 (#12796)

Author: phryneas

.prettierrc

@@ -6,13 +6,22 @@
   "tabWidth": 2,
   "trailingComma": "es5",
   "experimentalTernaries": true,
-  "plugins": ["./config/prettier/format-jsdoc.js"],
+  "plugins": [
+    "./config/prettier/format-jsdoc.js",
+    "./config/prettier/format-mdx3.js"
+  ],
   "overrides": [
     {
       "files": ["*.ts", "*.tsx"],
       "options": {
         "parser": "typescript-with-jsdoc"
       }
+    },
+    {
+      "files": ["*.mdx"],
+      "options": {
+        "parser": "mdx3"
+      }
     }
   ]
 }

config/prettier/format-mdx3.js

@@ -0,0 +1,48 @@
+/** @import { Plugin } from 'prettier' */
+
+import markdown from "prettier/plugins/markdown.js";
+
+/** @type {Plugin["languages"]} */
+export const languages = [
+  {
+    name: "MDX",
+    parsers: ["mdx3"],
+    extensions: [".mdx"],
+  },
+];
+/** @type {Plugin["parsers"]} */
+export const parsers = {
+  mdx3: {
+    ...markdown.parsers.mdx,
+    astFormat: "mdx3",
+  },
+};
+/** @type {Plugin["printers"]} */
+export const printers = {
+  mdx3: {
+    ...markdown.printers.mdast,
+    embed(path, options) {
+      const node = path.node;
+      if (node.type === "jsx") {
+        // If the node was parsed incorrectly because it followed the MDX3 format (no spacing around JSX tags),
+        // we will not try to format it as MDX, but instead return the original value.
+
+        // We detect that by looking at `value` - if it's only a starting or closing tag, it was parsed correctly.
+        const correctlyParsedMatch = node.value.match(/^(<\/?[^>]*>)$/);
+        if (!correctlyParsedMatch)
+          return (
+            node.value
+              .split("\n")
+              // But we need to restore the original indentation
+              .map((line, idx) =>
+                idx === 0 ? line : (
+                  " ".repeat(node.position.indent[idx - 1] - 1) + line
+                )
+              )
+              .join("\n")
+          );
+      }
+      return markdown.printers.mdast.embed(path, options);
+    },
+  },
+};

config/prettier/test.ts

@@ -1,93 +1,27 @@
 import * as prettier from "prettier";
 const code = `
+Notice that the \`Trail\` component isn't receiving the entire \`trail\` object via props, only the \`id\` which is used along with the fragment document to create a live binding for each trail item in the cache. This allows each \`Trail\` component to react to the cache updates for a single trail independently. Updates to a trail's \`status\` will not cause the parent \`App\` component to rerender since the \`@nonreactive\` directive is applied to the \`TrailFragment\` spread, a fragment that includes the \`status\` field.
 
+<MinVersion version="3.12.0">
+## \`@unmask\`
+</MinVersion>
 
-/**
- * A hook for executing queries in an Apollo application.
- *
- * To run a query within a React component, call \`useQuery\` and pass it a GraphQL query document.
- *
- * When your component renders, \`useQuery\` returns an object from Apollo Client that contains
- *
- * > Refer to the [Queries](https://www.apollographql.com/docs/react/data/queries) section for a more in-depth overview of \`useQuery\`.
- *
- * @example
- * \`\`\`jsx
- * import { gql } from '@apollo/client';
- * import { useQuery } from '@apollo/client/react';
- *
- * const GET_GREETING = gql\`
- *   query GetGreeting($language: String!) {
- *     greeting(language: $language) {
- *       message
- *     }
- *   }
- * \`;
- *
- * function Hello() {
- *   const { loading, error, data } = useQuery(GET_GREETING, {
- *                 variables: { language: 'english' },
- *   });
- *   if (loading) return <p>Loading ...</p>;
- *   return <h1>Hello {data.greeting.message}!</h1>;
- * }
- * \`\`\`
- * @param query - A GraphQL query document parsed into an AST by \`gql\`.
- * @param options - Options to control how the query is executed.
- * @returns Query result object
- */
-export function useQuery<
-  TData = unknown,
-  TVariables extends OperationVariables = OperationVariables,
->(
-  query: DocumentNode | TypedDocumentNode<TData, TVariables>,
-  options: useQuery.Options<NoInfer<TData>, NoInfer<TVariables>> & {
-    returnPartialData: true;
-  }
-): useQuery.Result<
-  TData,
-  TVariables,
-  "empty" | "complete" | "streaming" | "partial"
->;
+The \`@unmask\` directive is used to make fragment data available when using [data masking](./fragments#data-masking). It is primarily used to [incrementally adopt data masking in an existing application](./fragments#incremental-adoption-in-an-existing-application). It is considered an escape hatch for all other cases where working with masked data would otherwise be difficult.
 
-/** {@inheritDoc @apollo/client!useQuery:function(1)} */
-export function useQuery<
-  TData = unknown,
-  TVariables extends OperationVariables = OperationVariables,
->(
-  query: DocumentNode | TypedDocumentNode<TData, TVariables>,
-  options: useQuery.Options<NoInfer<TData>, NoInfer<TVariables>> & {
-    returnPartialData: boolean;
+\`\`\`graphql
+query GetPosts {
+  posts {
+    id
+    ...PostDetails @unmask
   }
-): useQuery.Result<
-  TData,
-  TVariables,
-  "empty" | "complete" | "streaming" | "partial"
->;
-
-/** {@inheritDoc @apollo/client!useQuery:function(1)} */
-export function useQuery<
-  TData = unknown,
-TVariables extends OperationVariables = OperationVariables,
->(
-query: DocumentNode | TypedDocumentNode<TData, TVariables>,
-...[options]: {} extends TVariables ?
- [options?: useQuery.Options<NoInfer<TData>, NoInfer<TVariables>>]
-: [options: useQuery.Options<NoInfer<TData>, NoInfer<TVariables>>]
-): useQuery.Result<TData, TVariables, "empty" | "complete" | "streaming">;
+}
+\`\`\`
 
-`
-  .split("\n")
-  .map((line) => line.trim())
-  .join("\n");
-await prettier.format(``, {
-  parser: "jsdoc",
-  plugins: ["./format-jsdoc.js"],
-});
+`;
 
 const result = await prettier.format(code, {
-  parser: "typescript-with-jsdoc",
-  plugins: ["./format-jsdoc.js"],
+  parser: "mdx3",
+  plugins: ["./format-mdx3.js"],
 });
 
 console.log(result);

docs/source/data/queries.mdx

@@ -181,7 +181,7 @@ You call `refetch` with a new set of variables like so:
   }
 >
   Refetch!
-</button>
+</button>;
 ```
 
 If you provide new values for _some_ of your original query's variables but not _all_ of them, `refetch` uses each omitted variable's original value.