feat(cache): add option to disable xstyled cache (#379)

Also document it.

packages/system/src/cache.ts

@@ -15,7 +15,12 @@ const cacheSupported: boolean =
 
 const caches = cacheSupported ? new WeakMap<ITheme, ThemeCache>() : null
 
+const isCacheDisabled = (theme: ITheme): boolean =>
+  theme?.xstyled?.cache === false
+
 const getThemeCache = (theme: ITheme): ThemeCache | null => {
+  const cacheDisabled = isCacheDisabled(theme)
+  if (cacheDisabled) return null
   if (caches === null) return null
   if (caches.has(theme)) return caches.get(theme) || null
   const cache = {}

packages/system/src/defaultTheme.ts

@@ -516,6 +516,9 @@ export const defaultTheme = {
     disabled: '&:disabled, &[aria-disabled=true]',
     placeholder: '&::placeholder',
   },
+  xstyled: {
+    cache: true,
+  },
 }
 
 export type DefaultTheme = typeof defaultTheme

website/pages/docs/customization/cache.mdx

@@ -0,0 +1,24 @@
+---
+section: Customization
+title: Colors
+slug: /docs/colors/
+order: 4
+---
+
+# Cache
+
+Customizing the cache behaviour of xstyled.
+
+<carbon-ad />
+
+## Turn off cache
+
+By default xstyled cache every property resolution. If you need to disabled the cache behaviour, you can do it in the theme.
+
+```js
+export const theme = {
+  xstyled: {
+    cache: false,
+  },
+}
+```