fix: expost FilteringStyledOptions from native, tweak up some tests…

…, add some comments

packages/native/types/base.d.ts

@@ -58,7 +58,10 @@ export type Interpolation<
   | ArrayInterpolation<MergedProps, StyleType>
   | FunctionInterpolation<MergedProps, StyleType>
 
-/** Same as StyledOptions but shouldForwardProp must be a type guard */
+/**
+ * Same as StyledOptions but shouldForwardProp must be a type guard (https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates).
+ * Practical sense: you can define and reuse atomic `shouldForwardProp` filters that are strictly bound with some `ForwardedProps` type.
+ */
 export interface FilteringStyledOptions<
   Props = Record<PropertyKey, any>,
   ForwardedProps extends keyof Props = keyof Props

packages/native/types/index.d.ts

@@ -18,6 +18,7 @@ export {
   ArrayInterpolation,
   CreateStyledComponent,
   CSSInterpolation,
+  FilteringStyledOptions,
   FunctionInterpolation,
   Interpolation,
   InterpolationPrimitive,

packages/native/types/tests.tsx

@@ -7,7 +7,12 @@ import {
   TextStyle,
   View
 } from 'react-native'
-import styled, { css, ReactNativeStyle, StyledOptions } from '@emotion/native'
+import styled, {
+  css,
+  ReactNativeStyle,
+  StyledOptions,
+  FilteringStyledOptions
+} from '@emotion/native'
 
 declare module '@emotion/react' {
   // tslint:disable-next-line: strict-export-declare-modifiers
@@ -168,16 +173,14 @@ export const ImageFullWidthContained = styled.Image`
 }
 
 {
-  const styledOpts: StyledOptions = {
-    shouldForwardProp: p => true
-  }
-  const styledOptsParameterized: StyledOptions<{ foo: string }> = {
-    shouldForwardProp: (p: 'foo') => true
-  }
-  const styledOptsParameterizedBroken: StyledOptions<{ foo: string }> = {
-    shouldForwardProp: (p: 'bar') => true // $ExpectError
-  }
-  const styledOptsBroken: StyledOptions = {
-    shouldForwardProp: (p1, p2) => true // $ExpectError
-  }
+  // Props forwarding through StyledOptions and FilteringStyledOptions
+
+  styled(View, { shouldForwardProp: (prop: 'testID') => true })({})
+
+  styled(View, {
+    shouldForwardProp: (prop: 'testID'): prop is 'testID' => true
+  })({})
+
+  // $ExpectError
+  styled(View, { shouldForwardProp: (prop: 'foo') => true })({})
 }

packages/styled/types/base.d.ts

@@ -17,7 +17,10 @@ export {
 
 export { ComponentSelector, Interpolation }
 
-/** Same as StyledOptions but shouldForwardProp must be a type guard */
+/**
+ * Same as StyledOptions but shouldForwardProp must be a type guard (https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates).
+ * Practical sense: you can define and reuse atomic `shouldForwardProp` filters that are strictly bound with some `ForwardedProps` type.
+ */
 export interface FilteringStyledOptions<
   Props = Record<PropertyKey, any>,
   ForwardedProps extends keyof Props = keyof Props

packages/styled/types/tests.tsx

@@ -266,13 +266,13 @@ const Input5 = styled.input`
   const shouldForwardProp9: FilteringStyledOptions<
     { foo: string; bar: string },
     'foo'
-  >['shouldForwardProp'] = (prop: 'foo'): prop is 'foo' => true
+  >['shouldForwardProp'] = (prop: 'foo' | 'bar'): prop is 'foo' => true
 
   // $ExpectError
   const shouldForwardProp10: FilteringStyledOptions<
     { foo: string; bar: string },
     'foo'
-  >['shouldForwardProp'] = (prop: 'bar'): prop is 'bar' => true
+  >['shouldForwardProp'] = (prop: 'foo' | 'bar'): prop is 'bar' => true
 
   styled('div', { shouldForwardProp: (prop: 'color') => true })({})