Refactor to use TypeScript @import JSDoc tags

Closes GH-2498.

Reviewed-by: Titus Wormer <[email protected]>

docs/_asset/editor.jsx

@@ -2,20 +2,20 @@
 /* @jsxImportSource react */
 
 /**
- * @typedef {import('@wooorm/starry-night').Grammar} Grammar
- * @typedef {import('estree').Node} EstreeNode
- * @typedef {import('estree').Program} Program
- * @typedef {import('hast').Nodes} HastNodes
- * @typedef {import('hast').Root} HastRoot
- * @typedef {import('mdast').Nodes} MdastNodes
- * @typedef {import('mdast').Root} MdastRoot
- * @typedef {import('mdast-util-mdx-jsx').MdxJsxAttribute} MdxJsxAttribute
- * @typedef {import('mdast-util-mdx-jsx').MdxJsxAttributeValueExpression} MdxJsxAttributeValueExpression
- * @typedef {import('mdast-util-mdx-jsx').MdxJsxExpressionAttribute} MdxJsxExpressionAttribute
- * @typedef {import('mdx/types.js').MDXModule} MDXModule
- * @typedef {import('react-error-boundary').FallbackProps} FallbackProperties
- * @typedef {import('unified').PluggableList} PluggableList
- * @typedef {import('unist').Node} UnistNode
+ * @import {Grammar} from '@wooorm/starry-night'
+ * @import {Node as EstreeNode, Program} from 'estree'
+ * @import {Nodes as HastNodes, Root as HastRoot} from 'hast'
+ * @import {Nodes as MdastNodes, Root as MdastRoot} from 'mdast'
+ * @import {
+    MdxJsxAttribute,
+    MdxJsxAttributeValueExpression,
+    MdxJsxExpressionAttribute
+ * } from 'mdast-util-mdx-jsx'
+ * @import {MDXModule} from 'mdx/types.js'
+ * @import {ReactNode} from 'react'
+ * @import {FallbackProps} from 'react-error-boundary'
+ * @import {PluggableList} from 'unified'
+ * @import {Node as UnistNode} from 'unist'
  */
 
 /**
@@ -35,7 +35,7 @@
  *   OK.
  * @property {true} ok
  *   Whether OK.
- * @property {JSX.Element} value
+ * @property {ReactNode} value
  *   Result.
  *
  * @typedef {EvalNok | EvalOk} EvalResult
@@ -315,7 +315,7 @@ function Playground() {
   const scope = formatMarkdown ? 'text.md' : 'source.mdx'
   // Cast to actual value.
   const compiledResult = /** @type {EvalResult | undefined} */ (evalResult)
-  /** @type {JSX.Element | undefined} */
+  /** @type {ReactNode | undefined} */
   let display
 
   if (compiledResult) {
@@ -579,9 +579,9 @@ function Playground() {
 
 /**
  *
- * @param {Readonly<FallbackProperties>} properties
+ * @param {Readonly<FallbackProps>} properties
  *   Properties.
- * @returns {JSX.Element}
+ * @returns {ReactNode}
  *   Element.
  */
 function ErrorFallback(properties) {
@@ -601,7 +601,7 @@ function ErrorFallback(properties) {
 /**
  * @param {DisplayProperties} properties
  *   Properties.
- * @returns {JSX.Element}
+ * @returns {ReactNode}
  *   Element.
  */
 function DisplayError(properties) {

docs/_component/blog.jsx

@@ -1,5 +1,6 @@
 /**
- * @typedef {import('./sort.js').Item} Item
+ * @import {ReactNode} from 'react'
+ * @import {Item} from './sort.js'
  */
 
 /**
@@ -29,7 +30,7 @@ const dateTimeFormat = new Intl.DateTimeFormat('en', {dateStyle: 'long'})
 /**
  * @param {Readonly<EntryProperties>} properties
  *   Properties.
- * @returns {JSX.Element}
+ * @returns {ReactNode}
  *   Element.
  */
 export function BlogEntry(properties) {
@@ -106,7 +107,7 @@ export function BlogEntry(properties) {
 /**
  * @param {Readonly<GroupProperties>} properties
  *   Properties.
- * @returns {JSX.Element}
+ * @returns {ReactNode}
  *   Element.
  */
 export function BlogGroup(properties) {

docs/_component/home.jsx

@@ -1,11 +1,11 @@
 /**
- * @typedef {import('react').ReactNode} ReactNode
- * @typedef {import('vfile').Data['meta']} DataMeta
- * @typedef {import('./sort.js').Item} Item
+ * @import {ReactNode} from 'react'
+ * @import {Data} from 'vfile'
+ * @import {Item} from './sort.js'
  */
 
 /**
- * @typedef {Exclude<DataMeta, undefined>} Meta
+ * @typedef {Exclude<Data['meta'], undefined>} Meta
  *
  * @typedef Properties
  *   Properties.
@@ -26,7 +26,7 @@ import {NavigationSite, NavigationSiteSkip} from './nav-site.jsx'
 /**
  * @param {Readonly<Properties>} properties
  *   Properties.
- * @returns {JSX.Element}
+ * @returns {ReactNode}
  *   Element.
  */
 export function Home(properties) {

docs/_component/layout.jsx

@@ -1,6 +1,7 @@
 /**
- * @typedef {import('vfile').Data['meta']} DataMeta
- * @typedef {import('./sort.js').Item} Item
+ * @import {ReactNode} from 'react'
+ * @import {Data} from 'vfile'
+ * @import {Item} from './sort.js'
  */
 
 /**
@@ -10,11 +11,11 @@
  *   Name.
  * @property {Readonly<URL>} ghUrl
  *   GitHub URL.
- * @property {Readonly<DataMeta> | undefined} [meta]
+ * @property {Readonly<Data['meta']> | undefined} [meta]
  *   Meta.
  * @property {Readonly<Item>} navigationTree
  *   Navigation tree.
- * @property {JSX.Element} children
+ * @property {ReactNode} children
  *   Children.
  */
 
@@ -28,7 +29,7 @@ const dateTimeFormat = new Intl.DateTimeFormat('en', {dateStyle: 'long'})
 /**
  * @param {Readonly<Properties>} properties
  *   Properties.
- * @returns {JSX.Element}
+ * @returns {ReactNode}
  *   Element.
  */
 export function Layout(properties) {

docs/_component/nav-site.jsx

@@ -1,5 +1,6 @@
 /**
- * @typedef {import('./sort.js').Item} Item
+ * @import {ReactNode} from 'react'
+ * @import {Item} from './sort.js'
  */
 
 /**
@@ -34,7 +35,7 @@ export function NavigationSiteSkip() {
 /**
  * @param {Readonly<Properties>} properties
  *   Properties.
- * @returns {JSX.Element}
+ * @returns {ReactNode}
  *   Element.
  */
 export function NavigationSite(properties) {

docs/_component/nav.jsx

@@ -2,9 +2,9 @@
 /// <reference types="rehype-infer-description-meta" />
 
 /**
- * @typedef {import('hast').ElementContent} ElementContent
- * @typedef {import('react').ReactNode} ReactNode
- * @typedef {import('./sort.js').Item} Item
+ * @import {ElementContent} from 'hast'
+ * @import {ReactNode} from 'react'
+ * @import {Item} from './sort.js'
  */
 
 /**
@@ -46,7 +46,7 @@ const dateTimeFormat = new Intl.DateTimeFormat('en', {dateStyle: 'long'})
 /**
  * @param {Readonly<GroupProperties>} properties
  *   Properties.
- * @returns {JSX.Element}
+ * @returns {ReactNode}
  *   Element.
  */
 export function NavigationGroup(properties) {
@@ -69,7 +69,7 @@ export function NavigationGroup(properties) {
 /**
  * @param {Readonly<ItemProperties>} properties
  *   Properties.
- * @returns {JSX.Element}
+ * @returns {ReactNode}
  *   Element.
  */
 export function NavigationItem(properties) {

docs/_component/note.jsx

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('react').ReactNode} ReactNode
+ * @import {ReactNode} from 'react'
  */
 
 /**
@@ -22,7 +22,7 @@ const known = new Set(['info', 'legacy', 'important'])
 /**
  * @param {Readonly<Properties>} properties
  *   Properties.
- * @returns {JSX.Element}
+ * @returns {ReactNode}
  *   Element.
  */
 export function Note(properties) {

docs/_component/snowfall.jsx

@@ -1,3 +1,7 @@
+/**
+ * @import {ReactNode} from 'react'
+ */
+
 /**
  * @typedef Properties
  *   Properties.
@@ -14,7 +18,7 @@ const data = [6, 5, 2, 4.5, 1.5, 2.5, 2, 2.5, 1.5, 2.5, 3.5, 7]
 /**
  * @param {Readonly<Properties>} properties
  *   Properties.
- * @returns {JSX.Element}
+ * @returns {ReactNode}
  *   Element.
  */
 export function Chart(properties) {

docs/_component/sort.js

@@ -1,5 +1,5 @@
 /**
- * @typedef {import('vfile').Data} Data
+ * @import {Data} from 'vfile'
  */
 
 /**

docs/blog/index.mdx

@@ -1,3 +1,14 @@
+{
+  /**
+   * @import {Item} from '../_component/sort.js
+   */
+
+  /**
+   * @typedef Props
+   * @property {Item} navigationTree
+   */
+}
+
 import assert from 'node:assert/strict'
 import {BlogGroup} from '../_component/blog.jsx'
 
@@ -16,11 +27,6 @@ The latest news about MDX.
 
 {
   (function () {
-    /**
-     * @typedef {import('../_component/sort.js').Item} Item
-     */
-
-    /** @type {Item} */
     const navigationTree = props.navigationTree
     const category = navigationTree.children.find(function (item) {
       return item.name === '/blog/'

docs/community/index.mdx

@@ -1,3 +1,14 @@
+{
+  /**
+   * @import {Item} from '../_component/sort.js
+   */
+
+  /**
+   * @typedef Props
+   * @property {Item} navigationTree
+   */
+}
+
 import assert from 'node:assert/strict'
 import {NavigationGroup} from '../_component/nav.jsx'
 
@@ -15,11 +26,6 @@ and some background information.
 
 {
   (function () {
-    /**
-     * @typedef {import('../_component/sort.js').Item} Item
-     */
-
-    /** @type {Item} */
     const navigationTree = props.navigationTree
     const category = navigationTree.children.find(function (item) {
       return item.name === '/community/'

docs/docs/index.mdx

@@ -1,3 +1,14 @@
+{
+  /**
+   * @import {Item} from '../_component/sort.js
+   */
+
+  /**
+   * @typedef Props
+   * @property {Item} navigationTree
+   */
+}
+
 import assert from 'node:assert/strict'
 import {NavigationGroup} from '../_component/nav.jsx'
 
@@ -17,11 +28,6 @@ Reading through these should give you a good understanding of MDX.
 
 {
   (function () {
-    /**
-     * @typedef {import('../_component/sort.js').Item} Item
-     */
-
-    /** @type {Item} */
     const navigationTree = props.navigationTree
     const category = navigationTree.children.find(function (item) {
       return item.name === '/docs/'

docs/guides/index.mdx

@@ -1,3 +1,14 @@
+{
+  /**
+   * @import {Item} from '../_component/sort.js
+   */
+
+  /**
+   * @typedef Props
+   * @property {Item} navigationTree
+   */
+}
+
 import assert from 'node:assert/strict'
 import {NavigationGroup} from '../_component/nav.jsx'
 
@@ -15,11 +26,6 @@ around MDX.
 
 {
   (function () {
-    /**
-     * @typedef {import('../_component/sort.js').Item} Item
-     */
-
-    /** @type {Item} */
     const navigationTree = props.navigationTree
     const category = navigationTree.children.find(function (item) {
       return item.name === '/guides/'

docs/packages/index.mdx

@@ -1,3 +1,14 @@
+{
+  /**
+   * @import {Item} from '../_component/sort.js
+   */
+
+  /**
+   * @typedef Props
+   * @property {Item} navigationTree
+   */
+}
+
 import assert from 'node:assert/strict'
 import {NavigationGroup} from '../_component/nav.jsx'
 
@@ -17,11 +28,6 @@ bundlers and frontend frameworks.
 
 {
   (function () {
-    /**
-     * @typedef {import('../_component/sort.js').Item} Item
-     */
-
-    /** @type {Item} */
     const navigationTree = props.navigationTree
     const category = navigationTree.children.find(function (item) {
       return item.name === '/packages/'