docs: enhance docs with new props for 6.2 release

jsamr · jsamr · commit a384da7d87e3 · 2021-10-20T13:07:41.000-03:00
diff --git a/apps/website/blog/2021-06-07-foundry-announcement.mdx b/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
diff --git a/apps/website/blog/2021-09-27-6-2-updates.mdx b/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.
diff --git a/doc-tools/doc-pages/src/pages/PageConceptTRE.tsx b/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>
diff --git a/doc-tools/doc-pages/src/pages/PageFAQ.tsx b/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>
   );
diff --git a/doc-tools/doc-pages/src/pages/PageGuideCustomRenderers.tsx b/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
