From 3443028963d8efe8092c204b6be6caa637e17c69 Mon Sep 17 00:00:00 2001 From: overlookmotel Date: Wed, 18 Sep 2024 15:26:41 +0100 Subject: [PATCH] docs(transformer): JSX: convert docs to standard format --- .../oxc_transformer/src/react/display_name.rs | 55 ++++++-- crates/oxc_transformer/src/react/jsx.rs | 119 +++++++++++++----- crates/oxc_transformer/src/react/jsx_self.rs | 38 ++++-- .../oxc_transformer/src/react/jsx_source.rs | 43 +++++-- 4 files changed, 202 insertions(+), 53 deletions(-) diff --git a/crates/oxc_transformer/src/react/display_name.rs b/crates/oxc_transformer/src/react/display_name.rs index 9cc733cc78940e..b0c58d3e027ecc 100644 --- a/crates/oxc_transformer/src/react/display_name.rs +++ b/crates/oxc_transformer/src/react/display_name.rs @@ -1,3 +1,50 @@ +//! React Display Name +//! +//! Adds `displayName` property to `React.createClass` calls. +//! +//! > This plugin is included in `preset-react`. +//! +//! ## Example +//! +//! Input: +//! ```js +//! // some_filename.jsx +//! var foo = React.createClass({}); // React <= 15 +//! bar = createReactClass({}); // React 16+ +//! +//! var obj = { prop: React.createClass({}) }; +//! obj.prop2 = React.createClass({}); +//! obj["prop 3"] = React.createClass({}); +//! export default React.createClass({}); +//! ``` +//! +//! Output: +//! ```js +//! var foo = React.createClass({ displayName: "foo" }); +//! bar = createReactClass({ displayName: "bar" }); +//! +//! var obj = { prop: React.createClass({ displayName: "prop" }) }; +//! obj.prop2 = React.createClass({ displayName: "prop2" }); +//! obj["prop 3"] = React.createClass({ displayName: "prop 3" }); +//! export default React.createClass({ displayName: "some_filename" }); +//! ``` +//! +//! ## Implementation +//! +//! Implementation based on [@babel/plugin-transform-react-display-name](https://babeljs.io/docs/babel-plugin-transform-react-display-name). +//! +//! Babel does not get the display name for this example: +//! +//! ```js +//! obj["prop 3"] = React.createClass({}); +//! ``` +//! +//! This implementation does, which is a divergence from Babel, but probably an improvement. +//! +//! ## References: +//! +//! * Babel plugin implementation: + use oxc_allocator::Box; use oxc_ast::ast::*; use oxc_span::{Atom, SPAN}; @@ -5,14 +52,6 @@ use oxc_traverse::{Ancestor, Traverse, TraverseCtx}; use crate::context::Ctx; -/// [plugin-transform-react-display-name](https://babeljs.io/docs/babel-plugin-transform-react-display-name) -/// -/// This plugin is included in `preset-react`. -/// -/// ## Example -/// -/// In: `var bar = createReactClass({});` -/// Out: `var bar = createReactClass({ displayName: "bar" });` pub struct ReactDisplayName<'a> { ctx: Ctx<'a>, } diff --git a/crates/oxc_transformer/src/react/jsx.rs b/crates/oxc_transformer/src/react/jsx.rs index 5132f33e1ad31e..c58c84f90540fa 100644 --- a/crates/oxc_transformer/src/react/jsx.rs +++ b/crates/oxc_transformer/src/react/jsx.rs @@ -1,3 +1,93 @@ +//! React JSX +//! +//! This plugin transforms React JSX to JS. +//! +//! > This plugin is included in `preset-react`. +//! +//! Has two modes which create different output: +//! 1. Automatic +//! 2. Classic +//! +//! And also prod/dev modes: +//! 1. Production +//! 2. Development +//! +//! ## Example +//! +//! ### Automatic +//! +//! Input: +//! ```js +//!
foo
; +//! foo; +//! <>foo; +//! ``` +//! +//! Output: +//! ```js +//! // Production mode +//! import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime"; +//! _jsx("div", { children: "foo" }); +//! _jsx(Bar, { children: "foo" }); +//! _jsx(_Fragment, { children: "foo" }); +//! ``` +//! +//! ```js +//! // Development mode +//! var _jsxFileName = "/test.js"; +//! import { jsxDEV as _jsxDEV, Fragment as _Fragment } from "react/jsx-dev-runtime"; +//! _jsxDEV( +//! "div", { children: "foo" }, void 0, false, +//! { fileName: _jsxFileName, lineNumber: 1, columnNumber: 1 }, +//! this +//! ); +//! _jsxDEV( +//! Bar, { children: "foo" }, void 0, false, +//! { fileName: _jsxFileName, lineNumber: 2, columnNumber: 1 }, +//! this +//! ); +//! _jsxDEV(_Fragment, { children: "foo" }, void 0, false); +//! ``` +//! +//! ### Classic +//! +//! Input: +//! ```js +//!
foo
; +//! foo; +//! <>foo; +//! ``` +//! +//! Output: +//! ```js +//! // Production mode +//! React.createElement("div", null, "foo"); +//! React.createElement(Bar, null, "foo"); +//! React.createElement(React.Fragment, null, "foo"); +//! ``` +//! +//! ```js +//! // Development mode +//! var _jsxFileName = "/test.js"; +//! React.createElement("div", { +//! __self: this, +//! __source: { fileName: _jsxFileName, lineNumber: 1, columnNumber: 1 } +//! }, "foo"); +//! React.createElement(Bar, { +//! __self: this, +//! __source: { fileName: _jsxFileName, lineNumber: 2, columnNumber: 1 } +//! }, "foo"); +//! React.createElement(React.Fragment, null, "foo"); +//! ``` +//! +//! ## Implementation +//! +//! Implementation based on [@babel/plugin-transform-react-jsx](https://babeljs.io/docs/babel-plugin-transform-react-jsx). +//! +//! ## References: +//! +//! * Babel plugin implementation: + use std::rc::Rc; use oxc_allocator::Vec; @@ -22,16 +112,6 @@ use crate::{ helpers::{bindings::BoundIdentifier, module_imports::NamedImport}, }; -/// [plugin-transform-react-jsx](https://babeljs.io/docs/babel-plugin-transform-react-jsx) -/// -/// This plugin generates production-ready JS code. -/// -/// This plugin is included in `preset-react`. -/// -/// References: -/// -/// * -/// * pub struct ReactJsx<'a> { options: ReactOptions, @@ -417,25 +497,6 @@ impl<'a> ReactJsx<'a> { program.body.splice(index..index, imports); } - /// ## Automatic - /// ### Element - /// Builds JSX into: - /// - Production: React.jsx(type, arguments, key) - /// - Development: React.jsxDEV(type, arguments, key, isStaticChildren, source, self) - /// - /// ### Fragment - /// Builds JSX Fragment <> into - /// - Production: React.jsx(type, arguments) - /// - Development: React.jsxDEV(type, { children }) - /// - /// ## Classic - /// ### Element - /// - Production: React.createElement(type, arguments, children) - /// - Development: React.createElement(type, arguments, children, source, self) - /// - /// ### Fragment - /// React.createElement(React.Fragment, null, ...children) - /// fn transform_jsx<'b>( &mut self, e: &JSXElementOrFragment<'a, 'b>, diff --git a/crates/oxc_transformer/src/react/jsx_self.rs b/crates/oxc_transformer/src/react/jsx_self.rs index 60979bd7f5b10c..5f96e1fb384d9c 100644 --- a/crates/oxc_transformer/src/react/jsx_self.rs +++ b/crates/oxc_transformer/src/react/jsx_self.rs @@ -1,3 +1,33 @@ +//! React JSX Self +//! +//! This plugin adds `__self` attribute to JSX elements. +//! +//! > This plugin is included in `preset-react`. +//! +//! ## Example +//! +//! Input: +//! ```js +//!
foo
; +//! foo; +//! <>foo; +//! ``` +//! +//! Output: +//! ```js +//!
foo
; +//! foo; +//! <>foo; +//! ``` +//! +//! ## Implementation +//! +//! Implementation based on [@babel/plugin-transform-react-jsx-self](https://babeljs.io/docs/babel-plugin-transform-react-jsx-self). +//! +//! ## References: +//! +//! * Babel plugin implementation: + use oxc_ast::ast::*; use oxc_diagnostics::OxcDiagnostic; use oxc_span::{Span, SPAN}; @@ -7,14 +37,6 @@ use crate::context::Ctx; const SELF: &str = "__self"; -/// [plugin-transform-react-jsx-self](https://babeljs.io/docs/babel-plugin-transform-react-jsx-self) -/// -/// This plugin is included in `preset-react` and only enabled in development mode. -/// -/// ## Example -/// -/// In: `` -/// Out: `` pub struct ReactJsxSelf<'a> { ctx: Ctx<'a>, } diff --git a/crates/oxc_transformer/src/react/jsx_source.rs b/crates/oxc_transformer/src/react/jsx_source.rs index 8809114ed8a808..5ba0a8f0f83f3b 100644 --- a/crates/oxc_transformer/src/react/jsx_source.rs +++ b/crates/oxc_transformer/src/react/jsx_source.rs @@ -1,3 +1,38 @@ +//! React JSX Source +//! +//! This plugin adds `__source` attribute to JSX elements. +//! +//! > This plugin is included in `preset-react`. +//! +//! ## Example +//! +//! Input: +//! ```js +//!
foo
; +//! foo; +//! <>foo; +//! ``` +//! +//! Output: +//! ```js +//! var _jsxFileName = "/test.js"; +//!
foo
; +//! foo; +//! <>foo; +//! ``` +//! +//! ## Implementation +//! +//! Implementation based on [@babel/plugin-transform-react-jsx-source](https://babeljs.io/docs/babel-plugin-transform-react-jsx-source). +//! +//! ## References: +//! +//! * Babel plugin implementation: + use oxc_ast::{ast::*, NONE}; use oxc_diagnostics::OxcDiagnostic; use oxc_span::{Span, SPAN}; @@ -11,14 +46,6 @@ use crate::{context::Ctx, helpers::bindings::BoundIdentifier}; const SOURCE: &str = "__source"; const FILE_NAME_VAR: &str = "jsxFileName"; -/// [plugin-transform-react-jsx-source](https://babeljs.io/docs/babel-plugin-transform-react-jsx-source) -/// -/// This plugin is included in `preset-react` and only enabled in development mode. -/// -/// ## Example -/// -/// In: `` -/// Out: `` pub struct ReactJsxSource<'a> { filename_var: Option>, source_rope: Option,