Refactor code-style

.gitignore

@@ -4,3 +4,5 @@ node_modules/
 *.d.cts
 *.d.ts
 /public/
+!/packages/mdx/lib/types.d.ts
+!/website/types.d.ts

docs/404.mdx

@@ -1,4 +1,5 @@
 import {Note} from './_component/note.jsx'
+
 export {Home as default} from './_component/home.jsx'
 export const navExclude = true
 

docs/_asset/editor.jsx

@@ -2,31 +2,43 @@
 
 /**
  * @typedef {import('@wooorm/starry-night').Grammar} Grammar
- * @typedef {import('mdx/types.js').MDXModule} MDXModule
- * @typedef {import('react-error-boundary').FallbackProps} FallbackProps
- * @typedef {import('unified').PluggableList} PluggableList
- * @typedef {import('estree').Program} Program
  * @typedef {import('estree').Node} EstreeNode
- * @typedef {import('hast').Root} HastRoot
+ * @typedef {import('estree').Program} Program
  * @typedef {import('hast').Nodes} HastNodes
- * @typedef {import('mdast').Root} MdastRoot
+ * @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').MdxJsxExpressionAttribute} MdxJsxExpressionAttribute
  * @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} FallbackProps
+ * @typedef {import('unified').PluggableList} PluggableList
  * @typedef {import('unist').Node} UnistNode
  */
 
 /**
- * @typedef EvalOk
- * @property {true} ok
- * @property {JSX.Element} value
+ * @typedef DisplayProps
+ *   Props.
+ * @property {Error} error
+ *   Error.
  *
  * @typedef EvalNok
+ *   Not OK.
  * @property {false} ok
+ *   Whether OK.
  * @property {Error} value
+ *   Error.
+ *
+ * @typedef EvalOk
+ *   OK.
+ * @property {true} ok
+ *   Whether OK.
+ * @property {JSX.Element} value
+ *   Result.
  *
  * @typedef {EvalNok | EvalOk} EvalResult
+ *   Result.
  */
 
 import {compile, nodeTypes, run} from '@mdx-js/mdx'
@@ -42,7 +54,7 @@ import textMd from '@wooorm/starry-night/text.md'
 import {visit as visitEstree} from 'estree-util-visit'
 import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
 import {useEffect, useState} from 'react'
-// @ts-expect-error: untyped.
+// @ts-expect-error: the automatic react runtime is untyped.
 import {Fragment, jsx, jsxs} from 'react/jsx-runtime'
 import ReactDom from 'react-dom/client'
 import {ErrorBoundary} from 'react-error-boundary'
@@ -61,7 +73,7 @@ const sample = `# Hello, world!
 
 Below is an example of markdown in JSX.
 
-<div style={{padding: '1rem', backgroundColor: 'violet'}}>
+<div style={{backgroundColor: 'violet', padding: '1rem'}}>
   Try and change the background color to \`tomato\`.
 </div>`
 
@@ -92,13 +104,17 @@ if (body && window.location.pathname === '/playground/') {
 
 /**
  * @param {Element} main
+ *   DOM element.
+ * @returns {undefined}
+ *   Nothing.
  */
 function init(main) {
   const root = ReactDom.createRoot(main)
 
   createStarryNight(grammars).then(
     /**
      * @returns {undefined}
+     *   Nothing.
      */
     function (x) {
       starryNight = x
@@ -116,6 +132,7 @@ function init(main) {
 function Playground() {
   const [directive, setDirective] = useState(false)
   const [evalResult, setEvalResult] = useState(
+    // Cast to more easily use actual value.
     /** @type {unknown} */ (undefined)
   )
   const [development, setDevelopment] = useState(false)
@@ -139,6 +156,9 @@ function Playground() {
         },
         /**
          * @param {Error} error
+         *   Error.
+         * @returns {undefined}
+         *   Nothing.
          */
         function (error) {
           setEvalResult({ok: false, value: error})
@@ -225,6 +245,9 @@ function Playground() {
         function captureMdast() {
           /**
            * @param {MdastRoot} tree
+           *   Tree.
+           * @returns {undefined}
+           *   Nothing.
            */
           return function (tree) {
             const clone = structuredClone(tree)
@@ -236,6 +259,9 @@ function Playground() {
         function captureHast() {
           /**
            * @param {HastRoot} tree
+           *   Tree.
+           * @returns {undefined}
+           *   Nothing.
            */
           return function (tree) {
             const clone = structuredClone(tree)
@@ -247,6 +273,9 @@ function Playground() {
         function captureEsast() {
           /**
            * @param {Program} tree
+           *   Tree.
+           * @returns {undefined}
+           *   Nothing.
            */
           return function (tree) {
             const clone = structuredClone(tree)
@@ -273,6 +302,7 @@ function Playground() {
   )
 
   const scope = formatMarkdown ? 'text.md' : 'source.mdx'
+  // Cast to actual value.
   const compiledResult = /** @type {EvalResult | undefined} */ (evalResult)
   /** @type {JSX.Element | undefined} */
   let display
@@ -532,13 +562,14 @@ function Playground() {
 
 /**
  *
- * @param {FallbackProps} props
+ * @param {Readonly<FallbackProps>} props
+ *   Props.
  * @returns {JSX.Element}
+ *   Element.
  */
 function ErrorFallback(props) {
-  /** @type {Error} */
   // type-coverage:ignore-next-line
-  const error = props.error
+  const error = /** @type {Error} */ (props.error)
   return (
     <div role="alert">
       <p>Something went wrong:</p>
@@ -551,9 +582,10 @@ function ErrorFallback(props) {
 }
 
 /**
- *
- * @param {{error: Error}} props
+ * @param {DisplayProps} props
+ *   Props.
  * @returns {JSX.Element}
+ *   Element.
  */
 function DisplayError(props) {
   return (
@@ -565,14 +597,20 @@ function DisplayError(props) {
 
 /**
  * @param {HastRoot | MdastRoot} node
+ *   mdast or hast root.
+ * @returns {undefined}
+ *   Nothing.
  */
 function cleanUnistTree(node) {
   removePosition(node, {force: true})
   visit(node, cleanUnistNode)
 }
 
 /**
- * @param {HastNodes | MdastNodes | MdxJsxAttribute | MdxJsxExpressionAttribute | MdxJsxAttributeValueExpression} node
+ * @param {HastNodes | MdastNodes | MdxJsxAttribute | MdxJsxAttributeValueExpression | MdxJsxExpressionAttribute} node
+ *   Node.
+ * @returns {undefined}
+ *   Nothing.
  */
 function cleanUnistNode(node) {
   if (
@@ -601,12 +639,15 @@ function cleanUnistNode(node) {
 
 /**
  * @param {EstreeNode} node
+ *   estree node.
+ * @returns {undefined}
+ *   Nothing.
  */
 function removeFromEstree(node) {
   delete node.loc
-  // @ts-expect-error: acorn.
+  // @ts-expect-error: this field is added by acorn.
   delete node.start
-  // @ts-expect-error: acorn.
+  // @ts-expect-error: this field is added by acorn.
   delete node.end
   delete node.range
 }

docs/_asset/index.js

@@ -62,6 +62,9 @@ for (const copy of copies) {
 
 /**
  * @this {HTMLButtonElement}
+ *   Button element.
+ * @returns {undefined}
+ *   Nothing.
  */
 function onclick() {
   assert(copyIcon)

docs/_component/blog.jsx

@@ -4,34 +4,40 @@
 
 /**
  * @typedef EntryProps
- * @property {Item} item
+ *   Props for `BlogEntry`.
+ * @property {Readonly<Item>} item
+ *   Item.
  *
  * @typedef GroupProps
+ *   Props for `BlogGroup`.
  * @property {string | undefined} [className]
- * @property {Array<Item>} items
+ *   Class name.
+ * @property {ReadonlyArray<Item>} items
+ *   Items.
  * @property {string | undefined} [sort]
+ *   Fields to sort on.
  */
 
-import React from 'react'
-// @ts-expect-error: untyped.
-import {Fragment, jsx, jsxs} from 'react/jsx-runtime'
 import {apStyleTitleCase} from 'ap-style-title-case'
 import {toJsxRuntime} from 'hast-util-to-jsx-runtime'
+import React from 'react'
+// @ts-expect-error: the automatic react runtime is untyped.
+import {Fragment, jsx, jsxs} from 'react/jsx-runtime'
 import {sortItems} from './sort.js'
 
 const runtime = {Fragment, jsx, jsxs}
 
 const dateTimeFormat = new Intl.DateTimeFormat('en', {dateStyle: 'long'})
 
 /**
- * @param {EntryProps} props
+ * @param {Readonly<EntryProps>} props
  *   Props.
  * @returns {JSX.Element}
  *   Element.
  */
 export function BlogEntry(props) {
   const {item} = props
-  const {name, data = {}} = item
+  const {data, name} = item
   const {matter = {}, meta = {}} = data
   const title = matter.title || meta.title
   const defaultTitle = apStyleTitleCase(
@@ -44,7 +50,9 @@ export function BlogEntry(props) {
         ? meta.readingTime
         : [meta.readingTime, meta.readingTime]
       : []
-  ).map((d) => Math.ceil(d))
+  ).map(function (d) {
+    return Math.ceil(d)
+  })
   /** @type {string | undefined} */
   let timeLabel
 
@@ -64,7 +72,7 @@ export function BlogEntry(props) {
           toJsxRuntime(meta.descriptionHast, runtime)
         ) : description ? (
           <p>{description}</p>
-        ) : null}
+        ) : undefined}
         <span>
           <a href={name}>Continue reading »</a>
         </span>
@@ -98,20 +106,20 @@ export function BlogEntry(props) {
 }
 
 /**
- * @param {GroupProps} props
+ * @param {Readonly<GroupProps>} props
  *   Props.
  * @returns {JSX.Element}
  *   Element.
  */
 export function BlogGroup(props) {
-  const {items, className, sort = 'navSortSelf,meta.title', ...rest} = props
+  const {className, items, sort = 'navSortSelf,meta.title', ...rest} = props
   const sorted = sortItems(items, sort)
 
   return (
     <>
-      {sorted.map((d) => (
-        <BlogEntry key={d.name} {...rest} item={d} />
-      ))}
+      {sorted.map(function (d) {
+        return <BlogEntry key={d.name} {...rest} item={d} />
+      })}
     </>
   )
 }

docs/_component/foot-site.jsx

@@ -6,8 +6,8 @@ export function FootSite() {
     <footer className="foot-site">
       <div className="content">
         <div
-          style={{display: 'flex', justifyContent: 'space-between'}}
           className="block"
+          style={{display: 'flex', justifyContent: 'space-between'}}
         >
           <div>
             <small>

docs/_component/home.jsx

@@ -1,39 +1,45 @@
 /**
  * @typedef {import('react').ReactNode} ReactNode
- * @typedef {Exclude<import('vfile').Data['meta'], undefined>} Meta
+ * @typedef {import('vfile').Data['meta']} DataMeta
  * @typedef {import('./sort.js').Item} Item
  */
 
 /**
+ * @typedef {Exclude<DataMeta, undefined>} Meta
+ *
  * @typedef Props
+ *   Props.
  * @property {string} name
+ *   Name.
  * @property {ReactNode} children
+ *   Children.
  * @property {Item} navTree
+ *   Navigation tree.
  * @property {Meta} meta
+ *   Meta.
  */
 
 import React from 'react'
-import {NavSite, NavSiteSkip} from './nav-site.jsx'
 import {FootSite} from './foot-site.jsx'
+import {NavSite, NavSiteSkip} from './nav-site.jsx'
 
 /**
- * @param {Props} props
+ * @param {Readonly<Props>} props
  *   Props.
  * @returns {JSX.Element}
  *   Element.
  */
 export function Home(props) {
-  const {name, meta, navTree, children} = props
-  /** @type {unknown} */
-  // @ts-expect-error: to do: type.
-  const schema = meta.schemaOrg
+  const {children, meta, name, navTree} = props
 
   return (
     <div className="page home">
       <NavSiteSkip />
       <main>
-        {schema ? (
-          <script type="application/ld+json">{JSON.stringify(schema)}</script>
+        {meta.schemaOrg ? (
+          <script type="application/ld+json">
+            {JSON.stringify(meta.schemaOrg)}
+          </script>
         ) : undefined}
         <article>
           <div className="content body">{children}</div>