Typescript definition changes and explaining Sinuous internals

packages/sinuous/h/src/add.js

@@ -8,8 +8,10 @@ const castNode = (value) => {
   if (typeof value === 'string') {
     return document.createTextNode(value);
   }
+  // Note that a DocumentFragment is an instance of Node
   if (!(value instanceof Node)) {
-    // Passing an empty array creates a DocumentFragment.
+    // Passing an empty array creates a DocumentFragment
+    // Note this means api.add is not purely a subcall of api.h; it can nest
     return api.h(EMPTY_ARR, value);
   }
   return value;
@@ -32,7 +34,8 @@ const frag = (value) => {
 
 /**
  * Add a string or node before a reference node or at the end.
- * @typedef {(parent: Node, value: Node | string | number, endMark: Node?) => Node | Frag} hAdd
+ * @typedef {Node | string | number} Value
+ * @typedef {(parent: Node, value: Value | Value[], endMark: Node?) => Node | Frag} hAdd
  * @type {hAdd}
  */
 export const add = (parent, value, endMark) => {

packages/sinuous/h/src/api.js

@@ -2,7 +2,7 @@
  * Internal API.
  * Consumer must provide an observable at api.subscribe<T>(observer: () => T).
  *
- * @typedef {0 | 1} hSVG Determines if `h` will build HTML or SVG elements
+ * @typedef {boolean} hSVG Determines if `h` will build HTML or SVG elements
  * @type {{
  * h:         import('./h.js').hTag
  * s:         hSVG

packages/sinuous/h/src/h.js

@@ -7,7 +7,7 @@ import { api } from './api.js';
  * @typedef {(tag: string? | [], props: object?, ...children: Node | *) => DOM} hTag
  * @type {hTag}
  */
-// eslint-disable-next-line fp/no-rest-parameters
+
 export const h = (...args) => {
   let el;
   const item = (/** @type {*} */ arg) => {

packages/sinuous/h/src/index.d.ts

@@ -11,31 +11,35 @@ declare namespace _h {
         Record<string, unknown>
       | null,
     ...children: ElementChildren[]
-  ): HTMLElement;
+  ): HTMLElement | SVGElement;
   function h(
     type: FunctionComponent,
     props:
       | (JSXInternal.HTMLAttributes | JSXInternal.SVGAttributes) &
         Record<string, unknown>
       | null,
     ...children: ElementChildren[]
-  ): HTMLElement;
+  ): HTMLElement | SVGElement | DocumentFragment;
   function h(
-    children: ElementChildren[]
+    tag: ElementChildren[] | [],
+    ...children: ElementChildren[]
   ): DocumentFragment;
   namespace h {
     export import JSX = JSXInternal;
   }
 }
 
+type Frag = { _startMark: Text }
+type Value = Node | DocumentFragment | string | number
+
 export interface HyperscriptApi {
   // Hyperscript
   h: typeof _h.h;
 
   // Internal API
-  insert<T>(el: Node, value: T, endMark?: Node, current?: T, startNode?: Node): T;
+  insert<T>(el: Node, value: T, endMark?: Node, current?: T | Frag, startNode?: Node): T | Frag;
   property(el: Node, value: unknown, name: string, isAttr?: boolean, isCss?: boolean): void;
-  add(parent: Node, value: Node | string, endMark?: Node): Node;
+  add(parent: Node, value: Value | Value[], endMark?: Node): Node | Frag;
   rm(parent: Node, startNode: Node, endMark: Node): void;
 
   // Required from an observable implmentation

packages/sinuous/h/src/insert.js

@@ -2,7 +2,8 @@ import { api } from './api.js';
 
 /**
  * @typedef {import('./add.js').Frag} Frag
- * @typedef {(el: Node, value: *, endMark: Node?, current: (Node | Frag)?, startNode: Node?) => Node} hInsert
+ * @typedef {(el: Node, value: *, endMark: Node?, current: (Node | Frag)?,
+ * startNode: Node?) => Node | Frag } hInsert
  * @type {hInsert}
  */
 export const insert = (el, value, endMark, current, startNode) => {
@@ -64,5 +65,5 @@ export const insert = (el, value, endMark, current, startNode) => {
     }
   }
 
-  return /** @type {Node} */ (current);
+  return current;
 };

packages/sinuous/src/index.d.ts

@@ -39,9 +39,10 @@ declare namespace sinuous {
         Record<string, unknown>
       | null,
     ...children: ElementChildren[]
-  ): HTMLElement;
+  ): HTMLElement | DocumentFragment;
   function h(
-    children: ElementChildren[]
+    tag: ElementChildren[] | [],
+    ...children: ElementChildren[]
   ): DocumentFragment;
   namespace h {
     export import JSX = JSXInternal;
@@ -62,9 +63,10 @@ declare namespace sinuous {
         Record<string, unknown>
       | null,
     ...children: ElementChildren[]
-  ): SVGElement;
+  ): SVGElement | DocumentFragment;
   function hs(
-    children: ElementChildren[]
+    tag: ElementChildren[] | [],
+    ...children: ElementChildren[]
   ): DocumentFragment;
   namespace hs {
     export import JSX = JSXInternal;
@@ -73,8 +75,7 @@ declare namespace sinuous {
   /** Sinuous API */
   interface SinuousApi extends HyperscriptApi {
     // Hyperscript
-    h: typeof h;
-    hs: typeof hs;
+    hs: <T extends () => unknown>(closure: T) => ReturnType<T>;
 
     // Observable
     subscribe: typeof _o.subscribe;

packages/sinuous/src/index.js

@@ -1,7 +1,7 @@
 /*
-* Sinuous by Wesley Luyten (@luwes).
-* Really ties all the packages together.
-*/
+ * Sinuous by Wesley Luyten (@luwes).
+ * Really ties all the packages together.
+ */
 import {
   o,
   observable,