Add insertionPoint option in EmotionCache (#2521)

mnajdova · Andarist · web-flow · commit 516fe458058c · 2021-11-03T08:40:34.000+01:00
* Add insertionPoint option in EmotionCache * yarn changeset * yarn lint * Add tests as per view * Updated changeset, improved tests * Update packages/sheet/src/index.js * Update packages/cache/__tests__/index.js Co-authored-by: Mateusz Burzyński <mateuszburzynski@gmail.com> * Improve tests * Use @testing-library * Address comments from review * Fix some flow issues * fix selectors * small tweaks Co-authored-by: Mateusz Burzyński <mateuszburzynski@gmail.com>
diff --git a/.changeset/sixty-balloons-build.md b/.changeset/sixty-balloons-build.md
@@ -0,0 +1,31 @@
+---
+'@emotion/cache': minor
+'@emotion/sheet': minor
+---
+
+Add insertionPoint option to the EmotionCache, to insert rules after the specified element.
+
+```jsx
+const head = document.querySelector('head')
+
+// <meta name="emotion-insertion-point" content="">
+const emotionInsertionPoint = document.createElement('meta')
+emotionInsertionPoint.setAttribute('name', 'emotion-insertion-point')
+emotionInsertionPoint.setAttribute('content', '')
+
+head.appendChild(emotionInsertionPoint)
+
+// the emotion sheets should be inserted right after the meta tag
+const cache = createCache({
+  key: 'my-app',
+  insertionPoint: emotionInsertionPoint
+})
+
+function App() {
+  return (
+    <CacheProvider value={cache}>
+      <Main />
+    </CacheProvider>
+  )
+}
+```
diff --git a/packages/cache/__tests__/__snapshots__/index.js.snap b/packages/cache/__tests__/__snapshots__/index.js.snap
@@ -1,3 +1,27 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`should accept insertionPoint option 1`] = `
+<head>
+  
+    
+  <style
+    id="first"
+  />
+  <style
+    data-emotion="test-insertion-point"
+    data-s=""
+  >
+    
+    .test-insertion-point-83n355{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;color:blue;}
+  </style>
+  
+    
+  <style
+    id="last"
+  />
+  
+  
+</head>
+`;
+
 exports[`throws correct error with invalid key 1`] = `"Emotion key must only contain lower case alphabetical characters and - but \\".\\" was passed"`;
diff --git a/packages/cache/__tests__/index.js b/packages/cache/__tests__/index.js
@@ -1,8 +1,36 @@
 // @flow
+/** @jsx jsx */
+import 'test-utils/next-env'
+import { safeQuerySelector } from 'test-utils'
 import createCache from '@emotion/cache'
+import { jsx, CacheProvider } from '@emotion/react'
+import { render } from '@testing-library/react'
 
 test('throws correct error with invalid key', () => {
   expect(() => {
     createCache({ key: '.' })
   }).toThrowErrorMatchingSnapshot()
 })
+
+it('should accept insertionPoint option', () => {
+  const head = safeQuerySelector('head')
+
+  head.innerHTML = `
+    <style id="first"></style>
+    <style id="last"></style>
+  `
+
+  // the sheet should be inserted between the first and last style nodes
+  const cache = createCache({
+    key: 'test-insertion-point',
+    insertionPoint: safeQuerySelector('#first')
+  })
+
+  render(
+    <CacheProvider value={cache}>
+      <div css={{ display: 'flex', color: 'blue' }} />
+    </CacheProvider>
+  )
+
+  expect(document.head).toMatchSnapshot()
+})
diff --git a/packages/cache/src/index.js b/packages/cache/src/index.js
@@ -28,7 +28,8 @@ export type Options = {
   key: string,
   container?: HTMLElement,
   speedy?: boolean,
-  prepend?: boolean
+  prepend?: boolean,
+  insertionPoint?: HTMLElement
 }
 
 let getServerStylisCache = isBrowser
@@ -252,7 +253,8 @@ let createCache = (options: Options): EmotionCache => {
       container: ((container: any): HTMLElement),
       nonce: options.nonce,
       speedy: options.speedy,
-      prepend: options.prepend
+      prepend: options.prepend,
+      insertionPoint: options.insertionPoint
     }),
     nonce: options.nonce,
     inserted,
diff --git a/packages/cache/types/index.d.ts b/packages/cache/types/index.d.ts
@@ -36,7 +36,9 @@ export interface Options {
   key: string
   container?: HTMLElement
   speedy?: boolean
+  /** @deprecate use `insertionPoint` instead */
   prepend?: boolean
+  insertionPoint?: HTMLElement
 }
 
 export default function createCache(options: Options): EmotionCache
diff --git a/packages/sheet/README.md b/packages/sheet/README.md
@@ -49,8 +49,39 @@ This defines how rules are inserted. If it is true, rules will be inserted with
 
 #### prepend
 
+**Deprecated:** Please use `insertionPoint` option instead.
+
 This defines where rules are inserted into the `container`. By default they are appended but this can be changed by using `prepend: true` option.
 
+#### insertionPoint
+
+This defines specific dom node after which the rules are inserted into the `container`. You can use a `meta` tag to specify the specific location:
+
+```jsx
+const head = document.querySelector('head')
+
+// <meta name="emotion-insertion-point" content="">
+const emotionInsertionPoint = document.createElement('meta')
+emotionInsertionPoint.setAttribute('name', 'emotion-insertion-point')
+emotionInsertionPoint.setAttribute('content', '')
+
+head.appendChild(emotionInsertionPoint)
+
+// the emotion sheets should be inserted right after the meta tag
+const cache = createCache({
+  key: 'my-app',
+  insertionPoint: emotionInsertionPoint
+})
+
+function App() {
+  return (
+    <CacheProvider value={cache}>
+      <Main />
+    </CacheProvider>
+  )
+}
+```
+
 ### Methods
 
 #### insert
diff --git a/packages/sheet/__tests__/__snapshots__/index.js.snap b/packages/sheet/__tests__/__snapshots__/index.js.snap
@@ -1,5 +1,39 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`StyleSheet should accept insertionPoint option 1`] = `
+<html>
+  <head>
+    
+      
+    <style
+      id="first"
+    />
+    <style
+      data-emotion=""
+      data-s=""
+    >
+      
+      html { color: hotpink; }
+    </style>
+    <style
+      data-emotion=""
+      data-s=""
+    >
+      
+      * { box-sizing: border-box; }
+    </style>
+    
+      
+    <style
+      id="last"
+    />
+    
+    
+  </head>
+  <body />
+</html>
+`;
+
 exports[`StyleSheet should accept prepend option 1`] = `
 <html>
   <head>
@@ -212,3 +246,28 @@ exports[`StyleSheet should use the container option instead of document.head to
   </body>
 </html>
 `;
+
+exports[`StyleSheet should work if insertionPoint is last element 1`] = `
+<html>
+  <head>
+    <style
+      id="last"
+    />
+    <style
+      data-emotion=""
+      data-s=""
+    >
+      
+      html { color: hotpink; }
+    </style>
+    <style
+      data-emotion=""
+      data-s=""
+    >
+      
+      * { box-sizing: border-box; }
+    </style>
+  </head>
+  <body />
+</html>
+`;
diff --git a/packages/sheet/__tests__/index.js b/packages/sheet/__tests__/index.js
@@ -17,6 +17,11 @@ afterEach(() => {
   jest.clearAllMocks()
 })
 
+beforeEach(() => {
+  safeQuerySelector('head').innerHTML = ''
+  safeQuerySelector('body').innerHTML = ''
+})
+
 describe('StyleSheet', () => {
   it('should be speedy by default in production', () => {
     process.env.NODE_ENV = 'production'
@@ -98,8 +103,6 @@ describe('StyleSheet', () => {
     expect(sheet.tags).toHaveLength(1)
     expect(sheet.tags[0].parentNode).toBe(container)
     sheet.flush()
-    // $FlowFixMe
-    document.body.removeChild(container)
   })
 
   it('should accept prepend option', () => {
@@ -114,7 +117,44 @@ describe('StyleSheet', () => {
     expect(document.documentElement).toMatchSnapshot()
 
     sheet.flush()
-    head.removeChild(otherStyle)
+  })
+
+  it('should accept insertionPoint option', () => {
+    const head = safeQuerySelector('head')
+
+    head.innerHTML = `
+      <style id="first"></style>
+      <style id="last"></style>
+    `
+
+    // the sheet should be inserted between the first and last style nodes
+    const sheet = new StyleSheet({
+      ...defaultOptions,
+      insertionPoint: safeQuerySelector('#first')
+    })
+    sheet.insert(rule)
+    sheet.insert(rule2)
+    expect(document.documentElement).toMatchSnapshot()
+
+    sheet.flush()
+  })
+
+  it('should work if insertionPoint is last element', () => {
+    const head = safeQuerySelector('head')
+    const lastStyle = document.createElement('style')
+    lastStyle.setAttribute('id', 'last')
+    head.appendChild(lastStyle)
+
+    // the sheet should be inserted after the first node
+    const sheet = new StyleSheet({
+      ...defaultOptions,
+      insertionPoint: lastStyle
+    })
+    sheet.insert(rule)
+    sheet.insert(rule2)
+    expect(document.documentElement).toMatchSnapshot()
+
+    sheet.flush()
   })
 
   it('should be able to hydrate styles', () => {
@@ -179,7 +219,6 @@ describe('StyleSheet', () => {
     expect(document.documentElement).toMatchSnapshot()
 
     sheet.flush()
-    head.removeChild(otherStyle)
   })
 
   it('should not crash when flushing when styles are already detached', () => {
diff --git a/packages/sheet/src/index.js b/packages/sheet/src/index.js
@@ -44,7 +44,8 @@ export type Options = {
   key: string,
   container: HTMLElement,
   speedy?: boolean,
-  prepend?: boolean
+  prepend?: boolean,
+  insertionPoint?: HTMLElement
 }
 
 function createStyleElement(options: {
@@ -70,6 +71,7 @@ export class StyleSheet {
   nonce: string | void
   prepend: boolean | void
   before: Element | null
+  insertionPoint: HTMLElement | void
   constructor(options: Options) {
     this.isSpeedy =
       options.speedy === undefined
@@ -82,13 +84,20 @@ export class StyleSheet {
     this.key = options.key
     this.container = options.container
     this.prepend = options.prepend
+    this.insertionPoint = options.insertionPoint
     this.before = null
   }
 
   _insertTag = (tag: HTMLStyleElement) => {
     let before
     if (this.tags.length === 0) {
-      before = this.prepend ? this.container.firstChild : this.before
+      if (this.insertionPoint) {
+        before = this.insertionPoint.nextSibling
+      } else if (this.prepend) {
+        before = this.container.firstChild
+      } else {
+        before = this.before
+      }
     } else {
       before = this.tags[this.tags.length - 1].nextSibling
     }
diff --git a/packages/sheet/types/index.d.ts b/packages/sheet/types/index.d.ts
@@ -6,7 +6,9 @@ export interface Options {
   key: string
   container: HTMLElement
   speedy?: boolean
+  /** @deprecate use `insertionPoint` instead */
   prepend?: boolean
+  insertionPoint?: HTMLElement
 }
 
 export class StyleSheet {

Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,9 @@ export interface Options {`
`36`	`36`	`key: string`
`37`	`37`	`container?: HTMLElement`
`38`	`38`	`speedy?: boolean`
	`39`	+ /** @deprecate use `insertionPoint` instead */
`39`	`40`	`prepend?: boolean`
	`41`	`+ insertionPoint?: HTMLElement`
`40`	`42`	`}`
`41`	`43`
`42`	`44`	`export default function createCache(options: Options): EmotionCache`
Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,9 @@ export interface Options {`
`6`	`6`	`key: string`
`7`	`7`	`container: HTMLElement`
`8`	`8`	`speedy?: boolean`
	`9`	+ /** @deprecate use `insertionPoint` instead */
`9`	`10`	`prepend?: boolean`
	`11`	`+ insertionPoint?: HTMLElement`
`10`	`12`	`}`
`11`	`13`
`12`	`14`	`export class StyleSheet {`