feat(tre): enhanced typings and documentation

Author: jsamr

packages/transient-render-engine/src/index.ts

@@ -1,6 +1,7 @@
 export type { StylesConfig, MixedStyleRecord } from './styles/types';
 export * from './model/model-types';
 export { default as HTMLElementModel } from './model/HTMLElementModel';
+export type { HTMLElementModelShape } from './model/HTMLElementModel';
 export { default as HTMLContentModel } from './model/HTMLContentModel';
 export type { TStylesShape } from './styles/TStyles';
 export type {

packages/transient-render-engine/src/model/HTMLElementModel.ts

@@ -24,7 +24,7 @@ const translatableBlockCategories: ElementCategory[] = [
  * @typeParam T - The name of the tag to which the model will apply.
  * @typeParam M - The {@link HTMLContentModel} associated with this tag.
  */
-export interface HTMLElementModelProperties<
+export interface HTMLElementModelShape<
   T extends string,
   M extends HTMLContentModel
 > extends ElementModelBase<T> {
@@ -42,6 +42,11 @@ export interface HTMLElementModelProperties<
    *   have children.
    */
   readonly isVoid: boolean;
+  /**
+   * An opaque element translated {@link TNode} will have no translated {@link TNode}
+   * children.
+   */
+  readonly isOpaque: boolean;
 }
 
 /**
@@ -54,7 +59,7 @@ export interface HTMLElementModelProperties<
 export default class HTMLElementModel<
   T extends string,
   M extends HTMLContentModel
-> implements HTMLElementModelProperties<T, M>
+> implements HTMLElementModelShape<T, M>
 {
   /**
    * The tag name associated with this model.
@@ -144,7 +149,7 @@ export default class HTMLElementModel<
     setMarkersForTNode,
     getReactNativeProps,
     reactNativeProps
-  }: HTMLElementModelProperties<T, M>) {
+  }: HTMLElementModelShape<T, M>) {
     this.tagName = tagName;
     this.contentModel = contentModel;
     this.isOpaque = isOpaque || false;
@@ -248,24 +253,24 @@ export default class HTMLElementModel<
    */
   extend<CM extends HTMLContentModel>(
     merger: (
-      properties: HTMLElementModelProperties<T, CM>
-    ) => Partial<HTMLElementModelProperties<T, CM>>
+      shape: HTMLElementModelShape<T, CM>
+    ) => Partial<HTMLElementModelShape<T, CM>>
   ): HTMLElementModel<T, CM>;
   /**
    * Create a new {@link HTMLElementModel} by shallow-merging properties into this model.
    *
-   * @param properties - The {@link HTMLElementModelProperties} to shallow-merge into this model.
+   * @param shape - The {@link HTMLElementModelShape} to shallow-merge into this model.
    * @typeParam CM - The {@link HTMLContentModel} attached to the new model.
    */
   extend<CM extends HTMLContentModel>(
-    properties: Partial<HTMLElementModelProperties<T, CM>>
+    shape: Partial<HTMLElementModelShape<T, CM>>
   ): HTMLElementModel<T, CM>;
   extend<CM extends HTMLContentModel>(
     arg:
       | ((
-          fields: HTMLElementModel<T, M>
-        ) => Partial<HTMLElementModelProperties<T, CM>>)
-      | Partial<HTMLElementModelProperties<T, CM>>
+          shape: HTMLElementModelShape<T, M>
+        ) => Partial<HTMLElementModelShape<T, CM>>)
+      | Partial<HTMLElementModelShape<T, CM>>
   ): HTMLElementModel<T, CM> {
     const properties = typeof arg === 'function' ? arg(this) : arg;
     return new HTMLElementModel<T, CM>({

packages/transient-render-engine/src/model/model-types.ts

@@ -202,13 +202,34 @@ export interface ElementModelBase<T extends string> {
   readonly mixedUAStyles?: MixedStyleDeclaration;
 
   /**
-   * Default react Native props to pass to renderers.
+   * React Native props grouped by native components. Those props
+   * will be passed to the underlying native component at render time.
    *
    * @remarks Some props might be overriden by props derived from the
    * {@link TNode} attributes. For example, if you pass `accessibilityLabel`
    * and there is an `aria-label` attribute attached to one node, the
    * `aria-label` will be used. If you want to be able to override the
    * `aria-label`, use {@link getReactNativeProps} instead.
+   *
+   * @example
+   *
+   * ```ts
+   * import {HTMLElementModel, HTMLContentModel} from 'react-native-render-html';
+   *
+   * const customHTMLElementModels = {
+   *  'nav-button': HTMLElementModel.fromCustomModel({
+   *    tagName: 'nav-button',
+   *    contentModel: HTMLContentModel.block,
+   *    reactNativeProps: {
+   *      native: {
+   *        onPress() {
+   *          console.info('nav-button pressed');
+   *        },
+   *      },
+   *    },
+   *  }),
+   *};
+   * ```
    */
   readonly reactNativeProps?: ReactNativePropsDefinitions;
 
@@ -253,16 +274,48 @@ export interface ElementModelBase<T extends string> {
   ) => MixedStyleDeclaration | null | undefined | void;
 
   /**
-   * A function to create conditional React Native props for a specific TNode.
+   * A function to create React Native props from a {@link TNode} grouped by
+   * native components.
+   *
    * Those props will be deep-merged over the pre-generated props. You can
    * preserve some of the pre-generated props since you receive them as second
    * argument.
    *
-   * **Merge strategy** (rightmost overrides leftmost): _static props from model_,
-   * _auto-generated props from attributes_, _props returned by this function_.
+   * **Merge strategy** (latest overrides former):
+   *
+   * 1. props from `reactNativeProps`,
+   * 2. auto-generated props from attributes
+   * 3. props returned by this function
    *
-   * @param tnode - The TNode for which to create React Native props.
-   * @param preGeneratedProps - The props that were pre-generated for the TNode based on attributes (style, aria-* ...) and {@link HTMLELementModel.reactNativeProps}.
+   * @param tnode - The {@link TNode} for which to create React Native props.
+   * @param preGeneratedProps - The props that were pre-generated for the {@link TNode}
+   * based on attributes (e.g. aria-label ...) and
+   * {@link ElementModelBase.reactNativeProps}.
+   * @returns React Native props grouped by native components (see
+   * {@link ReactNativePropsDefinitions}). Those props will be passed to the
+   * underlying native component at render time.
+   *
+   * @example
+   *
+   * ```ts
+   * import { defaultHTMLElementModels } from "react-native-render-html";
+   *
+   * const customHTMLElementModels = {
+   *   a: defaultHTMLElementModels.a.extend({
+   *     getReactNativeProps(tnode) {
+   *       const attributes = tnode.attributes;
+   *       return {
+   *         native: {
+   *           accessibilityHint:
+   *             attributes['data-scope'] === 'internal'
+   *               ? 'Open in a new screen.'
+   *               : 'Open in system web browser.',
+   *         },
+   *       };
+   *     },
+   *   }),
+   * };
+   * ```
    */
   getReactNativeProps?: (
     tnode: ExtractTNodeFromType<TNodeType>,
@@ -288,7 +341,7 @@ export interface CustomElementModel<
   /**
    * The tag name associated with this model.
    */
-  readonly tagName: Exclude<T, TagName>;
+  readonly tagName: T;
 }
 
 /**