feat: export some useful Flow types (#154)

These types may be useful to consumers to better type their own code.

This commit aims to get on pair with #153

Author: FezVrasta

.flowconfig

@@ -10,5 +10,6 @@
 [lints]
 
 [options]
+suppress_comment=\\(.\\|\n\\)*\\$FlowExpectError
 
 [strict]

README.md

@@ -244,6 +244,13 @@ const Example = () => (
 );
 ```
 
+## Flow and TypeScript types
+
+This library is built with Flow but it supports TypeScript as well.
+
+You can find the exported Flow types in `src/index.js`, and the
+TypeScript definitions in `typings/react-popper.d.ts`.
+
 ## Running Locally
 
 #### clone repo

package.json

@@ -18,7 +18,7 @@
     "build:clean": "rimraf dist/ && rimraf lib/",
     "build:es": "cross-env BABEL_ENV=es babel src --ignore '*.test.js,__mocks__' --out-dir lib/es",
     "build:cjs": "cross-env BABEL_ENV=cjs babel src --ignore '*.test.js,__mocks__' --out-dir lib/cjs",
-    "build:flow": "flow-copy-source --ignore '{__mocks__/*,*.test}.js' src lib/es",
+    "build:flow": "flow-copy-source --ignore '{__mocks__/*,*.test}.js' src lib/cjs",
     "demo:dev": "parcel --out-dir demo/dist demo/index.html",
     "demo:build": "parcel build --out-dir demo/dist demo/index.html --public-url=/react-popper",
     "demo:deploy": "yarn demo:build && gh-pages -d demo/dist",
@@ -62,6 +62,7 @@
     "create-react-context": "^0.2.1",
     "popper.js": "^1.14.1",
     "prop-types": "^15.6.1",
+    "typed-styles": "^0.0.5",
     "warning": "^3.0.0"
   },
   "devDependencies": {

src/Manager.js

@@ -7,7 +7,7 @@ export const ManagerContext: Context<{
   referenceNode?: ?HTMLElement,
 }> = createContext({ getReferenceRef: undefined, referenceNode: undefined });
 
-type ManagerProps = {
+export type ManagerProps = {
   children: Node,
 };
 type ManagerState = {

src/Popper.js

@@ -7,33 +7,36 @@ import PopperJS, {
   type Modifiers,
   type ReferenceObject,
 } from 'popper.js';
+import type { Style } from 'typed-styles';
 import { ManagerContext } from './Manager';
 import { unwrapArray } from './utils';
 
 type getRefFn = (?HTMLElement) => void;
-type Style = Object;
-
 type ReferenceElement = ReferenceObject | HTMLElement | null;
+type StyleOffsets = { top: number, left: number };
+type StylePosition = { position: 'absolute' | 'fixed' };
 
-type RenderProp = ({|
+export type PopperArrowProps = {
+  ref: getRefFn,
+  style: StyleOffsets & Style,
+};
+export type PopperChildrenProps = {|
   ref: getRefFn,
-  style: Style,
-  placement: ?Placement,
+  style: StyleOffsets & StylePosition & Style,
+  placement: Placement,
   outOfBoundaries: ?boolean,
   scheduleUpdate: () => void,
-  arrowProps: {
-    ref: getRefFn,
-    style: Style,
-  },
-|}) => Node;
+  arrowProps: PopperArrowProps,
+|};
+export type PopperChildren = PopperChildrenProps => Node;
 
-type PopperProps = {
+export type PopperProps = {
   modifiers?: Modifiers,
   placement?: Placement,
   eventsEnabled?: boolean,
   positionFixed?: boolean,
   referenceElement?: ReferenceElement,
-  children: RenderProp,
+  children: PopperChildren,
 };
 
 type PopperState = {

src/Reference.js

@@ -4,8 +4,9 @@ import warning from 'warning';
 import { ManagerContext } from './Manager';
 import { unwrapArray } from './utils';
 
-type ReferenceProps = {
-  children: ({ ref: (?HTMLElement) => void }) => Node,
+export type ReferenceChildrenProps = { ref: (?HTMLElement) => void };
+export type ReferenceProps = {
+  children: ReferenceChildrenProps => Node,
 };
 
 export default function Reference({ children }: ReferenceProps) {

src/__typings__/main-test.js

@@ -0,0 +1,52 @@
+// @flow
+
+// Please remember to update also the TypeScript test files that can
+// be found under `/typings/tests` please. Thanks! 🤗
+
+import React from 'react';
+import { Manager, Reference, Popper } from '..';
+
+export const Test = () => (
+  <Manager>
+    {/* $FlowExpectError: empty children */}
+    <Reference />
+    <Reference>{({ ref }) => <div ref={ref} />}</Reference>
+    <Popper
+      // $FlowExpectError: should be boolean
+      eventsEnabled="foo"
+      eventsEnabled
+      // $FlowExpectError: should be boolean
+      positionFixed={2}
+      positionFixed
+      // $FlowExpectError: enabled should be boolean, order number
+      modifiers={{ flip: { enabled: 'bar', order: 'foo' } }}
+      modifiers={{ flip: { enabled: false } }}
+    >
+      {({
+        ref,
+        style,
+        placement,
+        outOfBoundaries,
+        scheduleUpdate,
+        arrowProps,
+      }) => (
+        <div
+          ref={ref}
+          style={{ ...style, opacity: outOfBoundaries ? 0 : 1 }}
+          data-placement={placement}
+          onClick={() => scheduleUpdate()}
+        >
+          Popper
+          <div ref={arrowProps.ref} style={arrowProps.style} />
+        </div>
+      )}
+    </Popper>
+    <Popper>
+      {({ ref, style, placement }) => (
+        <div ref={ref} style={style} data-placement={placement}>
+          Popper
+        </div>
+      )}
+    </Popper>
+  </Manager>
+);

src/index.js

@@ -1,6 +1,26 @@
 // @flow
+
+// Public components
 import Popper, { placements } from './Popper';
 import Manager from './Manager';
 import Reference from './Reference';
-
 export { Popper, placements, Manager, Reference };
+
+// Public types
+import type { Placement } from 'popper.js';
+import type { ManagerProps } from './Manager';
+import type { ReferenceProps, ReferenceChildrenProps } from './Reference';
+import type {
+  PopperChildrenProps,
+  PopperArrowProps,
+  PopperProps,
+} from './Popper';
+export type {
+  Placement,
+  ManagerProps,
+  ReferenceProps,
+  ReferenceChildrenProps,
+  PopperChildrenProps,
+  PopperArrowProps,
+  PopperProps,
+};

typings/tests/main-test.tsx

@@ -1,7 +1,10 @@
+// Please remember to update also the Flow test files that can
+// be found under `/src/__typings__` please. Thanks! 🤗
+
 import * as React from 'react';
 import { Manager, Reference, Popper } from '../..';
 
-const Test = () => (
+export const Test = () => (
   <Manager>
     <Reference>{({ ref }) => <div ref={ref} />}</Reference>
     <Popper

yarn.lock

@@ -6327,6 +6327,10 @@ type-check@~0.3.2:
   dependencies:
     prelude-ls "~1.1.2"
 
+typed-styles@^0.0.5:
+  version "0.0.5"
+  resolved "https://registry.yarnpkg.com/typed-styles/-/typed-styles-0.0.5.tgz#a60df245d482a9b1adf9c06c078d0f06085ed1cf"
+
 typedarray@^0.0.6:
   version "0.0.6"
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"