docs: enhance docs with new props for 6.2 release

apps/website/blog/2021-06-07-foundry-announcement.mdx

@@ -4,7 +4,7 @@ author: Jules Sam. Randolph
 author_title: Developer of React Native Render HTML v6
 author_url: https://github.com/jsamr/
 author_image_url: https://avatars.githubusercontent.com/u/3646758?v=4
-tags: [foundry, announcement]
+tags: [foundry, "release notes"]
 description: A major rewrite of the hackable, full-featured Open Source HTML rendering solution for React Native.
 image: img/foundry-announcement.png
 hide_table_of_contents: false

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

@@ -4,7 +4,7 @@ author: Jules Sam. Randolph
 author_title: Developer of React Native Render HTML v6
 author_url: https://github.com/jsamr/
 author_image_url: https://avatars.githubusercontent.com/u/3646758?v=4
-tags: [foundry, announcement]
+tags: [foundry, "release notes"]
 description: A version focused on accessibility and enhanced model rendering.
 image: img/foundry-announcement.png
 hide_table_of_contents: false
@@ -15,11 +15,12 @@ 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. This new release focuses on two areas of
+release has been made public. This new version focuses on two areas of
 improvements:
 
-1. Accessibility;
-2. Richer model-based rendering.
+1. Accessibility, and more specifically integration with screen readers;
+2. Richer model-based rendering, and the feature to define React Native props from
+within those models.
 
 As you will discover through this reading, both are somehow related. Let's find out how!
 
@@ -34,7 +35,7 @@ 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
 (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
+The below example is a reminder on 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"
@@ -70,10 +71,13 @@ 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 rendering more popular. Let's take a tour!
 
-### `getMixedUAStyles` Tickles CSS Selectors!
+### `getMixedUAStyles`
 
-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:
+This field deprecates <APIReference name="HTMLElementModel"
+member="getUADerivedStyleFromAttributes"/>; it serves the same purpose but its
+signature has changed. It now receives the target `tnode` and DOM `element`,
+which lets us implement more fine-grained logic such as CSS-selector-like
+behaviors:
 
 ```js title="Conditionnaly remove margins of 'ol' direct descendents of 'p' elements."
 import RenderHTML, {
@@ -114,9 +118,10 @@ 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 (for reference, the shape of
-this object is a <APIReference name="ReactNativePropsDefinitions" />):
+This field holds props that will be passed 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;
@@ -241,13 +246,6 @@ Nevertheless, those interactive element models are already shipped with the appr
 The new Transient Render Engine will from now on
 translate both attributes to their React Native counterparts.
 
-:::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`
@@ -333,18 +331,16 @@ any other value to `selectable={true}`.
 
 ## Bonus: Version 6.1 Features
 
-
-### `renderIndex` and `renderLength` Props to Custom Component Renderers
-
-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.
+I didn't publish a release notes post for this version; I'm catching up
+here! From now on, I will try to write up a post for each minor and major
+release.
 
 ### `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
+as at the end of a paragraph. Its default it yet `false` to avoid introducing
+breaking changes but it will be enabled by default in the next major
 release.
 
 :::tip learn more
@@ -353,28 +349,31 @@ Read the complete explanation for this prop [in the textual content guide](/docs
 
 ### `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).
+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). Its
+default it yet `false` to avoid introducing breaking changes but 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#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).
+A function prop which allows to generate HTTP headers for
+remote resources. It currently works with `<img>` and `<iframe>` tags (since version 2.6 of the
+[`@native-html/iframe-plugin`](https://github.com/native-html/plugins/tree/master/packages/iframe-plugin#readme) library).
 
 :::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:
+This prop, `true` by default, makes the React rendering layer bypass grouping
+(anonymous) `TPhrasing` nodes which have only one child. It is best understood by
+example. For instance, the following HTML snippet:
 
 ```html
 <p>A sentence.</p>
@@ -410,7 +409,7 @@ the render tree will be simplified to:
 ```
 
 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
+simplifies the render tree. The less React elements there are, the best it is
+performance-wise. Moreover, there are a lot of React Native bugs related to
 nested `Text` nodes, so this simplification limits the number of occurrences
 of those bugs.

doc-tools/doc-pages/src/pages/PageConceptTRE.tsx

@@ -76,7 +76,25 @@ export default function PageConceptTRE() {
  To each standard tag is attached an <Bold>element model</Bold>,
  instance of the <RefTRE name="HTMLElementModel" /> class. Such model
  has multiple fields describing different behaviors related to
- translation of those DOM elements:
+ translation of those DOM elements. There are two ways to instantiate
+ an element model:
+ </Paragraph>
+ <List>
+ <ListItem>
+ When changing an existing tag model with the{' '}
+ <RefTRE name="HTMLElementModel" member="extend" full /> method;
+ </ListItem>
+ <ListItem>
+ When registering a new tag with the{' '}
+ <RefTRE name="HTMLElementModel" member="fromCustomModel" full />{' '}
+ static method.
+ </ListItem>
+ </List>
+ <Paragraph>
+ You will have to register custom and extended models with the{' '}
+ <RefRenderHtmlProp name="customHTMLElementModels" /> prop. Below is
+ a list of fields that can be set when defining or extending HTML
+ element models:
  </Paragraph>
  <DList>
  <DListTitle>
@@ -111,15 +129,35 @@ export default function PageConceptTRE() {
  This is how default styles are set for tags.
  </DListItem>
  <DListTitle>
- <RefTRE
- name="HTMLElementModel"
- member="getUADerivedStyleFromAttributes"
- />
+ <RefTRE name="HTMLElementModel" member="getMixedUAStyles" />
+ </DListTitle>
+ <DListItem>
+ A function which returns mixed UA styles given a minimal{' '}
+ <RefTRE name="TNodeDescriptor" /> and a DOM <RefTRE name="Node" />
+ .
+ </DListItem>
+ <DListTitle>
+ <RefTRE name="HTMLElementModel" member="reactNativeProps" />
+ </DListTitle>
+ <DListItem>
+ An object with three fields, <InlineCode>text</InlineCode>,{' '}
+ <InlineCode>view</InlineCode> and <InlineCode>native</InlineCode>.
+ Each field value is a props object that will be passed to the
+ underlying native component at render time. Respecively, for
+ <RefRNSymbol name="Text" />, <RefRNSymbol name="View" /> and all
+ (catch-all).
+ </DListItem>
+ <DListTitle>
+ <RefTRE name="HTMLElementModel" member="getReactNativeProps" />
  </DListTitle>
  <DListItem>
- A function which returns mixed UA styles given the DOM node{' '}
- <Bold>attributes</Bold> and <RefTRE name="TNode" />{' '}
- <RefTRE name="Markers" />.
+ Serves the same purpose as{' '}
+ <InlineCode>reactNativeProps</InlineCode>, but it's a function
+ taking a <RefTRE name="TNode" /> as first argument, pre-generated
+ props as second argument (such as{' '}
+ <InlineCode>accessibilityLabel</InlineCode> derived from{' '}
+ <RefHtmlAttr name="aria-label" />) and the DOM{' '}
+ <RefTRE name="Element" /> as a third argument.
  </DListItem>
  </DList>
  </Section>

doc-tools/doc-pages/src/pages/PageFAQ.tsx

@@ -218,6 +218,34 @@ export default function PageFAQ() {
  image.
  </Paragraph>
  </Section>
+ <Section title="Some anchors (<a>) are not accessible to screen readers">
+ <Paragraph>
+ Because of a{' '}
+ <Hyperlink url="https://github.com/facebook/react-native/issues/32004">
+ React Native bug
+ </Hyperlink>
+ , nested `Text` elements are not accessible, which means that the
+ screen reader will not be able to identify{' '}
+ <RefHtmlElement name="a" /> tags as links when grouped with other
+ textual elements. Below is an example:
+ </Paragraph>
+ <SourceDisplay
+ lang="html"
+ showLineNumbers={false}
+ content={`<p>
+ Unfortunately,
+ <a href="https://domain.com">this hyperlink is not accessible</a>
+ </p>`}
+ />
+ <Paragraph>
+ Luke Walczak from Callstack{' '}
+ <Hyperlink url="https://callstack.com/blog/react-native-android-accessibility-tips/">
+ explains how to circumvent this issue in a great post
+ </Hyperlink>
+ . Unfortunately, this workaround cannot be genericized and we will
+ have to wait for a fix in React Native codebase.
+ </Paragraph>
+ </Section>
  </Chapter>
  </Page>
  );

doc-tools/doc-pages/src/pages/PageGuideCustomRenderers.tsx

@@ -299,10 +299,6 @@ export default function PageGuideCustomRenderers() {
  </DListTitle>
  <DListItem>
  The position relative to the parent React element, starting at 0.
- Not to be confused with{' '}
- <RefRenderHTMLExport name="TNodeShape" member="index" full /> the
- position of the <RefRenderHTMLExport name="TNode" /> before
- hoisting, which is much closer to the position in the DOM.
  </DListItem>
  <DListTitle>
  <RefRenderHTMLExport