From fcfe9c9a6ed90f2e59c2235a2589d753f73537b7 Mon Sep 17 00:00:00 2001 From: Xuan Huang Date: Tue, 22 Feb 2022 22:01:37 -0800 Subject: [PATCH] Migrate to ecmarkup This is the first step to revamp this repo: [ecmarkup](https://github.com/tc39/ecmarkup) is TC39's official tool for specifying syntax and semantics for ECMAScript. I proposed that we should adopt it because it has several favorabilities than the current approach (`README.md` + a `gh-pages` website living in the `websitescript` branch): 1. The resultant `index.html` has a similar looks and feels with the official ECMA-262 spec. 2. It uses [Grammarkdown](https://github.com/rbuckton/grammarkdown) which is not only convenient to write but more importantly, can enforce the grammar to be more formal. 3. It provides links to ECMA-262 out of the box (closed #112). Furthurmore, I can use `` to make "extension" points explicit. One possible concern it that it'll make this too like a ECMAScript proposal, but I think we mediated by opting-out from the "stage-N proposal" heading, and by explicitly calling out our intention in the "Introduction" section. In addition, - Link to JXON is updated since the original link no more existed. - Parser and Transpiler section is dropped from the "spec" website. - Facebook, Inc. is updated to Meta Platform, Inc everywhere. Once this is merged, we can switch to `main` to host Github Pages. --- .gitignore | 43 + README.md | 143 +-- index.html | 2749 ++++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 11 + spec.emu | 258 +++++ 5 files changed, 3069 insertions(+), 135 deletions(-) create mode 100644 .gitignore create mode 100644 index.html create mode 100644 package.json create mode 100644 spec.emu diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..434262c --- /dev/null +++ b/.gitignore @@ -0,0 +1,43 @@ +# Logs +logs +*.log +npm-debug.log* + +# Runtime data +pids +*.pid +*.seed + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (http://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +node_modules +jspm_packages + +# Optional npm cache directory +.npm + +# Optional REPL history +.node_repl_history + +# Only apps should have lockfiles +yarn.lock +package-lock.json +npm-shrinkwrap.json +pnpm-lock.yaml diff --git a/README.md b/README.md index e195e25..308d870 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,8 @@ DRAFT: JSX Specification ======================== -JSX is an XML-like syntax extension to ECMAScript without any defined semantics. It's NOT intended to be implemented by engines or browsers. __It's NOT a proposal to incorporate JSX into the ECMAScript spec itself.__ It's intended to be used by various preprocessors (transpilers) to transform these tokens into standard ECMAScript. + +JSX is an XML-like syntax extension to ECMAScript without any defined semantics. It's NOT intended to be implemented by engines or browsers. __It's NOT a proposal to incorporate JSX into the ECMAScript spec itself.__ It's intended to be used by various preprocessors (transpilers) to transform these tokens into standard ECMAScript. ```jsx // Using JSX to express UI components. @@ -18,6 +19,11 @@ var dropdown = render(dropdown); ``` +[See grammar and spec text](https://facebook.github.io/jsx). + + + + Rationale --------- @@ -31,139 +37,6 @@ It is our intention to claim minimal syntactic real estate while keeping the syn This specification does not attempt to comply with any XML or HTML specification. JSX is designed as an ECMAScript feature and the similarity to XML is only for familiarity. -Syntax ------- - -_JSX extends the PrimaryExpression in the [ECMAScript 6th Edition (ECMA-262)](https://www.ecma-international.org/ecma-262/8.0/index.html) grammar:_ - -PrimaryExpression : - -- JSXElement -- JSXFragment - -__Elements__ - -JSXElement :
 - -- JSXSelfClosingElement
 -- JSXOpeningElement JSXChildrenopt JSXClosingElement - (names of JSXOpeningElement and JSXClosingElement should match) - -JSXSelfClosingElement : - -- `<` JSXElementName JSXAttributesopt `/` `>` - -JSXOpeningElement : - -- `<` JSXElementName JSXAttributesopt `>` - -JSXClosingElement : - -- `<` `/` JSXElementName `>` - -JSXFragment : - -- `<` `>` JSXChildrenopt `<` `/` `>` - -JSXElementName : - -- JSXIdentifier -- JSXNamespacedName -- JSXMemberExpression - -JSXIdentifier : - -- IdentifierStart -- JSXIdentifier IdentifierPart -- JSXIdentifier __NO WHITESPACE OR COMMENT__ `-` - -JSXNamespacedName : - -- JSXIdentifier `:` JSXIdentifier - -JSXMemberExpression : - -- JSXIdentifier `.` JSXIdentifier -- JSXMemberExpression `.` JSXIdentifier - -__Attributes__ - -JSXAttributes :
 - -- JSXSpreadAttribute JSXAttributesopt -- JSXAttribute JSXAttributesopt - -JSXSpreadAttribute : - -- `{` `...` AssignmentExpression `}` - -JSXAttribute :
 - -- JSXAttributeName JSXAttributeInitializeropt - -JSXAttributeName : - -- JSXIdentifier -- JSXNamespacedName - -JSXAttributeInitializer :
 - -- `=` JSXAttributeValue - -JSXAttributeValue :
 - -- `"` JSXDoubleStringCharactersopt `"` -- `'` JSXSingleStringCharactersopt `'` -- `{` AssignmentExpression `}` -- JSXElement -- JSXFragment - -JSXDoubleStringCharacters :
 - -- JSXDoubleStringCharacter JSXDoubleStringCharactersopt - -JSXDoubleStringCharacter :
 - -- SourceCharacter __but not `"`__ - -JSXSingleStringCharacters :
 - -- JSXSingleStringCharacter JSXSingleStringCharactersopt - -JSXSingleStringCharacter :
 - -- SourceCharacter __but not `'`__ - -__Children__ - -JSXChildren :
 - -- JSXChild JSXChildrenopt - -JSXChild : - -- JSXText -- JSXElement -- JSXFragment -- `{` JSXChildExpressionopt `}` - -JSXText : - -- JSXTextCharacter JSXTextopt - -JSXTextCharacter : - -- SourceCharacter __but not one of `{`, `<`, `>` or `}`__ - -JSXChildExpression : - -- AssignmentExpression -- `...` AssignmentExpression - -__Whitespace and Comments__ - -_JSX uses the same punctuators and braces as ECMAScript. WhiteSpace, LineTerminators and Comments are generally allowed between any punctuators._ - Parser Implementations ---------------------- @@ -255,7 +128,7 @@ The JSX syntax is similar to the [E4X Specification (ECMA-357)](http://www.ecma- License ------- -Copyright (c) 2014 - present, Facebook, Inc. +Copyright (c) 2014 - present, Meta Platform, Inc. All rights reserved. This work is licensed under a [Creative Commons Attribution 4.0 diff --git a/index.html b/index.html new file mode 100644 index 0000000..be0e5ad --- /dev/null +++ b/index.html @@ -0,0 +1,2749 @@ + + + + + +JSX
+
    +
  • Toggle shortcuts help?
  • +
  • Toggle "can call user code" annotationsu
  • + +
  • Jump to search box/
  • +

Draft / February 23, 2022

JSX

+ + +

Introduction

+

JSX is an XML-like syntax extension to ECMAScript without any defined semantics. It's NOT intended to be implemented by engines or browsers. It's NOT a proposal to incorporate JSX into the ECMAScript spec itself. It's intended to be used by various preprocessors (transpilers) to transform these tokens into standard ECMAScript. +

+ + +
// Using JSX to express UI components
+var dropdown =
+  <Dropdown>
+    A dropdown list
+    <Menu>
+      <MenuItem>Do Something</MenuItem>
+      <MenuItem>Do Something Fun!</MenuItem>
+      <MenuItem>Do Something Else</MenuItem>
+    </Menu>
+  </Dropdown>;
+
+render(dropdown);
+ + +

Rationale

+

The purpose of this specification is to define a concise and familiar syntax for defining tree structures with attributes. A generic but well defined syntax enables a community of independent parsers and syntax highlighters to conform to a single specification.

+

Embedding a new syntax in an existing language is a risky venture. Other syntax implementors or the existing language may introduce another incompatible syntax extension.

+

Through a stand-alone specification, we make it easier for implementors of other syntax extensions to consider JSX when designing their own syntax. This will hopefully allow various new syntax extensions to co-exist.

+

It is our intention to claim minimal syntactic real estate while keeping the syntax concise and familiar. That way we leave the door open for other extensions.

+

This specification does not attempt to comply with any XML or HTML specification. JSX is designed as an ECMAScript feature and the similarity to XML is only for familiarity.

+ +
+
+ + + +

1 JSX Definition

+ + +

1.1 Modified Productions

+

JSX extends the PrimaryExpression in the ECMAScript (ECMA-262) grammar:

+ +

Syntax

+ + PrimaryExpression : JSXElement + JSXFragment + + +
+ + +

1.2 JSX Elements

+

Syntax

+ + + JSXElement : JSXSelfClosingElement + + JSXOpeningElement + JSXChildrenopt + JSXClosingElement + + + + + Note
+ names of JSXOpeningElement and JSXClosingElement should match. +
+ + + JSXSelfClosingElement : + < + JSXElementName + JSXAttributesopt + / + > + + + + JSXOpeningElement : + < + JSXElementName + JSXAttributesopt + > + + + + JSXClosingElement : + < + / + JSXElementName + > + + + + JSXFragment : + < + > + JSXChildrenopt + < + / + > + + + + JSXElementName : JSXIdentifier + JSXNamespacedName + JSXMemberExpression + + + JSXIdentifier : IdentifierStart + + JSXIdentifier + IdentifierPart + + + JSXIdentifier + [no WhiteSpace or Comment here] + - + + + + JSXNamespacedName : + JSXIdentifier + : + JSXIdentifier + + + + JSXMemberExpression : + JSXIdentifier + . + JSXIdentifier + + + JSXMemberExpression + . + JSXIdentifier + + + +
+ + +

1.3 JSX Attributes

+

Syntax

+ + + JSXAttributes : + JSXSpreadAttribute + JSXAttributesopt + + + JSXAttribute + JSXAttributesopt + + + + JSXSpreadAttribute : + { + ... + AssignmentExpression + } + + + + JSXAttribute : + JSXAttributeName + JSXAttributeInitializeropt + + + + JSXAttributeName : JSXIdentifier + JSXNamespacedName + + + JSXAttributeInitializer : + = + JSXAttributeValue + + + + JSXAttributeValue : + " + JSXDoubleStringCharactersopt + " + + + ' + JSXSingleStringCharactersopt + ' + + + { + AssignmentExpression + } + + JSXElement + JSXFragment + + + JSXDoubleStringCharacters : + JSXDoubleStringCharacter + JSXDoubleStringCharactersopt + + + + JSXDoubleStringCharacter : SourceCharacter but not " + + + JSXSingleStringCharacters : + JSXSingleStringCharacter + JSXSingleStringCharactersopt + + + + JSXSingleStringCharacter : SourceCharacter but not ' + + +
+ + +

1.4 JSX Children

+

Syntax

+ + + JSXChildren : + JSXChild + JSXChildrenopt + + + + JSXChild : JSXText + JSXElement + + { + JSXChildExpressionopt + } + + + + JSXText : + JSXTextCharacter + JSXTextopt + + + + JSXTextCharacter : SourceCharacter but not one of { or < or > or } + + + JSXChildExpression : AssignmentExpression + + ... + AssignmentExpression + + + +
+
+ + +

A Why not Template Literals?

+

ECMAScript 6th Edition (ECMA-262) introduces template literals which are intended to be used for embedding DSL in ECMAScript. Why not just use that instead of inventing a syntax that's not part of ECMAScript?

+

Template literals work well for long embedded DSLs. Unfortunately the syntax noise is substantial when you exit in and out of embedded arbitrary ECMAScript expressions with identifiers in scope.

+ +
// Template Literals
+var box = jsx`
+  <${Box}>
+    ${
+      shouldShowAnswer(user) ?
+      jsx`<${Answer} value=${false}>no</${Answer}>` :
+      jsx`
+        <${Box.Comment}>
+         Text Content
+        </${Box.Comment}>
+      `
+    }
+  </${Box}>
+`;
+ +

It would be possible to use template literals as a syntactic entry point and change the semantics inside the template literal to allow embedded scripts that can be evaluated in scope:

+ +
// Template Literals with embedded JSX
+var box = jsx`
+  <Box>
+    {
+      shouldShowAnswer(user) ?
+      <Answer value={false}>no</Answer> :
+      <Box.Comment>
+         Text Content
+      </Box.Comment>
+    }
+  </Box>
+`;
+ +

However, this would lead to further divergence. Tooling that is built around the assumptions imposed by template literals wouldn't work. It would undermine the meaning of template literals. It would be necessary to define how JSX behaves within the rest of the ECMAScript grammar within the template literal anyway.

+ +

Therefore it's better to introduce JSX as an entirely new type of PrimaryExpression:

+ +
// JSX
+var box =
+  <Box>
+    {
+      shouldShowAnswer(user) ?
+      <Answer value={false}>no</Answer> :
+      <Box.Comment>
+         Text Content
+      </Box.Comment>
+    }
+  </Box>;
+ +Note
+ Don't you love the syntax highlighting here? ;) +
+ +
+ + + +

B Why not JXON?

+

Another alternative would be to use object initializers (similar to JXON). Unfortunately, the balanced braces do not give great syntactic hints for where an element starts and ends in large trees. Balanced named tags is a critical syntactic feature of the XML-style notation.

+
+ + +

C Prior Art

+

The JSX syntax is similar to the E4X Specification (ECMA-357). E4X is a deprecated specification with deep reaching semantic meaning. JSX partially overlaps with a tiny subset of the E4X syntax. However, JSX has no relation to the E4X specification.

+
+ + +

D License

+

Copyright (c) 2014 - present, Meta Platforms, Inc. All rights reserved.

+

+This work is licensed under a Creative Commons Attribution 4.0 International License. +

+
+
\ No newline at end of file diff --git a/package.json b/package.json new file mode 100644 index 0000000..b15bbb7 --- /dev/null +++ b/package.json @@ -0,0 +1,11 @@ +{ + "private": true, + "scripts": { + "start": "npm run build-loose -- --watch", + "build": "npm run build-loose -- --strict", + "build-loose": "ecmarkup --verbose spec.emu index.html" + }, + "devDependencies": { + "ecmarkup": "^9.8.1" + } +} diff --git a/spec.emu b/spec.emu new file mode 100644 index 0000000..312bd05 --- /dev/null +++ b/spec.emu @@ -0,0 +1,258 @@ + + + + + + + + +

Introduction

+

JSX is an XML-like syntax extension to ECMAScript without any defined semantics. It's NOT intended to be implemented by engines or browsers. It's NOT a proposal to incorporate JSX into the ECMAScript spec itself. It's intended to be used by various preprocessors (transpilers) to transform these tokens into standard ECMAScript. +

+ + +

+// Using JSX to express UI components
+var dropdown =
+  <Dropdown>
+    A dropdown list
+    <Menu>
+      <MenuItem>Do Something</MenuItem>
+      <MenuItem>Do Something Fun!</MenuItem>
+      <MenuItem>Do Something Else</MenuItem>
+    </Menu>
+  </Dropdown>;
+
+render(dropdown);
+  
+ + +

Rationale

+

The purpose of this specification is to define a concise and familiar syntax for defining tree structures with attributes. A generic but well defined syntax enables a community of independent parsers and syntax highlighters to conform to a single specification.

+

Embedding a new syntax in an existing language is a risky venture. Other syntax implementors or the existing language may introduce another incompatible syntax extension.

+

Through a stand-alone specification, we make it easier for implementors of other syntax extensions to consider JSX when designing their own syntax. This will hopefully allow various new syntax extensions to co-exist.

+

It is our intention to claim minimal syntactic real estate while keeping the syntax concise and familiar. That way we leave the door open for other extensions.

+

This specification does not attempt to comply with any XML or HTML specification. JSX is designed as an ECMAScript feature and the similarity to XML is only for familiarity.

+ +
+
+ + + +

JSX Definition

+ + +

Modified Productions

+

JSX extends the |PrimaryExpression| in the ECMAScript (ECMA-262) grammar:

+ +

Syntax

+ + PrimaryExpression : + JSXElement + JSXFragment + +
+ + +

JSX Elements

+

Syntax

+ + +JSXElement : + JSXSelfClosingElement + JSXOpeningElement JSXChildren? JSXClosingElement + + + + names of |JSXOpeningElement| and |JSXClosingElement| should match. + + + +JSXSelfClosingElement : + `<` JSXElementName JSXAttributes? `/` `>` + +JSXOpeningElement : + `<` JSXElementName JSXAttributes? `>` + +JSXClosingElement : + `<` `/` JSXElementName `>` + +JSXFragment : + `<` `>` JSXChildren? `<` `/` `>` + +JSXElementName : + JSXIdentifier + JSXNamespacedName + JSXMemberExpression + +JSXIdentifier : + IdentifierStart + JSXIdentifier IdentifierPart + JSXIdentifier [no one of WhiteSpace or Comment here] `-` + +JSXNamespacedName : + JSXIdentifier `:` JSXIdentifier + +JSXMemberExpression : + JSXIdentifier `.` JSXIdentifier + JSXMemberExpression `.` JSXIdentifier + + +
+ + +

JSX Attributes

+

Syntax

+ + +JSXAttributes : + JSXSpreadAttribute JSXAttributes? + JSXAttribute JSXAttributes? + +JSXSpreadAttribute : + `{` `...` AssignmentExpression `}` + +JSXAttribute : + JSXAttributeName JSXAttributeInitializer? + +JSXAttributeName : + JSXIdentifier + JSXNamespacedName + +JSXAttributeInitializer : + `=` JSXAttributeValue + +JSXAttributeValue : + `"` JSXDoubleStringCharacters? `"` + `'` JSXSingleStringCharacters? `'` + `{` AssignmentExpression `}` + JSXElement + JSXFragment + +JSXDoubleStringCharacters : + JSXDoubleStringCharacter JSXDoubleStringCharacters? + +JSXDoubleStringCharacter : + SourceCharacter but not `"` + +JSXSingleStringCharacters : + JSXSingleStringCharacter JSXSingleStringCharacters? + +JSXSingleStringCharacter : + SourceCharacter but not `'` + +
+ + +

JSX Children

+

Syntax

+ + +JSXChildren : + JSXChild JSXChildren? + +JSXChild : + JSXText + JSXElement + `{` JSXChildExpression? `}` + +JSXText : + JSXTextCharacter JSXText? + +JSXTextCharacter : + SourceCharacter but not one of `{` or `<` or `>` or `}` + +JSXChildExpression : + AssignmentExpression + `...` AssignmentExpression + + +
+
+ + +

Why not Template Literals?

+

ECMAScript 6th Edition (ECMA-262) introduces template literals which are intended to be used for embedding DSL in ECMAScript. Why not just use that instead of inventing a syntax that's not part of ECMAScript?

+

Template literals work well for long embedded DSLs. Unfortunately the syntax noise is substantial when you exit in and out of embedded arbitrary ECMAScript expressions with identifiers in scope.

+ +

+// Template Literals
+var box = jsx`
+  <${Box}>
+    ${
+      shouldShowAnswer(user) ?
+      jsx`<${Answer} value=${false}>no</${Answer}>` :
+      jsx`
+        <${Box.Comment}>
+         Text Content
+        </${Box.Comment}>
+      `
+    }
+  </${Box}>
+`;
+
+ +

It would be possible to use template literals as a syntactic entry point and change the semantics inside the template literal to allow embedded scripts that can be evaluated in scope:

+ +

+// Template Literals with embedded JSX
+var box = jsx`
+  <Box>
+    {
+      shouldShowAnswer(user) ?
+      <Answer value={false}>no</Answer> :
+      <Box.Comment>
+         Text Content
+      </Box.Comment>
+    }
+  </Box>
+`;
+
+ +

However, this would lead to further divergence. Tooling that is built around the assumptions imposed by template literals wouldn't work. It would undermine the meaning of template literals. It would be necessary to define how JSX behaves within the rest of the ECMAScript grammar within the template literal anyway.

+ +

Therefore it's better to introduce JSX as an entirely new type of PrimaryExpression:

+ +

+// JSX
+var box =
+  <Box>
+    {
+      shouldShowAnswer(user) ?
+      <Answer value={false}>no</Answer> :
+      <Box.Comment>
+         Text Content
+      </Box.Comment>
+    }
+  </Box>;
+
+ + + Don't you love the syntax highlighting here? ;) + + +
+ + + +

Why not JXON?

+

Another alternative would be to use object initializers (similar to JXON). Unfortunately, the balanced braces do not give great syntactic hints for where an element starts and ends in large trees. Balanced named tags is a critical syntactic feature of the XML-style notation.

+
+ + +

Prior Art

+

The JSX syntax is similar to the E4X Specification (ECMA-357). E4X is a deprecated specification with deep reaching semantic meaning. JSX partially overlaps with a tiny subset of the E4X syntax. However, JSX has no relation to the E4X specification.

+
+ + +

License

+

Copyright (c) 2014 - present, Meta Platforms, Inc. All rights reserved.

+

+This work is licensed under a Creative Commons Attribution 4.0 International License. +

+