refactor(theme): split admonitions, make swizzle easier, better retrocompatibility (#7945)

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

packages/docusaurus-theme-common/src/index.ts

@@ -78,3 +78,5 @@ export {duplicates, uniq} from './utils/jsUtils';
 export {usePrismTheme} from './hooks/usePrismTheme';
 
 export {useDocsPreferredVersion} from './contexts/docsPreferredVersion';
+
+export {processAdmonitionProps} from './utils/admonitionUtils';

packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts

@@ -40,8 +40,7 @@ export const ThemeClassNames = {
     backToTopButton: 'theme-back-to-top-button',
     codeBlock: 'theme-code-block',
     admonition: 'theme-admonition',
-    admonitionType: (type: 'note' | 'tip' | 'danger' | 'info' | 'caution') =>
-      `theme-admonition-${type}`,
+    admonitionType: (type: string) => `theme-admonition-${type}`,
   },
   layout: {
     // TODO add other stable classNames here

packages/docusaurus-theme-common/src/utils/admonitionUtils.tsx

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React, {type ReactNode} from 'react';
+
+// Workaround because it's difficult in MDX v1 to provide a MDX title as props
+// See https://github.com/facebook/docusaurus/pull/7152#issuecomment-1145779682
+function extractMDXAdmonitionTitle(children: ReactNode): {
+  mdxAdmonitionTitle: ReactNode | undefined;
+  rest: ReactNode;
+} {
+  const items = React.Children.toArray(children);
+  const mdxAdmonitionTitle = items.find(
+    (item) =>
+      React.isValidElement(item) &&
+      (item.props as {mdxType: string} | null)?.mdxType ===
+        'mdxAdmonitionTitle',
+  );
+  const rest = <>{items.filter((item) => item !== mdxAdmonitionTitle)}</>;
+  return {
+    mdxAdmonitionTitle,
+    rest,
+  };
+}
+
+export function processAdmonitionProps<
+  Props extends {readonly children: ReactNode; readonly title?: ReactNode},
+>(props: Props): Props {
+  const {mdxAdmonitionTitle, rest} = extractMDXAdmonitionTitle(props.children);
+  const title = props.title ?? mdxAdmonitionTitle;
+  return {
+    ...props,
+    // Do not return "title: undefined" prop
+    // this might create unwanted props overrides when merging props
+    // For example: {...default,...props}
+    ...(title && {title}),
+    children: rest,
+  };
+}