docs(blog): update draft 6.2 release notes blog post

Author: jsamr

apps/website/blog/2021-09-27-6-2-updates.mdx

@@ -1,5 +1,5 @@
 ---
-title: Announcing the 6.2 Release, Featuring Enhanced Model Rendering and Accessibility!
+title: What's New in v6.2?
 author: Jules Sam. Randolph
 author_title: Developer of React Native Render HTML v6
 author_url: https://github.com/jsamr/
@@ -12,22 +12,36 @@ draft: true
 ---
 
 import APIReference from '@site/src/components/APIReference';
+import Reference from '@site/src/components/Reference';
 
 It has been over two months since the first final version of the Foundry
-released has been made public.
+released has been made public. This new release focuses on two areas of
+improvements:
+
+1. Accessibility;
+2. Richer model-based rendering.
+
+As you will discover through this reading, both are somehow related. Let's find out how!
+
+<!--truncate-->
 
 ## You Might not Need a Custom Component Renderer
 
-Model-based custom rendering via <APIReference name="RenderHTMLProps"
+Model-based rendering via <APIReference name="RenderHTMLProps"
 member="customHTMLElementModels"/> prop has been a lightweight alternative to
 custom (component) renderers since the early stages of the Foundry release.
 However, it was limited to setting user agent styles (<APIReference
 name="HTMLElementModel" member="mixedUAStyles" />),
 although those styles could be derived from the DOM node element attributes
-(<APIReference name="HTMLElementModel" member="getUADerivedStyleFromAttributes" />).
+(the now-deprecated <APIReference name="HTMLElementModel" member="getUADerivedStyleFromAttributes" />).
+The below example is a reminder of how those element models can be defined, for instance to
+register a new `<blue-circle>` tag which renders to a 50 by 50 blue circle!
 
 ```js title="An Example of Model-Based Rendering"
-import RenderHTML, { HTMLElementModel } from 'react-native-render-html';
+import RenderHTML, {
+  HTMLElementModel,
+  HTMLContentModel
+} from 'react-native-render-html';
 
 // The eponym prop to pass to RenderHTML
 const customHTMLElementModels = {
@@ -49,12 +63,14 @@ const customHTMLElementModels = {
 Keep in mind that <APIReference name="HTMLElementModel" member="mixedUAStyles"
 /> has a lower specificity than styles passed to `RenderHTML` such as
 &ZeroWidthSpace;<APIReference name="RenderHTMLProps" member="tagsStyles" />.
+See the [CSS Processing guide](/docs/flow/css-processing#specificity) section
+related to specificity for a refresher.
 :::
 
 Version 6.2 ships with a bunch of new fields for HTML element models which
-should make model-based custom rendering more popular. Let's take a tour!
+should make model-based rendering more popular. Let's take a tour!
 
-### `getMixedUAStyles` almost features CSS selectors!
+### `getMixedUAStyles` Tickles CSS Selectors!
 
 This field deprecates <APIReference name="HTMLElementModel" member="getUADerivedStyleFromAttributes"/>; it's basically the same
 but its signature has changed: it receives the target `tnode` and DOM `element`, which lets us implement CSS-selector-like behaviors:
@@ -81,6 +97,11 @@ const customHTMLElementModels = {
 };
 ```
 
+However and as stated before, those styles will have a lower specificity than tags, classes and
+ID styles and as such, these are not "real" CSS selectors. Hopefully, CSS selectors will be
+implemented at some point, [you can upvote the feature request here](https://native-html.canny.io/features/p/support-complex-css-like-selectors-eg-div-button)!
+The hard challenge is that these should not impede performances. I am planning to explore this issue next year.
+
 :::warning
 Beware that this `tnode` is an instance of <APIReference name="TNodeDescriptor"
 />, which is a minimal `tnode` shape available during the Transient Render
@@ -93,15 +114,15 @@ to query the DOM and create your conditional styling rules.
 
 ### `reactNativeProps`
 
-This field will set props to the native component during the rendering phase. It is an object with three optional properties:
+This field will set props to the native component during the rendering phase.
+It is an object with three optional properties (for reference, the shape of
+this object is a <APIReference name="ReactNativePropsDefinitions" />):
 
 1. `text`, to pass native props to the `Text` component when the renderer is textual;
 2. `view`, to pass native props to the `View` component when the renderer is block;
 3. `native`, to pass props to either `View` or `Text` components, irrespective of the renderer type.
 
-The type definition for this object is <APIReference name="ReactNativePropsDefinitions" />.
-
-In the below example, we are defining a custom tag, `nav-widget`, and setting
+In the next snippet, we are defining a custom tag, `<nav-widget>`, and setting
 accessibility props to any underlying native component for the render phase. We
 can also define `onPress`, which will cause the renderer to use the
 &ZeroWidthSpace;<APIReference name="RenderHTMLProps" member="GenericPressable" /> instead of
@@ -143,21 +164,23 @@ name="ReactNativePropsDefinitions" />).
 
 In the example below, a custom `nav-widget` tag is registered. This time, we
 are handling `onPress` events conditionally, based on attributes of the
-`tnode`. The snippets uses a phony API, `appNavigatorControler`, to navigate
+`tnode`. The snippets uses a phony API, `appNavigatorController`, to navigate
 between screens. Such API is easy to implement with a globally-defined ref to a
-`react-navigation` "navigation" object.
+[`react-navigation`](https://reactnavigation.org) "navigation" object.
 
 :::important
-It is worth noting that you cannot use React hooks in any of element models functions. But you can use
-any ad-hoc API to emit events. If you really need React hooks, add a custom component renderer.
+It is worth noting that you cannot use React hooks in those element models
+functions. But you can use any ad-hoc API to emit events, and glue that logic
+to hooks. If you really need React hooks, it might be simple to [create a custom
+component renderer](/docs/guides/custom-renderers#component-based-custom-rendering).
 :::
 
 ```js title="Defining React Native props based on the TNode in an HTML element model"
 import RenderHTML, {
   HTMLContentModel,
   HTMLElementModel
 } from 'react-native-render-html';
-import appNavigatorControler from './appNavigatorControler';
+import appNavigatorController from './appNavigatorController';
 
 // The eponym prop to pass to RenderHTML
 const customHTMLElementModels = {
@@ -171,7 +194,7 @@ const customHTMLElementModels = {
           onPress() {
             const targetScreen = tnode.attributes['data-target'];
             const targetParams = tnode.attributes['data-params'];
-            appNavigatorControler.navigate(
+            appNavigatorController.navigate(
               targetScreen,
               targetParams ? JSON.parse(targetParams) : null
             );
@@ -189,18 +212,46 @@ Don't forget that you can mix model-based and component-based rendering!
 
 ## A Focus on Accessibility
 
-### Support for `aria-label` and `aria-role` Attributes
+Screen readers integration has been worked on sparsely since the Foundry
+release, by addressing issues raised by the community, but until v6.2 there has
+not been structural improvements to cover the full range of required features.
+Thanks to the new Transient Render Engine, it has become very easy to define
+translations from HTML attributes to React Native props within the engine.
+Let's find out what's new!
+
+### Support for `aria-label` and `role` Attributes
+
+On one hand, <Reference type="html-attr" url="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-label_attribute" name="aria-label" />
+is used to hint screen readers on how a specific node **and all its descendants** should be read out loud. It is especially
+useful to handle icons which don't have inner semantic meanings. This attribute has a React Native prop equivalent, namely
+[`accessibilityLabel`](https://reactnative.dev/docs/accessibility#accessibilitylabel), which serves the same purpose.
+On the other hand, <Reference type="html-attr" url="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles" name="role" />
+informs the screen reader of the target element nature and how a user might interact with it.
+This attributes roughly maps to React Native [`accessibilityRole`](https://reactnative.dev/docs/accessibility#accessibilityrole)
+prop, although the set of allowed values slightly differs.
+See [all supported roles and their mapping
+here](https://github.com/native-html/core/blob/00c0cd1034c4cb721e991d5c02b232c4d64eae3d/packages/transient-render-engine/src/tree/TNodeCtor.ts#L33).
+
+:::warning
+Remember that a majority of interactive elements will not be rendered by this library. You must change their
+content model to <APIReference name="HTMLContentModel" member="block" /> in order for them to be rendered.
+Nevertheless, those interactive element models are already shipped with the appropriate `accessibilityRole` prop.
+:::
+
+The new Transient Render Engine will from now on
+translate both attributes to their React Native counterparts.
 
-`aria-label` and `aria-role` HTML attributes roughly map to
-`accessibilityLabel` and `accessibilityRole` React Native props. The new
-Transient Render Engine which features React Native props generation will from now on
-translate both attributes to their React Native counterparts. The mapping rules
-for `aria-role` have been extracted from `react-native-web`.
+:::info Midly relevant
+The mapping rules from the `role` HTML attribute to React Native props has
+been greatly influenced by those of
+[`react-native-web`](https://github.com/necolas/react-native-web/blob/66d01734ce3ffcfea61e05aa1b45015658b3f2af/packages/react-native-web/src/modules/AccessibilityUtil/propsToAriaRole.js),
+the other way round!
+:::
 
 ### Accessible `<a>` Tags
 
 `<a>` tags now receive an `accessibilityRole="link"` prop when their `href`
-attribute is non-empty. Let's see now how we could set a custom generic hint by
+attribute is non-empty. Let's see now how we could set [an accessibility hint](https://reactnative.dev/docs/accessibility#accessibilityhint) by
 extending the HTML model:
 
 ```ts
@@ -217,9 +268,13 @@ const customHTMLElementModels = {
 };
 ```
 
+Notice that <APIReference full name="HTMLElementModel" member="extend" />
+method can now take a generator function. Pretty convenient to merge
+nested fields!
+
 :::warning
 Because of a [React Native
-limitation](https://github.com/facebook/react-native/issues/32004), nested
+bug](https://github.com/facebook/react-native/issues/32004), nested
 `Text` elements are not accessible, which means that the screen reader will not
 be able to identify `<a>` tags as links when grouped with other textual
 elements. Below is an example:
@@ -233,9 +288,8 @@ elements. Below is an example:
 
 Luke Walczak from Callstack [explains how to circumvent this issue in a great
 post](https://callstack.com/blog/react-native-android-accessibility-tips/).
-Unfortunately, this workaround is not generalizable and we will have to wait
+Unfortunately, this workaround cannot be genericized and we will have to wait
 for an upstream fix.
-
 :::
 
 ### Enhanced Accessibility for `<img>` Tags
@@ -254,7 +308,7 @@ image container, to make it independent of the internal state.
 ### Accessible `<h1-6>` Tags
 
 React Native has a “header” accessibility role which screen reader users depend
-on a lot to identify efficiently the content hierarchy of a screen. Until this
+on widely to identify quickly the content hierarchy of a screen. Until this
 release, `react-native-render-html` did not pass this role to heading tags.
 
 ## Other Enhancements
@@ -277,20 +331,85 @@ Please not that this is not full support. The TRE will map `user-select: none;`
 any other value to `selectable={true}`.
 :::
 
-### `getNativePropsForTnode` Function
+## Bonus: Version 6.1 Features
 
-## Bonus: Notes on Version 6.1
+### `renderIndex` and `renderLength` Props to Custom Component Renderers
 
-### `renderIndex` and `renderLength` Props to `TDefaultRenderer`
+Those props passed to custom component renderers give you positional
+information regarding this element in the render tree. `renderIndex` will often
+coincide with `tnode.index` but there are subtle differences.
 
 ### `enableExperimentalBRCollapsing` Prop
 
+This **recommended prop** allows consumers to circumvent a bug in the Foundry
+release where line breaks (`<br>`) would be printed erroneously, such
+as at the end of a paragraph. It will be enabled by default in the next major
+release.
+
+:::tip learn more
+Read the complete explanation for this prop [in the textual content guide](/docs/content/textual#line-breaks).
+:::
+
 ### `enableExperimentalGhostLinesPrevention` Prop
 
+This **recommended prop** allows to circumvent [a React Native bug](https://github.com/facebook/react-native/issues/32062) where empty
+`Text` elements would be printed as ghost lines of fixed height (around 20 dpi).
+
+:::tip learn more
+Read the complete explanation for this prop [in the textual content guide](/docs/content/textual#empty-tags).
+:::
+
 ### `provideEmbeddedHeaders` Prop
 
 This is a function prop which allows consumer to generate HTTP headers for
 remote resources. It currently works with `<img>` and `<iframe>` tags (from the
 `@native-html/iframe-plugin` lib).
 
+:::tip learn more
+See for example how it can be used with images [in the image content guide](/docs/content/images#providing-headers).
+:::
+
 ### `bypassAnonymousTPhrasingNodes` Prop
+
+This prop makes the React rendering layer omit grouping (anonymous) `TPhrasing`
+nodes which have only one child. It is best learn by example. For instance, the
+following HTML snippet:
+
+```html
+<p>A sentence.</p>
+```
+
+will produce the below Transient Render Tree:
+
+```xml
+<TBlock tagName="p">
+  <TPhrasing>
+    <TText>A sentence.</TText>
+  </TPhrasing>
+</TBlock>
+```
+
+which by default rendering rules, would be translated to the below React render tree:
+
+```xml
+<View>
+  <Text>
+    <Text>A sentence.</Text>
+  </Text>
+</View>
+```
+
+However, when `bypassAnonymousTPhrasingNodes` prop is `true` (the default),
+the render tree will be simplified to:
+
+```xml
+<View>
+  <Text>A sentence.</Text>
+</View>
+```
+
+This behavior is preferred for many reasons. The most simple one is that it
+simplifies the render tree. The less React element there is, the best it is
+performance-wise. Moreover, there are a lot of React Native bugs implying
+nested `Text` nodes, so this simplification limits the number of occurrences
+of those bugs.