docs: add experimental features (#874)

packages/docs/src/Icon/Science/index.tsx

@@ -0,0 +1,20 @@
+import React, {ComponentProps} from 'react';
+
+export default function IconScience({
+  width = 24,
+  height = 24,
+  ...props
+}: ComponentProps<'svg'>): JSX.Element {
+  return (
+    <svg
+      viewBox="0 0 24 24"
+      width={width}
+      height={height}
+      aria-hidden
+      fill="currentColor"
+      {...props}
+    >
+      <path d="M19.8,18.4L14,10.67V6.5l1.35-1.69C15.61,4.48,15.38,4,14.96,4H9.04C8.62,4,8.39,4.48,8.65,4.81L10,6.5v4.17L4.2,18.4 C3.71,19.06,4.18,20,5,20h14C19.82,20,20.29,19.06,19.8,18.4z" />
+    </svg>
+  );
+}

packages/docs/src/components/Api/ApiItem.tsx

@@ -12,6 +12,16 @@ import React, {useMemo} from 'react';
 import type {JSONOutput} from 'typedoc';
 import {ReflectionKind} from './ReflectionKind';
 
+const ExperimentalIcon = `
+<svg 
+  xmlns="http://www.w3.org/2000/svg" 
+  viewBox="0 0 24 24" 
+  fill="currentColor" 
+  class="experimental" 
+  data-experimental="data-experimental">
+  <path d="M19.8,18.4L14,10.67V6.5l1.35-1.69C15.61,4.48,15.38,4,14.96,4H9.04C8.62,4,8.39,4.48,8.65,4.81L10,6.5v4.17L4.2,18.4 C3.71,19.06,4.18,20,5,20h14C19.82,20,20.29,19.06,19.8,18.4z"/>
+</svg>`;
+
 interface ApiItemProps {
   route: {
     reflectionId: number;
@@ -49,7 +59,9 @@ export default function ApiItem({route}: ApiItemProps): JSX.Element {
             continue;
           }
           toc.push({
-            value: `<code>${child.name}</code>`,
+            value: `${child.experimental ? ExperimentalIcon : ''}<code>${
+              child.name
+            }</code>`,
             id: child.anchor,
             level: 3,
           });

packages/docs/src/components/Api/Comment/index.tsx

@@ -1,5 +1,6 @@
 import {Collapsible} from '@docusaurus/theme-common';
 import Summary from '@site/src/components/Api/Comment/Summary';
+import Admonition from '@theme/Admonition';
 import clsx from 'clsx';
 import React, {useMemo, useState} from 'react';
 import type {JSONOutput} from 'typedoc';
@@ -18,13 +19,32 @@ export default function Comment({
 
   return (
     <>
+      {full && <Experimental comment={comment} />}
       <Summary id={comment?.summaryId} />
       <Summary id={remarks?.contentId} />
       {full && <FullComment comment={comment} />}
     </>
   );
 }
 
+function Experimental({comment}: {comment: JSONOutput.Comment}) {
+  const experimental = useMemo(
+    () => comment?.modifierTags?.includes('@experimental'),
+    [comment],
+  );
+
+  return (
+    <>
+      {experimental && (
+        <Admonition type="experimental">
+          This is an experimental feature. The behavior and API may change
+          drastically between major releases.
+        </Admonition>
+      )}
+    </>
+  );
+}
+
 function FullComment({comment}: {comment: JSONOutput.Comment}) {
   const [collapsed, setCollapsed] = useState(true);
   const preview = useMemo(

packages/docs/src/components/Release/Issue.tsx

@@ -1,3 +1,4 @@
+import IconScience from '@site/src/Icon/Science';
 import Contributor from '@site/src/components/Release/Contributor';
 import PullRequest from '@site/src/components/Release/PullRequest';
 import styles from '@site/src/components/Release/styles.module.css';
@@ -6,13 +7,19 @@ import React, {ReactNode} from 'react';
 export interface IssueProps {
   user: string;
   pr?: number;
+  experimental?: boolean;
   children: ReactNode | ReactNode[];
 }
 
-export default function Issue({user, pr, children}: IssueProps) {
+export default function Issue({user, pr, experimental, children}: IssueProps) {
   return (
     <li className={styles.element}>
       <Contributor name={user} />
+      {experimental && (
+        <span title="Experimental feature">
+          <IconScience className="experimental" />
+        </span>
+      )}
       {children}
       {pr && <PullRequest id={pr} />}
     </li>

packages/docs/src/css/custom.css

@@ -190,6 +190,14 @@ a.button:hover {
   margin: 0 0.3rem;
 }
 
+.experimental {
+  width: 1em;
+  height: 1em;
+  margin-right: 0.2em;
+  vertical-align: middle;
+  display: inline-block;
+}
+
 [data-theme='light']:root,
 [data-theme='dark']:root {
   --docsearch-primary-color: var(--ifm-color-primary);

packages/docs/src/theme/Admonition/index.tsx

@@ -1,3 +1,4 @@
+import IconScience from '@site/src/Icon/Science';
 import IconDanger from '@site/src/theme/Icon/Danger';
 import IconInfo from '@site/src/theme/Icon/Info';
 import IconLightBulb from '@site/src/theme/Icon/LightBulb';
@@ -6,23 +7,35 @@ import Admonition from '@theme-original/Admonition';
 import React, {useMemo} from 'react';
 import styles from './styles.module.css';
 
-export default function AdmonitionWrapper(props) {
+export default function AdmonitionWrapper({title, type, ...props}) {
   const Icon = useMemo(() => {
-    switch (props.type) {
+    switch (type) {
       case 'tip':
         return IconLightBulb;
       case 'caution':
         return IconWarning;
       case 'danger':
         return IconDanger;
+      case 'experimental':
+        return IconScience;
       default:
         return IconInfo;
     }
-  }, [props.type]);
+  }, [type]);
+
+  if (type === 'experimental') {
+    title ??= 'Experimental';
+    type = 'caution';
+  }
 
   return (
     <>
-      <Admonition icon={<Icon className={styles.icon} />} {...props} />
+      <Admonition
+        icon={<Icon className={styles.icon} />}
+        title={title}
+        type={type}
+        {...props}
+      />
     </>
   );
 }

packages/docs/typedoc.js

@@ -297,6 +297,31 @@ async function parseTypes(options, projectName, externalProject) {
     },
   });
 
+  app.serializer.addSerializer({
+    priority: -Infinity,
+    supports(item) {
+      return item instanceof Reflection;
+    },
+    toObject(item, obj) {
+      obj.experimental = isExperimental(item);
+
+      if (!obj.experimental && item instanceof DeclarationReflection) {
+        const signatures = [
+          ...(obj.signatures ?? []),
+          obj.setSignature,
+          obj.getSignature,
+          obj.indexSignature,
+        ].filter(item => !!item);
+
+        obj.experimental = signatures.some(signature =>
+          isExperimental(lookup[signature.id]),
+        );
+      }
+
+      return obj;
+    },
+  });
+
   app.serializer.addSerializer({
     priority: -Infinity,
     supports(item) {
@@ -399,3 +424,18 @@ function partsToText(parts) {
     })
     .join('');
 }
+
+function isExperimental(reflection) {
+  const tags = reflection?.comment?.modifierTags;
+  if (!tags) return false;
+
+  if (typeof tags === 'string') {
+    return tags === '@experimental';
+  }
+
+  if (Array.isArray(tags)) {
+    return tags.some(tag => tag === '@experimental');
+  }
+
+  return tags.has('@experimental');
+}

tsdoc.json

@@ -35,6 +35,7 @@
     "@ignore": true,
     "@inheritDoc": true,
     "@defaultValue": true,
-    "@see": true
+    "@see": true,
+    "@experimental": true
   }
 }