New and clearer descriptors proposal

Author: sebmarkbage

Diff for: 01 - Core/01 - Classes.js

@@ -1,8 +1,3 @@
-// Instead of using @jsx directive we import the HTML export from react-dom
-// and bind it to the JSX identifier. This models the DOM dependency explicitly.
-// The JSX transpiler uses this identifier to resolve HTML tags. E.g. JSX.div();
-import { HTML as JSX } from "react-dom";
-
 // The only reason we need a React depencency here is because the base class
 // provides the this.setState method.
 import { Component } from "react";

Diff for: 01 - Core/02 - Mixins.js

@@ -1,5 +1,3 @@
-import { Component } from "react";
-import { HTML as JSX } from "react-dom";
 import { mixin } from "react-utils";
 
 // Chainable mixins
@@ -44,9 +42,12 @@ class C extends mixin(A, B) {
 C.getQueries(); // B, C
 new C().componentDidMount(); // B, A, C
 
+
+import { Component } from "react";
+
 // A component that mixes in all of C's functionality
 
-class Component extends mixin(React.Component, C) {
+class Component extends mixin(Component, C) {
   render() {
     return <div />;
   }

Diff for: 01 - Core/03 - Stateless Functions.js

@@ -1,7 +1,3 @@
-// Instead of using @jsx directive we import the HTML export from react-dom
-// and bind it to the JSX identifier.
-import { HTML as JSX } from "react-dom";
-
 // A simple component, that isn't stateful, can be provided as a single
 // function that accepts props. This provides React with a hint that this
 // component can be collapsed and that it's state doesn't need to be preserved.

Diff for: 01 - Core/05 - Descriptor Factories.js

@@ -0,0 +1,119 @@
+/**
+ * DESCRIPTOR OBJECT LITERAL
+ *
+ * A React component module will no longer export a helper function to create
+ * descriptors. Instead it's the responsibility of the consumer to efficiently
+ * create the descriptors.
+ * 
+ * Languages that compile to JS can choose to implement the descriptor signature
+ * in whatever way is idiomatic for that language:
+ */
+
+{
+  type: Button,
+  props: {
+    ...Button.defaultProps, // optional
+    foo: 'bar',
+    children: [
+      { type: 'span', props: { children: a } },
+      { type: 'span', props: { children: b } }
+    ]
+  },
+
+  // optional
+  key: 'mybutton',
+  ref: myButtonRef,
+
+  // optional
+  owner: React.currentOwner,
+  context: React.currentContext
+}
+
+/**
+ * JSX
+ */
+
+<Button foo="bar" key="mybutton" ref={myButtonRef}>
+ <span>{a}</span>
+ <span>{b}</span>
+</Button>
+
+/**
+ * PLAIN JS
+ *
+ * This helper function ensures that your static children don't get the key
+ * warning. It creates a descriptor for you with the current owner/context.
+ * The props object is cloned and key/ref moved onto the descriptor.
+ */
+
+var C = React.createDescriptor;
+
+C(Button, { foo: 'bar', key: 'mybutton', ref: myButtonRef },
+  C('span', null, a),
+  C('span', null, b)
+)
+
+/**
+ * If you use JSX or statically can analyze that the C(...) call belongs to
+ * React, then you can chose to opt-in to one of the optimizations modes.
+ */
+
+/**
+ * FAST MODE
+ *
+ * Fast mode allocates the final props object inline instead of cloning a
+ * temporary object. If defaultProps can be statically resolved, their value is
+ * inlined (baz: 1) instead of dynamically resolved. This should not be typed
+ * manually in user code.
+ */
+
+var F = React.createDescriptorFast;
+
+F(Button, 'mybutton', myButtonRef, { foo: 'bar', baz: 1, children: [
+  F('span', null, null, a),
+  F('span', null, null, b)
+]})
+
+/**
+ * POOLED MODE
+ *
+ * Pooled mode doesn't allocate any new objects. Instead it gets mutable objects
+ * from an pool and reuses them. It overrides the props on the pooled object.
+ */
+
+var P = React.getPooledDescriptor;
+var A = React.getPooledArray;
+var t1, t2;
+
+(t1 = P(Button, 'mybutton', myButtonRef), t1.props.foo = 'bar', t1.props.children = A(
+  (t2 = P('span'), t2.props.children = a, t2),
+  (t2 = P('span'), t2.props.children = b, t2)
+), t1)
+
+/**
+ * NATIVE COMPONENTS
+ *
+ * Note that DOM nodes are no longer functions on React.DOM, instead they're
+ * just strings. JSX will convert any lower-case tag name, or if it has a dash,
+ * into a string value instead of a scope reference. This makes them compatible
+ * with custom tags (Web Components).
+ *
+ * There's no direct dependency between a component and the React runtime.
+ *
+ * A tree of just native components should be JSON serializable.
+ */
+
+/**
+ * TEMPLATE STRINGS
+ *
+ * You could great an add-on sugar which uses ES6 template strings to create
+ * descriptors. It becomes more palatable if all your components are registered
+ * through strings.
+ */
+
+X`
+ <my-button foo="bar" key="mybutton" ref=${myButtonRef}>
+   <span>${a}</span>
+   <span>${b}</span>
+ </my-button>
+`

Diff for: 01 - Core/05 - Descriptors.js

@@ -1,8 +1,8 @@
-import { HTML as JSX, joinClasses } from "react-dom";
+import { HTMLProps, joinClasses } from "react-dom";
 
 // Draft
 
-interface FancyButtonProps extends typeof JSX.button.prototype.props {
+interface FancyButtonProps extends typeof HTMLProps.button {
     color: string,
     width: number,
     height: number