refactor: enhance typings for provideEmbeddedHeaders + add 3d param

jsamr · jsamr · commit 3e744f49fba9 · 2021-08-29T17:30:29.000-03:00
diff --git a/doc-tools/doc-pages/src/pages/PageContentImages.tsx b/doc-tools/doc-pages/src/pages/PageContentImages.tsx
@@ -4,6 +4,7 @@ import Page from '../Page';
 import useToolkit from '../toolkit/useToolkit';
 import customImageRendererConfig from './cards/customImageRendererConfig';
 import internalImageRendererConfig from './cards/internalImageRendererConfig';
+import imagesWithHeadersConfig from './cards/imagesWithHeadersConfig';
 import InternalRendererAdmonition from '../components/InternalRendererAdmonition';
 
 const inlineExample = `<img
@@ -248,13 +249,32 @@ export default function PageContentImages() {
         </Section>
       </Chapter>
       <Chapter title="Configuring">
-        <Paragraph>
-          We can take advantage of the{' '}
-          <RefRenderHtmlProp name="renderersProps" /> to customize images
-          behavior (see{' '}
-          <RefRenderHTMLExport name="RenderersProps" member="img" full />
-          ).
-        </Paragraph>
+        <Section title="Providing headers">
+          <Paragraph>
+            You can take advantage of the{' '}
+            <RefRenderHtmlProp name="provideEmbeddedHeaders" />
+            prop to pass headers to the image fetching conditionnaly. For
+            example:
+          </Paragraph>
+          <RenderHtmlCard {...imagesWithHeadersConfig} />
+          <Admonition type="tip">
+            In this example, we are using a Bearer token to access a restricted
+            resource. We could also use headers to take advantage of the new{' '}
+            <Hyperlink url="https://wicg.github.io/responsive-image-client-hints/">
+              Responsive Image Client Hints
+            </Hyperlink>{' '}
+            standard.
+          </Admonition>
+        </Section>
+        <Section title="Advanced configuration">
+          <Paragraph>
+            We can take advantage of the{' '}
+            <RefRenderHtmlProp name="renderersProps" /> to customize images
+            behavior (see{' '}
+            <RefRenderHTMLExport name="RenderersProps" member="img" full />
+            ).
+          </Paragraph>
+        </Section>
       </Chapter>
     </Page>
   );
diff --git a/doc-tools/doc-pages/src/pages/cards/imagesWithHeadersConfig.tsx b/doc-tools/doc-pages/src/pages/cards/imagesWithHeadersConfig.tsx
@@ -0,0 +1,40 @@
+import { UIRenderHtmlCardProps } from '../../toolkit/toolkit-types';
+
+const html = `<img src="https://www.fillmurray.com/200/100" />`;
+
+function provideEmbeddedHeaders(uri: string, tagName: string) {
+  if (tagName === 'img') {
+    return {
+      Authorization: 'Bearer XYZ'
+    };
+  }
+}
+
+const imagesWithHeadersConfig: UIRenderHtmlCardProps = {
+  title: 'Providing headers to images',
+  caption:
+    'provideEmbeddedHeaders lets you pick headers for specific domains and works with multiple tags. For example, it can be used with the iframe plugin.',
+  props: {
+    source: {
+      html
+    },
+    provideEmbeddedHeaders
+  },
+  preferHtmlSrc: false,
+  config: {
+    importStatements: [
+      { package: 'react-native', named: ['Platform', 'PixelRatio'] }
+    ],
+    fnSrcMap: {
+      provideEmbeddedHeaders: `function provideEmbeddedHeaders(uri, tagName) {
+  if (tagName === 'img') {
+    return {
+      Authorization: "Bearer XYZ",
+    };
+  }
+}`
+    }
+  }
+};
+
+export default imagesWithHeadersConfig;
diff --git a/packages/render-html/src/context/SharedPropsProvider.tsx b/packages/render-html/src/context/SharedPropsProvider.tsx
@@ -4,18 +4,15 @@ import selectSharedProps from '../helpers/selectSharedProps';
 import { RenderHTMLSharedProps, RendererBaseProps } from '../shared-types';
 import defaultSharedProps from './defaultSharedProps';
 
-const SharedPropsContext =
-  React.createContext<Required<RenderHTMLSharedProps>>(defaultSharedProps);
+const SharedPropsContext = React.createContext(defaultSharedProps);
 
 /**
  * Use shared props. See {@link RenderHTMLSharedProps}.
  *
  * @public
  */
 export function useSharedProps() {
-  return React.useContext(
-    SharedPropsContext
-  ) as Required<RenderHTMLSharedProps>;
+  return React.useContext(SharedPropsContext);
 }
 
 /**
diff --git a/packages/render-html/src/context/defaultSharedProps.ts b/packages/render-html/src/context/defaultSharedProps.ts
@@ -1,5 +1,5 @@
 import { DEFAULT_PRESSABLE_RIPPLE_COLOR } from '../constants';
-import { RenderHTMLSharedProps } from '../shared-types';
+import { RenderHTMLAmbiantSharedProps } from '../shared-types';
 
 function WebViewPlaceholder() {
   /* istanbul ignore else */
@@ -12,7 +12,7 @@ function WebViewPlaceholder() {
   return null;
 }
 
-const defaultSharedProps: Required<RenderHTMLSharedProps> = {
+const defaultSharedProps: RenderHTMLAmbiantSharedProps = {
   bypassAnonymousTPhrasingNodes: true,
   debug: false,
   defaultTextProps: {
@@ -24,12 +24,12 @@ const defaultSharedProps: Required<RenderHTMLSharedProps> = {
   enableExperimentalGhostLinesPrevention: false,
   enableExperimentalMarginCollapsing: false,
   computeEmbeddedMaxWidth: (contentWidth) => contentWidth,
-  provideEmbeddedHeaders: () => null,
-  GenericPressable: undefined as any,
   WebView: WebViewPlaceholder,
   defaultWebViewProps: {},
   pressableHightlightColor: DEFAULT_PRESSABLE_RIPPLE_COLOR,
-  customListStyleSpecs: undefined as any
+  provideEmbeddedHeaders: undefined,
+  GenericPressable: undefined,
+  customListStyleSpecs: undefined
 };
 
 export default defaultSharedProps;
diff --git a/packages/render-html/src/elements/__tests__/useIMGElementStateWithCache.test.ts b/packages/render-html/src/elements/__tests__/useIMGElementStateWithCache.test.ts
@@ -5,7 +5,8 @@ const props = {
   contentWidth: 300,
   source: { uri: 'https://foo.bar/600x300' },
   initialDimensions: { width: 30, height: 30 },
-  computeMaxWidth: (contentWidth: number) => contentWidth
+  computeMaxWidth: (contentWidth: number) => contentWidth,
+  tnode: {} as any
 };
 
 describe('useIMGElementStateWithCache', () => {
diff --git a/packages/render-html/src/elements/useIMGElementState.ts b/packages/render-html/src/elements/useIMGElementState.ts
@@ -1,12 +1,12 @@
-import { useEffect, useMemo } from 'react';
+import { useEffect } from 'react';
 import { Image } from 'react-native';
 import type { UseIMGElementStateProps, IMGElementState } from './img-types';
 import useImageNaturalDimensions from './useImageNaturalDimensions';
 import useImageConcreteDimensions from './useImageConcreteDimensions';
 import defaultImageInitialDimensions from './defaultInitialImageDimensions';
 import { ImageDimensions } from '../shared-types';
 import { getIMGState } from './getIMGState';
-import { useSharedProps } from '../context/SharedPropsProvider';
+import useIMGNormalizedSource from './useIMGNormalizedSource';
 
 function getImageSizeAsync({
   uri,
@@ -89,26 +89,17 @@ export default function useIMGElementState(
   } = props;
   const { naturalDimensions, specifiedDimensions, flatStyle, onError, error } =
     useFetchedNaturalDimensions(props);
-  const { provideEmbeddedHeaders } = useSharedProps();
-  const nomalizedSource = useMemo(() => {
-    if (source.uri) {
-      const headers = provideEmbeddedHeaders(source.uri, 'img');
-      if (headers) {
-        return {
-          headers,
-          ...source
-        };
-      }
-    }
-    return source;
-  }, [provideEmbeddedHeaders, source]);
   const concreteDimensions = useImageConcreteDimensions({
     flatStyle,
     naturalDimensions,
     specifiedDimensions,
     computeMaxWidth,
     contentWidth
   });
+  const nomalizedSource = useIMGNormalizedSource({
+    concreteDimensions,
+    source
+  });
   return getIMGState({
     error,
     alt,
diff --git a/packages/render-html/src/elements/useIMGElementStateWithCache.ts b/packages/render-html/src/elements/useIMGElementStateWithCache.ts
@@ -7,6 +7,7 @@ import type {
 } from './img-types';
 import useImageConcreteDimensions from './useImageConcreteDimensions';
 import useImageNaturalDimensions from './useImageNaturalDimensions';
+import useIMGNormalizedSource from './useIMGNormalizedSource';
 
 /**
  * This hook is useful when one has access to image natural dimensions prior to
@@ -34,14 +35,18 @@ export default function useIMGElementStateWithCache(
     computeMaxWidth,
     contentWidth
   });
+  const nomalizedSource = useIMGNormalizedSource({
+    concreteDimensions,
+    source
+  });
   return getIMGState({
     error,
     concreteDimensions,
     containerStyle: flatStyle,
     initialDimensions,
     objectFit,
     onError,
-    source,
+    source: nomalizedSource,
     alt,
     altColor
   });
diff --git a/packages/render-html/src/elements/useIMGNormalizedSource.ts b/packages/render-html/src/elements/useIMGNormalizedSource.ts
@@ -0,0 +1,29 @@
+import { useMemo, useRef } from 'react';
+import { useSharedProps } from '../context/SharedPropsProvider';
+import { ImageDimensions } from '../shared-types';
+import { UseIMGElementStateProps } from './img-types';
+
+export default function useIMGNormalizedSource({
+  source,
+  concreteDimensions
+}: Pick<UseIMGElementStateProps, 'source'> & {
+  concreteDimensions: ImageDimensions | null;
+}) {
+  const cachedDimensions = useRef(concreteDimensions);
+  const { provideEmbeddedHeaders } = useSharedProps();
+  return useMemo(() => {
+    if (source.uri && typeof provideEmbeddedHeaders === 'function') {
+      const headers = provideEmbeddedHeaders(source.uri, 'img', {
+        printWidth: cachedDimensions.current?.width,
+        printHeight: cachedDimensions.current?.height
+      });
+      if (headers) {
+        return {
+          headers,
+          ...source
+        };
+      }
+    }
+    return source;
+  }, [provideEmbeddedHeaders, source]);
+}
diff --git a/packages/render-html/src/helpers/selectSharedProps.ts b/packages/render-html/src/helpers/selectSharedProps.ts
@@ -2,12 +2,12 @@ import pickBy from 'ramda/src/pickBy';
 import pick from 'ramda/src/pick';
 import pipe from 'ramda/src/pipe';
 import mergeRight from 'ramda/src/mergeRight';
-import { RenderHTMLSharedProps, RenderHTMLProps } from '../shared-types';
+import { RenderHTMLProps, RenderHTMLAmbiantSharedProps } from '../shared-types';
 import defaultSharedProps from '../context/defaultSharedProps';
 
 const selectSharedProps: (
   props: Partial<RenderHTMLProps>
-) => Required<RenderHTMLSharedProps> = pipe(
+) => RenderHTMLAmbiantSharedProps = pipe(
   pick(Object.keys(defaultSharedProps)),
   pickBy((val) => val != null),
   mergeRight(defaultSharedProps) as any
diff --git a/packages/render-html/src/internal-types.ts b/packages/render-html/src/internal-types.ts
@@ -3,7 +3,7 @@ import { Document, Element } from '@native-html/transient-render-engine';
 import {
   RenderHTMLProps,
   TNodeRendererProps,
-  RenderHTMLSharedProps
+  RenderHTMLAmbiantSharedProps
 } from './shared-types';
 
 export type SourceLoaderProps = Pick<
@@ -26,5 +26,5 @@ export interface TNodeSubRendererProps<T extends TNode>
   /**
    * Props shared across the whole render tree.
    */
-  sharedProps: Required<RenderHTMLSharedProps>;
+  sharedProps: RenderHTMLAmbiantSharedProps;
 }
diff --git a/packages/render-html/src/shared-types.ts b/packages/render-html/src/shared-types.ts
@@ -228,6 +228,39 @@ export interface RenderHTMLPassedProps {
   renderersProps?: Partial<RenderersProps>;
 }
 
+/**
+ * A map which defines the type of parameters passed as third argument
+ * of {@link EmbeddedHeadersProvider}.
+ */
+export interface EmbeddedWithHeadersParamsMap {
+  img: {
+    /**
+     * The print height of the image in DPI, if it can be determined beforehand
+     * (for example, with a _height_ attribute set or an inline style).
+     */
+    printHeight?: number;
+    /**
+     * The print width of the image in DPI, if it can be determined beforehand
+     * (for example, with a _width_ attribute set or an inline style).
+     */
+    printWidth?: number;
+  };
+}
+
+/**
+ * Tag names eligible for headers providing.
+ */
+export type EmbeddedWithHeadersTagName = keyof EmbeddedWithHeadersParamsMap;
+
+/**
+ * A function to provide headers to a peculiar embedded element.
+ */
+export type EmbeddedHeadersProvider = <T extends EmbeddedWithHeadersTagName>(
+  uri: string,
+  tagName: T,
+  params: EmbeddedWithHeadersParamsMap[T]
+) => Record<string, string> | null | void;
+
 /**
  * Props shared across renderers.
  *
@@ -434,9 +467,10 @@ export interface RenderHTMLSharedProps {
    *
    * @example
    *
-   * ```tsx
-   * function provideEmbeddedHeaders(uri: string, tagName: string) {
-   *    if (tagName === "img" && uri.startsWith("https://example.com")) {
+   * ```js
+   * function provideEmbeddedHeaders(uri, tagName, params) {
+   *    if (tagName === "img" &&
+   *        uri.startsWith("https://example.com")) {
    *     return {
    *      Authorization: "Bearer daem6QuaeloopheiD7Oh"
    *    }
@@ -447,12 +481,23 @@ export interface RenderHTMLSharedProps {
    * <RenderHTML provideEmbeddedHeaders={provideEmbeddedHeaders} />
    * ```
    */
-  provideEmbeddedHeaders?: (
-    embeddedUri: string,
-    tagName: string
-  ) => Record<string, string> | null | void;
+  provideEmbeddedHeaders?: EmbeddedHeadersProvider;
 }
 
+type SharedPropsWithoutFallback = Exclude<
+  keyof RenderHTMLSharedProps,
+  'provideEmbeddedHeaders' | 'GenericPressable' | 'customListStyleSpecs'
+>;
+
+/**
+ * Shared props available with {@link useSharedProps} hook or `sharedProp`
+ * custom renderers prop.
+ */
+export type RenderHTMLAmbiantSharedProps = Required<
+  Pick<RenderHTMLSharedProps, SharedPropsWithoutFallback>
+> &
+  Omit<RenderHTMLSharedProps, SharedPropsWithoutFallback>;
+
 /**
  * Configuration for the {@link TRenderEngineProvider} component.
  *
@@ -1073,7 +1118,7 @@ export interface InternalRendererProps<T extends TNode>
   /**
    * Props shared across the whole render tree.
    */
-  sharedProps: Required<RenderHTMLSharedProps>;
+  sharedProps: RenderHTMLAmbiantSharedProps;
 
   /**
    * Styles extracted with {@link TNode.getNativeStyles}.
