From b51caeedc198caa8821a4a9ee5955a419e0d22fc Mon Sep 17 00:00:00 2001
From: hasparus <hasparus@gmail.com>
Date: Tue, 19 May 2020 00:11:56 +0200
Subject: [PATCH] Document merge and tweak types

---
 packages/core/src/index.ts      | 15 +++++++++------
 packages/docs/src/pages/api.mdx | 22 +++++++++++++++++++---
 2 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 42cd6dc41..fcbd2e4da 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -13,16 +13,16 @@ import './react-jsx'
 
 export * from './types'
 
-const getCSS = props => {
+const getCSS = (props) => {
   if (!props.sx && !props.css) return undefined
-  return theme => {
+  return (theme) => {
     const styles = css(props.sx)(theme)
     const raw = typeof props.css === 'function' ? props.css(theme) : props.css
     return [styles, raw]
   }
 }
 
-const parseProps = props => {
+const parseProps = (props) => {
   if (!props) return null
   const next: typeof props & { css?: InterpolationWithTheme<any> } = {}
   for (let key in props) {
@@ -55,7 +55,7 @@ const canUseSymbol = typeof Symbol === 'function' && Symbol.for
 const REACT_ELEMENT = canUseSymbol ? Symbol.for('react.element') : 0xeac7
 const FORWARD_REF = canUseSymbol ? Symbol.for('react.forward_ref') : 0xeac7
 
-const isMergeableObject = n => {
+const isMergeableObject = (n) => {
   return (
     !!n &&
     typeof n === 'object' &&
@@ -66,10 +66,13 @@ const isMergeableObject = n => {
 
 const arrayMerge = (destinationArray, sourceArray, options) => sourceArray
 
-export const merge = <T>(a: Partial<T>, b: Partial<T>): T =>
+/**
+ * Deeply merge themes
+ */
+export const merge = (a: Theme, b: Theme): Theme =>
   deepmerge(a, b, { isMergeableObject, arrayMerge })
 
-merge.all = <T>(...args: Partial<T>[]) =>
+merge.all = <T = Theme>(...args: Partial<T>[]) =>
   deepmerge.all<T>(args, { isMergeableObject, arrayMerge })
 
 interface BaseProviderProps {
diff --git a/packages/docs/src/pages/api.mdx b/packages/docs/src/pages/api.mdx
index 1c1275e3e..659f814f4 100644
--- a/packages/docs/src/pages/api.mdx
+++ b/packages/docs/src/pages/api.mdx
@@ -19,7 +19,7 @@ It adds support for the `sx` prop, which uses Emotion's create element function
 /** @jsx jsx */
 import { jsx } from 'theme-ui'
 
-export default props => (
+export default (props) => (
   <div
     {...props}
     sx={{
@@ -89,7 +89,9 @@ Note that this will increase the CSS specificity of child elements, and you may
 
 ```jsx
 <BaseStyles>
-  <h1>Styled based on <code>theme.styles</code></h1>
+  <h1>
+    Styled based on <code>theme.styles</code>
+  </h1>
 </BaseStyles>
 ```
 
@@ -121,7 +123,21 @@ An existential getter function used internally.
 
 ### `merge`
 
-A deep object merge function used internally.
+A function to deeply merge themes.
+
+**Usage**
+
+```jsx
+import dark from '@theme-ui/preset-dark'
+
+const theme = merge(dark, {
+  fontWeights: {
+    body: 500,
+    heading: 700,
+    bold: 900,
+  },
+})
+```
 
 ### `InitializeColorMode`