✨Add support for function elements

Author: cowboyd

lib/core.js

@@ -32,6 +32,10 @@
  *   List of children.
  * @typedef {Node | HPrimitiveChild | HArrayChild} HChild
  *   Acceptable child value.
+ * @typedef {Record<string, unknown>} HComponentProperties
+ *   Acceptable properties for a component function.
+ * @typedef {(props: HComponentProperties) => HResult} HComponent
+ *   Function returning a hyperscript result (useful for JSX)
  */
 
 import {find, normalize} from 'property-information'
@@ -58,18 +62,38 @@ export function core(schema, defaultTagName, caseSensitive) {
      *   (selector: null | undefined, ...children: Array<HChild>): Root
      *   (selector: string, properties: HProperties, ...children: Array<HChild>): Element
      *   (selector: string, ...children: Array<HChild>): Element
+     *   (component: HComponent, props: HComponentProperties, ...children: Array<HChild>): HResult
      * }}
      */
     (
       /**
        * Hyperscript compatible DSL for creating virtual hast trees.
        *
-       * @param {string | null | undefined} [selector]
-       * @param {HProperties | HChild | null | undefined} [properties]
+       * @param {string | null | undefined | HComponent} [selector]
+       * @param {HProperties | HChild | null | undefined | HComponentProperties} [properties]
        * @param {Array<HChild>} children
        * @returns {HResult}
        */
       function (selector, properties, ...children) {
+        if (typeof selector === 'function') {
+          const props = properties ?? {}
+          if (typeof props !== 'object') {
+            // We should rarely hit this case because this codepath is only
+            // called by JSX transforms, but we have to make the check to
+            // satisfy TypeScript.
+            throw new TypeError(
+              `second argument to h(${
+                selector.name
+              }, props) must be an object, but was ${typeof props}`
+            )
+          }
+
+          return selector({
+            ...props,
+            children
+          })
+        }
+
         let index = -1
         /** @type {HResult} */
         let node
@@ -98,6 +122,7 @@ export function core(schema, defaultTagName, caseSensitive) {
               }
             }
           } else {
+            // @ts-expect-error cannot be `HComponentProperties` because we're not on that codepath.
             children.unshift(properties)
           }
         }
@@ -120,7 +145,7 @@ export function core(schema, defaultTagName, caseSensitive) {
 }
 
 /**
- * @param {HProperties | HChild} value
+ * @param {HProperties | HChild | HComponentProperties } value
  * @param {string} name
  * @returns {value is HProperties}
  */

lib/jsx-automatic.d.ts

@@ -1,43 +1,26 @@
 import type {HProperties, HChild, HResult} from './core.js'
 
-export namespace JSX {
-  /**
-   * This defines the return value of JSX syntax.
-   */
-  type Element = HResult
-
-  /**
-   * This disallows the use of functional components.
-   */
-  type IntrinsicAttributes = never
-
-  /**
-   * This defines the prop types for known elements.
-   *
-   * For `hastscript` this defines any string may be used in combination with `hast` `Properties`.
-   *
-   * This **must** be an interface.
-   */
-  // eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style, @typescript-eslint/consistent-type-definitions
-  interface IntrinsicElements {
-    [name: string]:
-      | HProperties
-      | {
-          /**
-           * The prop that matches `ElementChildrenAttribute` key defines the type of JSX children, defines the children type.
-           */
-          children?: HChild
-        }
-  }
+declare global {
+  namespace JSX {
+    /**
+     * Return value of JSX syntax.
+     */
+    type Element = HResult
 
-  /**
-   * The key of this interface defines as what prop children are passed.
-   */
-  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions
-  interface ElementChildrenAttribute {
     /**
-     * Only the key matters, not the value.
+     * This defines the prop types for known elements.
+     *
+     * For `hastscript` this defines any string may be used in combination with `hast` `Properties`.
+     *
+     * This **must** be an interface.
      */
-    children?: never
+    // eslint-disable-next-line @typescript-eslint/consistent-indexed-object-style, @typescript-eslint/consistent-type-definitions
+    interface IntrinsicElements {
+      [name: string]:
+        | HProperties
+        | {
+            children?: HChild
+          }
+    }
   }
 }

lib/jsx-automatic.js

@@ -1,2 +1,3 @@
+/// <reference types="./jsx-automatic.d.ts"/>
 // Empty (only used for TypeScript).
 export {}

lib/runtime.js

@@ -9,6 +9,7 @@
  * @typedef {import('./core.js').core} Core
  *
  * @typedef {Record<string, HPropertyValue | HStyle | HChild>} JSXProps
+ * @typedef {(props: Record<string, unknown>) => HResult} HComponent
  */
 
 /**
@@ -26,13 +27,21 @@ export function runtime(f) {
      */
     (
       /**
-       * @param {string | null} type
+       * @param {string | null | HComponent} component
        * @param {HProperties & {children?: HChild}} props
        * @returns {HResult}
        */
-      function (type, props) {
+      function (component, props, key) {
+        // If (typeof component === 'function') {
+        //   return component({...props, key})
+        // }
+
         const {children, ...properties} = props
-        return type === null ? f(type, children) : f(type, properties, children)
+
+        return component === null
+          ? f(component, children)
+          : // @ts-expect-error we can handle it.
+            f(component, {...properties, key}, children)
       }
     )
 

readme.md

@@ -257,20 +257,13 @@ The syntax tree is [hast][].
 
 ## JSX
 
-This package can be used with JSX.
-You should use the automatic JSX runtime set to `hastscript` (also available as
-the more explicit name `hastscript/html`) or `hastscript/svg`.
+This package can be used with JSX by setting your
+[`jsxImportSource`][jsx-import-source]  to `hastscript`
 
 > 👉 **Note**: while `h` supports dots (`.`) for classes or number signs (`#`)
 > for IDs in `selector`, those are not supported in JSX.
 
-> 🪦 **Legacy**: you can also use the classic JSX runtime, but this is not
-> recommended.
-> To do so, import `h` (or `s`) yourself and define it as the pragma (plus
-> set the fragment to `null`).
-
-The Use example above can then be written like so, using inline pragmas, so
-that SVG can be used too:
+For example, to write the hastscript example provided earlier u
 
 `example-html.jsx`:
 
@@ -287,6 +280,8 @@ console.log(
 )
 ```
 
+SVG can be used too by setting `jxsImportSource` to `hastscript/svg`:
+
 `example-svg.jsx`:
 
 ```jsx
@@ -299,6 +294,15 @@ console.log(
 )
 ```
 
+> 🪦 **Legacy**: you can also use the classic JSX runtime by importing either
+> `h` (or `s`) manually from `hastscript/jsx-factory` and setting it as the
+> `jsxFactory` in your transpiler, but it is not recommended.  For example:
+
+```jsx
+/** @jsxFactory h */
+import { h } from "hastscript/jsx-factory";
+```
+
 ## Types
 
 This package is fully typed with [TypeScript][].
@@ -466,3 +470,5 @@ abide by its terms.
 [properties]: #properties-1
 
 [result]: #result
+
+[jsx-import-source]: https://babeljs.io/docs/babel-plugin-transform-react-jsx#customizing-the-automatic-runtime-import

test-d/automatic-h.tsx

@@ -53,4 +53,4 @@ expectError(<a invalid={[true]} />)
 expectType<Result>(<a children={<b />} />)
 
 declare function Bar(props?: Record<string, unknown>): Element
-expectError(<Bar />)
+expectType<Result>(<Bar />)

test-d/automatic-s.tsx

@@ -43,4 +43,4 @@ expectError(<a invalid={[true]} />)
 expectType<Result>(<a children={<b />} />)
 
 declare function Bar(props?: Record<string, unknown>): Element
-expectError(<Bar />)
+expectType<Result>(<Bar />)

test/jsx.jsx

@@ -125,4 +125,41 @@ test('name', () => {
     ]),
     'should support a fragment in an element (#2)'
   )
+
+  /**
+   * @typedef {import('../lib/core.js').HChild} HChild
+   */
+
+  /**
+   * @param {{key: HChild; value: HChild}} options
+   * @returns {JSX.Element}
+   */
+  // eslint-disable-next-line no-unused-vars
+  const DlEntry = ({key, value}) => (
+    <>
+      <dt>{key}</dt>
+      <dd>{value}</dd>
+    </>
+  )
+
+  /**
+   * @param {{ children?: HChild }} options
+   * @returns {JSX.Element}
+   */
+  // eslint-disable-next-line no-unused-vars
+  const Dl = ({children}) => <dl>{children}</dl>
+
+  assert.deepEqual(
+    <Dl>
+      <DlEntry key="Firefox" value="A red panda." />
+      <DlEntry key="Chrome" value="A chemical element." />
+    </Dl>,
+    h('dl', [
+      h('dt', 'Firefox'),
+      h('dd', 'A red panda.'),
+      h('dt', 'Chrome'),
+      h('dd', 'A chemical element.')
+    ]),
+    'should support functional elements'
+  )
 })