diff --git a/README.md b/README.md index 510084aa4..5ed2ead3e 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ * __[Using it in your project](#using-it-in-your-project)__ - * [Running tests in your project](#running-tests-in-your-project) + * [Running tests in your project](#running-tests-in-your-project) * __[Anatomy of an OverReact component](#anatomy-of-an-overreact-component)__ * [UiFactory](#uifactory) * [UiProps](#uiprops) @@ -32,31 +32,31 @@ ## Using it in your project > __If you are not familiar with React JS__ -> -> Since OverReact is built atop React JS, we strongly encourage you to gain -> familiarity with it by reading this [React JS tutorial][react-js-tutorial] first. +> +> Since OverReact is built atop React JS, we strongly encourage you to gain +> familiarity with it by reading this [React JS tutorial][react-js-tutorial] first. 1. Add the `over_react` package as a dependency in your `pubspec.yaml`. - + ```yaml dependencies: over_react: "^1.3.0" ``` - + 2. Add the `over_react` [transformer] to your `pubspec.yaml`. - + ```yaml transformers: - over_react # Reminder: dart2js should come after any other transformers that touch Dart code - $dart2js ``` - - _Our transformer uses code generation to wire up the different pieces of your + + _Our transformer uses code generation to wire up the different pieces of your component declarations - and to create typed getters/setters for `props` and `state`._ -3. Include the native JavaScript `react` and `react_dom` libraries in your app’s `index.html` file, -and add an HTML element with a unique identifier where you’ll mount your OverReact UI component(s). +3. Include the native JavaScript `react` and `react_dom` libraries in your app’s `index.html` file, +and add an HTML element with a unique identifier where you’ll mount your OverReact UI component(s). ```html @@ -67,7 +67,7 @@ and add an HTML element with a unique identifier where you’ll mount your OverR
// OverReact component render() output will show up here.
- + @@ -75,14 +75,14 @@ and add an HTML element with a unique identifier where you’ll mount your OverR ``` - - > __Note:__ When serving your application in production, use `packages/react/react_with_react_dom_prod.js` + + > __Note:__ When serving your application in production, use `packages/react/react_with_react_dom_prod.js` file instead of the un-minified `react.js` / `react_dom.js` files shown in the example above. - -4. Import the `over_react` library _(and associated react libraries)_ into `your_app_name.dart`, and initialize -React within your Dart application. Then [build a custom component](#building-custom-components) and + +4. Import the `over_react` library _(and associated react libraries)_ into `your_app_name.dart`, and initialize +React within your Dart application. Then [build a custom component](#building-custom-components) and mount / render it into the HTML element you created in step 3. - + ```dart import 'dart:html'; import 'package:react/react.dart' as react; @@ -93,8 +93,8 @@ mount / render it into the HTML element you created in step 3. main() { // Initialize React within our Dart app react_client.setClientConfiguration(); - - // Mount / render your component. + + // Mount / render your component. react_dom.render(Foo()(), querySelector('#react_mount_point')); } ``` @@ -105,7 +105,7 @@ mount / render it into the HTML element you created in step 3. ### Running tests in your project -When running tests on code that uses our [transformer] _(or any code that imports `over_react`)_, +When running tests on code that uses our [transformer] _(or any code that imports `over_react`)_, __you must run your tests using Pub__. 1. Add the `test/pub_serve` transformer to your `pubspec.yaml` _after_ the `over_react` transformer. @@ -121,9 +121,9 @@ __you must run your tests using Pub__. 2. Use [the `--pub-serve` option](https://github.com/dart-lang/test#testing-with-barback) when running your tests: ```bash - $ pub run test --pub-serve=8081 test/your_test_file.dart + $ pub run test --pub-serve=8081 test/your_test_file.dart ``` - + > __Note:__ `8081` is the default port used, but your project may use something different. Be sure to take note of the output when running `pub serve` to ensure you are using the correct port. @@ -135,14 +135,14 @@ __you must run your tests using Pub__. ## Anatomy of an OverReact component > __If you are not familiar with React JS__ -> -> Since OverReact is built atop React JS, we strongly encourage you to gain +> +> Since OverReact is built atop React JS, we strongly encourage you to gain > familiarity with it by reading this [React JS tutorial][react-js-tutorial] first. -The `over_react` library functions as an additional "layer" atop the [Dart react package][react-dart] +The `over_react` library functions as an additional "layer" atop the [Dart react package][react-dart] which handles the underlying JS interop that wraps around [React JS][react-js]. -The library strives to maintain a 1:1 relationship with the React JS component class and API. +The library strives to maintain a 1:1 relationship with the React JS component class and API. To do that, an OverReact component is comprised of four core pieces that are each wired up to our Pub transformer using an analogous [annotation]. @@ -155,7 +155,7 @@ Pub transformer using an analogous [annotation]. ### UiFactory -__`UiFactory` is a function__ that returns a new instance of a +__`UiFactory` is a function__ that returns a new instance of a [`UiComponent`](#uicomponent)’s [`UiProps`](#uiprops) class. ```dart @@ -164,14 +164,14 @@ UiFactory Foo; ``` * This factory is __the entry-point__ to consuming every OverReact component. -* The `UiProps` instance it returns can be used [as a component builder](#uiprops-as-a-builder), +* The `UiProps` instance it returns can be used [as a component builder](#uiprops-as-a-builder), or [as a typed view into an existing props map](#uiprops-as-a-map).   ### UiProps -__`UiProps` is a Map class__ that adds statically-typed getters and setters for each React component prop. +__`UiProps` is a Map class__ that adds statically-typed getters and setters for each React component prop. It can also be invoked as a function, serving as a builder for its analogous component. ```dart @@ -179,7 +179,7 @@ It can also be invoked as a function, serving as a builder for its analogous com class FooProps extends UiProps { // ... } -``` +```   @@ -208,13 +208,13 @@ void bar() { print(props); // {FooProps.color: #66cc00} } -/// You can use the factory to create a UiProps instance +/// You can use the factory to create a UiProps instance /// backed by an existing Map. void baz() { Map existingMap = {'FooProps.color': '#0094ff'}; - + FooProps props = Foo(existingMap); - + print(props.color); // #0094ff } ``` @@ -241,7 +241,7 @@ class FooComponent extends UiComponent { // Add props builder.id = 'the_best_foo'; builder.color = '#ee2724'; - + // Invoke as a function with the desired children // to return a new instance of the component. return builder('child1', 'child2'); @@ -253,7 +253,7 @@ class FooComponent extends UiComponent { ..id = 'the_best_foo' ..color = 'red' )( - 'child1', + 'child1', 'child2' ); } @@ -266,7 +266,7 @@ class FooComponent extends UiComponent { ### UiState -__`UiState` is a Map class__ _(just like `UiProps`)_ that adds statically-typed getters and setters +__`UiState` is a Map class__ _(just like `UiProps`)_ that adds statically-typed getters and setters for each React component state property. ```dart @@ -282,7 +282,7 @@ class FooState extends UiState { ### UiComponent -__`UiComponent` is a subclass of [`react.Component`][react.component]__, containing lifecycle methods +__`UiComponent` is a subclass of [`react.Component`][react.component]__, containing lifecycle methods and rendering logic for components. ```dart @@ -292,18 +292,18 @@ class FooComponent extends UiComponent { } ``` -* This component provides statically-typed props via [`UiProps`](#uiprops), as well as utilities for +* This component provides statically-typed props via [`UiProps`](#uiprops), as well as utilities for prop forwarding and CSS class merging. -* The `UiStatefulComponent` flavor augments `UiComponent` behavior with statically-typed state via +* The `UiStatefulComponent` flavor augments `UiComponent` behavior with statically-typed state via [`UiState`](#uistate).   #### Accessing and manipulating props / state within UiComponent -* Within the `UiComponent` class, `props` and `state` are not just `Map`s. +* Within the `UiComponent` class, `props` and `state` are not just `Map`s. They are instances of `UiProps` and `UiState`, __which means you don’t need String keys to access them!__ -* `newProps()` and `newState()` are also exposed to conveniently create empty instances of `UiProps` and +* `newProps()` and `newState()` are also exposed to conveniently create empty instances of `UiProps` and `UiState` as needed. * `typedPropsFactory()` and `typedStateFactory()` are also exposed to conveniently create typed `props` / `state` objects out of any provided backing map. @@ -314,7 +314,7 @@ class FooComponent extends UiStatefulComponent { getDefaultProps() => (newProps() ..color = '#66cc00' ); - + @override getInitialState() => (newState() ..isActive = false @@ -326,10 +326,10 @@ class FooComponent extends UiStatefulComponent { var tNewProps = typedPropsFactory(newProps); var becameActive = !state.isActive && tNewState.isActive; - + // Do something here! } - + @override render() { return (Dom.div() @@ -342,11 +342,11 @@ class FooComponent extends UiStatefulComponent { props.children ); } - + void _handleButtonClick(SyntheticMouseEvent event) { _toggleActive(); } - + void _toggleActive() { setState(newState() ..isActive = !state.isActive @@ -362,14 +362,14 @@ class FooComponent extends UiStatefulComponent { ## Fluent-style component consumption -In OverReact, components are consumed by invoking a `UiFactory` to return a new `UiProps` builder, which is then +In OverReact, components are consumed by invoking a `UiFactory` to return a new `UiProps` builder, which is then modified and invoked to build a `ReactElement`. -This is done to make ["fluent-style"](#fluent-style-component-consumption) component consumption possible, so that -the OverReact consumer experience is very similar to the [React JS][react-js] / "vanilla" [react-dart] +This is done to make ["fluent-style"](#fluent-style-component-consumption) component consumption possible, so that +the OverReact consumer experience is very similar to the [React JS][react-js] / "vanilla" [react-dart] experience. -To demonstrate the similarities, the example below shows a render method for JS, JSX, react-dart, +To demonstrate the similarities, the example below shows a render method for JS, JSX, react-dart, and over_react that will have the exact same HTML markup result. * __React JS__: @@ -385,7 +385,7 @@ and over_react that will have the exact same HTML markup result. ); } ``` - + * __React JS__ (JSX): ```jsx @@ -404,7 +404,7 @@ and over_react that will have the exact same HTML markup result. ```dart render() { - return react.div({'className': 'container'}, + return react.div({'className': 'container'}, react.h1({}, 'Click the button!'), react.button({ 'id': 'main_button', @@ -429,18 +429,18 @@ and over_react that will have the exact same HTML markup result. ``` Let’s break down the OverReact fluent-style shown above - + ```dart render() { // Create a builder for a
, // add a CSS class name by cascading a typed setter, // and invoke the builder with the HTML DOM

and