Use TypeScript @import JSDoc tags

Previously we used `@typedef` tags to simulate type imports. The problem is that are not really imports. They define and export a new type. We now use `@import` introduced by TypeScript 5.5 to actually import types. The pattern using `@typedef` is still used in index files to export types. This change also replaces the type casting inside MDX files with definitions of the `Props` types. This also replaces usage of the global `JSX` namespace with proper types. For TypeScript<5.1 the correct return type of React components is `ReactElement`, for Preact `VNode`. For TypeScript>=5.1, the correct return type for React components is `ReactNode`, for Preact `ComponentChildren`.
mdx-js · Jun 25, 2024 · 429d15f · 429d15f
1 parent 8ccbba8
commit 429d15f
Show file tree

Hide file tree

Showing 63 changed files with 357 additions and 319 deletions.
diff --git a/docs/_asset/editor.jsx b/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) {

diff --git a/docs/_component/blog.jsx b/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) {

diff --git a/docs/_component/home.jsx b/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) {

diff --git a/docs/_component/layout.jsx b/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) {

diff --git a/docs/_component/nav-site.jsx b/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) {

diff --git a/docs/_component/nav.jsx b/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) {

diff --git a/docs/_component/note.jsx b/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) {

diff --git a/docs/_component/snowfall.jsx b/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) {

diff --git a/docs/_component/sort.js b/docs/_component/sort.js
@@ -1,5 +1,5 @@
 /**
- * @typedef {import('vfile').Data} Data
+ * @import {Data} from 'vfile'
  */
 
 /**

diff --git a/docs/blog/index.mdx b/docs/blog/index.mdx
@@ -1,3 +1,12 @@
+{/**
+ * @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 +25,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/'

diff --git a/docs/community/index.mdx b/docs/community/index.mdx
@@ -1,3 +1,12 @@
+{/**
+ * @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 +24,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/'

diff --git a/docs/docs/index.mdx b/docs/docs/index.mdx
@@ -1,3 +1,12 @@
+{/**
+ * @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 +26,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/'

diff --git a/docs/guides/index.mdx b/docs/guides/index.mdx
@@ -1,3 +1,12 @@
+{/**
+ * @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 +24,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/'

diff --git a/docs/packages/index.mdx b/docs/packages/index.mdx
@@ -1,3 +1,12 @@
+{/**
+ * @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 +26,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/'

diff --git a/packages/esbuild/lib/index.js b/packages/esbuild/lib/index.js
@@ -1,12 +1,12 @@
 /**
- * @typedef {import('@mdx-js/mdx').CompileOptions} CompileOptions
- * @typedef {import('esbuild').Message} Message
- * @typedef {import('esbuild').OnLoadArgs} OnLoadArgs
- * @typedef {import('esbuild').OnLoadResult} OnLoadResult
- * @typedef {import('esbuild').OnResolveArgs} OnResolveArgs
- * @typedef {import('esbuild').Plugin} Plugin
- * @typedef {import('esbuild').PluginBuild} PluginBuild
- * @typedef {import('vfile').Value} Value
+ * @import {CompileOptions} from '@mdx-js/mdx'
+ * @import {
+  Message,
+  OnLoadArgs,
+  OnLoadResult,
+  Plugin,
+   PluginBuild
+ * } from 'esbuild'
  */
 
 /**