@spark-ui/tailwind-plugins 2.0.0 → 2.1.1

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.1.1](https://github.com/adevinta/spark/compare/@spark-ui/tailwind-plugins@2.1.0...@spark-ui/tailwind-plugins@2.1.1) (2023-03-19)
+
+**Note:** Version bump only for package @spark-ui/tailwind-plugins
+
+# [2.1.0](https://github.com/adevinta/spark/compare/@spark-ui/tailwind-plugins@2.0.0...@spark-ui/tailwind-plugins@2.1.0) (2023-03-17)
+
+### Bug Fixes
+
+- add early return ([3cc0916](https://github.com/adevinta/spark/commit/3cc0916d4fe1aafd76814646b804be45b8870f34)), closes [#411](https://github.com/adevinta/spark/issues/411)
+
+### Features
+
+- **tailwind-plugins:** add spark theme plugin ([7009c51](https://github.com/adevinta/spark/commit/7009c513ab37b1118b89d7bada365156fb85f362)), closes [#411](https://github.com/adevinta/spark/issues/411)
+
 # [2.0.0](https://github.com/adevinta/spark/compare/@spark-ui/tailwind-plugins@1.1.2...@spark-ui/tailwind-plugins@2.0.0) (2023-03-15)
 
 ### Features

package/animations/index.stories.mdx

@@ -6,7 +6,7 @@ import { Alert } from '@docs/helpers/Alert'
 
 # Tailwind animation plugin
 
-## Installation
+<StoryHeading label="Installation" as="h2" />
 
 To use our Tailwind animation plugin, simply install the `@spark-ui/tailwind-plugins` package and add the animation plugin to your `tailwind.config.js` file
 
@@ -26,7 +26,7 @@ module.exports = {
 
 ```
 
-## Usage
+<StoryHeading label="Usage" as="h2" />
 
 This plugin provides the following **animation-related** declaration properties that are missing by default in **Tailwind**:
 
@@ -47,7 +47,7 @@ This plugin also includes four animation keyframes:
 - **animate-slide-bottom**: `animate-slide-bottom`
 - **animate-slide-left**: `animate-slide-left`
 
-<StoryHeading label="Configuration" as="h3" />
+<StoryHeading label="Configuration" as="h2" />
 
 You can customize the **CSS class prefix** using the `prefixVariant` option.
 

package/index.js

@@ -1,8 +1,10 @@
 /* eslint-disable @typescript-eslint/no-var-requires */
 const animations = require('./animations')
 const sizings = require('./sizings')
+const sparkTheme = require('./spark-theme')
 
 module.exports = {
   animations,
   sizings,
+  sparkTheme,
 }

package/index.stories.mdx

@@ -8,5 +8,6 @@ import { Alert } from '@docs/helpers/Alert'
 
 Below is a list of our Tailwind plugins:
 
+- [spark theme](?path=/docs/utils-tailwind-plugins-spark-theme--docs)
 - [animations](?path=/docs/utils-tailwind-plugins-animations--docs)
 - [sizings](?path=/docs/utils-tailwind-plugins-sizings--docs)

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@spark-ui/tailwind-plugins",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "description": "Spark Tailwind plugins",
   "publishConfig": {
     "access": "public"
   },
   "main": "index.js",
+  "dependencies": {
+    "@spark-ui/theme-utils": "^2.9.1"
+  },
   "peerDependencies": {
     "tailwindcss": "4.0.0"
   },
@@ -14,5 +17,5 @@
     "url": "git@github.com:adevinta/spark.git",
     "directory": "packages/utils/tailwind-plugins"
   },
-  "gitHead": "843a4c9ef31a1f346e4052685ccddceb494fc7bd"
+  "gitHead": "d74864d0a900c8bab3d505cb796fb2cb51527a61"
 }

package/sizings/index.stories.mdx

@@ -6,7 +6,7 @@ import { Alert } from '@docs/helpers/Alert'
 
 # Tailwind sizing plugin
 
-## Installation
+<StoryHeading label="Installation" as="h2" />
 
 To use our Tailwind sizing plugin, simply install the `@spark-ui/tailwind-plugins` package and add the animation plugin to your `tailwind.config.js` file
 
@@ -27,7 +27,7 @@ module.exports = {
 
 ```
 
-## Usage
+<StoryHeading label="Usage" as="h2" />
 
 This plugin predefines a sizing range with the following pixel values:
 
@@ -43,7 +43,7 @@ These values are converted into rem units based on the specified **HTML font siz
 
 The plugin generates CSS variables for each size value, which can then be used for `width`, `height`, `max-width`, `max-height`, and `translate` properties.
 
-<StoryHeading label="Example" as="h3" />
+<StoryHeading label="Example" as="h2" />
 
 To set the `width` of an element using the sizing plugin, use the `w-sz-{size}` class, where`{size}` is the desired pixel value from the predefined range:
 
@@ -53,7 +53,7 @@ To set the `width` of an element using the sizing plugin, use the `w-sz-{size}`
 
 This will set the width of the element to **10px** (0.625rem, if `htmlFontSize` is 16) using the custom sizing scale provided by the plugin.
 
-<StoryHeading label="Configuration" as="h3" />
+<StoryHeading label="Configuration" as="h2" />
 
 You can customize the **base html font size** using the `htmlFontSize` option.
 

package/spark-theme/constants.js

@@ -0,0 +1,15 @@
+const tailwindCategoryKeys = {
+  colors: 'colors',
+  fontSize: 'fontSize',
+  screens: 'screens',
+}
+
+const unassignedColors = {
+  inherit: 'inherit',
+  current: 'currentColor',
+  transparent: 'transparent',
+}
+
+const DEFAULT_KEY = 'DEFAULT'
+
+module.exports = { tailwindCategoryKeys, unassignedColors, DEFAULT_KEY }

package/spark-theme/getCSSVariableDeclarations.js

@@ -0,0 +1,53 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+const { DEFAULT_KEY } = require('./constants')
+const { hexRgb } = require('./hexRgb')
+
+const {
+  doubleHyphensRegex,
+  getRemEquivalentValue,
+  isHex,
+  isObject,
+  isStringOrNumber,
+  toKebabCase,
+} = require('./utils')
+
+function getCSSVariableDeclarations(_theme, htmlFontSize) {
+  const CSSVariableObj = {}
+
+  function traverse(theme, paths = []) {
+    Object.entries(theme).forEach(([key, value]) => {
+      if (isObject(value)) {
+        return traverse(value, paths.concat(key))
+      }
+
+      if (isStringOrNumber(value)) {
+        const getFormattedValue = () => {
+          if (isHex(value)) {
+            const { red, green, blue } = hexRgb(value)
+
+            return `${red} ${green} ${blue}`
+          }
+
+          if (/rem$/gi.test(value)) {
+            return getRemEquivalentValue(value, htmlFontSize)
+          }
+
+          return value
+        }
+
+        CSSVariableObj[
+          `--${[...paths, key === DEFAULT_KEY ? key.toLowerCase() : key]
+            .map(toKebabCase)
+            .join('-')
+            .replace(doubleHyphensRegex, '-')}`
+        ] = getFormattedValue()
+      }
+    })
+  }
+
+  traverse(_theme)
+
+  return CSSVariableObj
+}
+
+module.exports = { getCSSVariableDeclarations }

package/spark-theme/getCSSVariableReferences.js

@@ -0,0 +1,111 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+const { DEFAULT_KEY, tailwindCategoryKeys, unassignedColors } = require('./constants')
+const {
+  doubleHyphensRegex,
+  hasNumber,
+  isAlphanumericWithLeadingLetter,
+  isCamelCase,
+  isHex,
+  isObject,
+  isStringOrNumber,
+  toKebabCase,
+} = require('./utils')
+
+function getCSSVariableReferences(_theme) {
+  const themeCpy = JSON.parse(JSON.stringify(_theme))
+
+  const { fontSize, colors, screens } = tailwindCategoryKeys
+
+  /* eslint-disable complexity */
+  function traverse(theme, paths = []) {
+    Object.entries(theme).forEach(([key, value]) => {
+      // 👀 see: https://tailwindcss.com/docs/font-size#providing-a-default-line-height
+      if (isObject(value) && !paths.length && key === fontSize) {
+        Object.keys(value).forEach(k => {
+          const prefix = toKebabCase(fontSize)
+          if (isStringOrNumber(value[k])) {
+            theme[key][k] = `var(--${prefix}-${k})`
+
+            return
+          }
+
+          const kebabedKey = isCamelCase(k) || hasNumber(k) ? toKebabCase(k) : k
+
+          if (kebabedKey !== k) {
+            const tmp = theme[key][k]
+            delete theme[key][k]
+            theme[key][kebabedKey] = tmp
+          }
+
+          theme[key][kebabedKey] = [
+            `var(--${prefix}-${kebabedKey}-font-size)`,
+            {
+              ...(value[kebabedKey].lineHeight && {
+                lineHeight: `var(--${prefix}-${kebabedKey}-line-height)`,
+              }),
+              ...(value[kebabedKey].letterSpacing && {
+                letterSpacing: `var(--${prefix}-${kebabedKey}-letter-spacing)`,
+              }),
+              ...(value[kebabedKey].fontWeight && {
+                fontWeight: `var(--${prefix}-${kebabedKey}-font-weight)`,
+              }),
+            },
+          ]
+        })
+
+        return
+      }
+
+      if (isObject(value)) {
+        Object.keys(value).forEach(k => {
+          if (k === DEFAULT_KEY) {
+            return
+          }
+
+          if (!isObject(value[k]) && !isCamelCase(k)) {
+            return
+          }
+
+          const tmp = value[k]
+          delete value[k]
+          value[toKebabCase(k)] = tmp
+        })
+
+        return traverse(value, paths.concat(key))
+      }
+
+      if (isStringOrNumber(value)) {
+        const rootPath = paths[0] || ''
+        const isScreenValue = rootPath.includes(screens)
+        const isColorValue = rootPath.includes(colors)
+
+        const formattedValue = (() => {
+          if (isColorValue && isHex(value)) {
+            return `rgb(var(--${paths.join('-')}-${key}) / <alpha-value>)`
+          }
+          if (isScreenValue) {
+            return String(value).toLowerCase()
+          }
+
+          return `var(--${paths.join('-')}-${key.toLowerCase()})`
+        })()
+
+        const formattedKey = isAlphanumericWithLeadingLetter(key) ? toKebabCase(key) : key
+
+        if (formattedKey !== key) {
+          delete theme[key]
+        }
+
+        theme[formattedKey] = isScreenValue
+          ? formattedValue
+          : toKebabCase(formattedValue).replace(doubleHyphensRegex, '-')
+      }
+    })
+  }
+
+  traverse(themeCpy)
+
+  return { ...themeCpy, colors: { ...themeCpy.colors, ...unassignedColors } }
+}
+
+module.exports = { getCSSVariableReferences }

package/spark-theme/hexRgb.js

@@ -0,0 +1,51 @@
+// see 👀: https://github.com/sindresorhus/hex-rgb/blob/main/index.js
+
+const hexCharacters = 'a-f\\d'
+const match3or4Hex = `#?[${hexCharacters}]{3}[${hexCharacters}]?`
+const match6or8Hex = `#?[${hexCharacters}]{6}([${hexCharacters}]{2})?`
+const nonHexChars = new RegExp(`[^#${hexCharacters}]`, 'gi')
+const validHexSize = new RegExp(`^${match3or4Hex}$|^${match6or8Hex}$`, 'i')
+
+/* eslint-disable complexity */
+function hexRgb(hex, options = {}) {
+  if (typeof hex !== 'string' || nonHexChars.test(hex) || !validHexSize.test(hex)) {
+    throw new TypeError('Expected a valid hex string')
+  }
+
+  hex = hex.replace(/^#/, '')
+  let alphaFromHex = 1
+
+  if (hex.length === 8) {
+    alphaFromHex = Number.parseInt(hex.slice(6, 8), 16) / 255
+    hex = hex.slice(0, 6)
+  }
+
+  if (hex.length === 4) {
+    alphaFromHex = Number.parseInt(hex.slice(3, 4).repeat(2), 16) / 255
+    hex = hex.slice(0, 3)
+  }
+
+  if (hex.length === 3) {
+    hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2]
+  }
+
+  const number = Number.parseInt(hex, 16)
+  const red = number >> 16
+  const green = (number >> 8) & 255
+  const blue = number & 255
+  const alpha = typeof options.alpha === 'number' ? options.alpha : alphaFromHex
+
+  if (options.format === 'array') {
+    return [red, green, blue, alpha]
+  }
+
+  if (options.format === 'css') {
+    const alphaString = alpha === 1 ? '' : ` / ${Number((alpha * 100).toFixed(2))}%`
+
+    return `rgb(${red} ${green} ${blue}${alphaString})`
+  }
+
+  return { red, green, blue, alpha }
+}
+
+module.exports = { hexRgb }

package/spark-theme/index.js

@@ -0,0 +1,98 @@
+/* eslint-disable @typescript-eslint/no-var-requires */
+const { getCSSVariableDeclarations } = require('./getCSSVariableDeclarations')
+const { getCSSVariableReferences } = require('./getCSSVariableReferences')
+const { retrieveArrayDifferences, getAllObjectKeys } = require('./utils')
+
+const themeUtils = require('@spark-ui/theme-utils')
+const plugin = require('tailwindcss/plugin')
+
+const missingDefaultThemeErrorMsg =
+  'A default theme is required. Please ensure that the "themes" object passed to this plugin includes a "default" key containing your default theme.'
+
+const additionalItemsErrorMsg = (themeLabel, keys) =>
+  `The following keys: ${JSON.stringify(
+    keys
+  )} do not adhere to our Spark Theme interface and should be removed from the ${themeLabel} theme`
+
+const missingItemsErrorMsg = (themeLabel, keys) =>
+  `The following keys: ${JSON.stringify(
+    keys
+  )} are missing from the ${themeLabel} theme, but required to comply with our Spark Theme interface`
+
+module.exports = plugin.withOptions(
+  /**
+   * @typedef {Object} Options
+   * @property {Object} options.themes - An object containing your themes where each key corresponds to a data-theme attribute value.
+   * @property {number} htmlFontSize The base font size of your app.
+   */
+
+  /**
+   * @param {Object} options The options for the plugin.
+   * @param {Object} [options.themes={}] An object containing your themes where each key corresponds to a data-theme attribute value.
+   * @param {string} [options.htmlFontSize=16] The base font size to use to properly compute rem values.
+   * @returns {Function} The PostCSS plugin function.
+   */
+  options =>
+    ({ addBase }) => {
+      const opts = options || {
+        themes: {},
+      }
+
+      const { htmlFontSize = 16, themes } = opts
+
+      if (!themes.default) {
+        throw new Error(missingDefaultThemeErrorMsg)
+      }
+
+      const { missingItems, additionalItems } = retrieveArrayDifferences({
+        ref: getAllObjectKeys(themeUtils.defaultTheme),
+        comp: getAllObjectKeys(themes.default),
+      })
+
+      if (missingItems.length) {
+        throw new Error(missingItemsErrorMsg('default', missingItems))
+      }
+      if (additionalItems.length) {
+        throw new Error(additionalItemsErrorMsg('default', additionalItems))
+      }
+
+      addBase({
+        ':root': getCSSVariableDeclarations(themes.default, htmlFontSize),
+      })
+
+      Object.entries(themes).forEach(([key, value]) => {
+        if (key === 'default') {
+          return
+        }
+
+        const { missingItems, additionalItems } = retrieveArrayDifferences({
+          ref: getAllObjectKeys(themeUtils.defaultTheme),
+          comp: getAllObjectKeys(value),
+        })
+
+        if (missingItems.length) {
+          throw new Error(missingItemsErrorMsg(key, missingItems))
+        }
+        if (additionalItems.length) {
+          throw new Error(additionalItemsErrorMsg(key, additionalItems))
+        }
+
+        addBase({
+          [`[data-theme="${key}"]`]: getCSSVariableDeclarations(value, htmlFontSize),
+        })
+      })
+    },
+  options => {
+    const opts = options || {
+      themes: {},
+    }
+
+    const { themes } = opts
+
+    if (!themes.default) {
+      throw new Error(missingDefaultThemeErrorMsg)
+    }
+
+    return { theme: getCSSVariableReferences(themes.default) }
+  }
+)

package/spark-theme/index.stories.mdx

@@ -0,0 +1,98 @@
+import { Meta } from '@storybook/blocks'
+import { StoryHeading } from '@docs/helpers/StoryHeading'
+import { Alert } from '@docs/helpers/Alert'
+
+<Meta title="utils/Tailwind plugins/spark theme" />
+
+# Tailwind spark theme plugin
+
+## Installation
+
+To use our Tailwind spark theme plugin, simply install the `@spark-ui/tailwind-plugins` package and add the spark theme plugin to your `tailwind.config.js` file
+
+```bash
+$ npm i @spark-ui/tailwind-plugins
+```
+
+```js
+// tailwind.config.js
+
+const sparkPlugins = require('@spark-ui/tailwind-plugins')
+
+module.exports = {
+  ...,
+  plugins: [sparkPlugins.sparkTheme({
+    htmlFontSize: 16 // The base font size for your application (default: 16),
+    themes: {
+      default: yourDefaultTheme,
+      dark: yourDarkTheme,
+      foo: someOtherTheme,
+      ...rest
+    } //
+  })],
+}
+
+```
+
+<StoryHeading label="Usage" as="h2" />
+
+The plugin performs two main tasks:
+
+- first, it converts every value within the objects inside the themes object into **CSS variables**, which is helpful for managing **multiple themes**.
+
+- Second, it provides Tailwind with an internal mapping to retrieve these CSS variables This is necessary because, by default, Tailwind does not use CSS variables, but rather direct values.
+
+Once the plugin is configured, all Spark custom classes become available for use.
+
+```tsx
+<div className="bg-primary text-primary...">...</div>
+```
+
+<StoryHeading label="Configuration" as="h2" />
+
+This plugin can be customized by providing a configuration object with two fields, `themes` and `htmlFontSize`.
+
+**themes**:
+
+An object containing your themes. Each key in the object will be extracted to a `[data-theme]` attribute, and the values will be converted to CSS custom properties inside the `css` file generated by Tailwing. **Note that this object requires a key with a value of default**, which specifies the default theme for your project.
+
+For example, if your `themes` object looks like this:
+
+```js
+
+sparkPlugins.sparkTheme({
+  themes: {
+    default: yourDefaultTheme,
+    alternative: someAlternativeTheme,
+  },
+}),
+```
+
+Tailwind will generate the following CSS:
+
+```css
+:root {
+  /* ...tokens from yourDefaultTheme */
+}
+
+[data-theme='alternative'] {
+  /* ...tokens from someAlternativeTheme */
+}
+```
+
+You can populate the `themes` object with as many themes as desired, with the only requirement being that they conform to our `Theme` interface. The Theme interface can be accessed through the [**@spark-ui/theme-utils**](?path=/docs/utils-theme--docs#theme) package.
+
+**htmlFontSize (optional)**:
+
+Spark uses a base font size of **16 pixels** as a standard value for calculating the sizes of all other font-related properties defined in the theme. For example, our `spacing.lg` value is defined as **1rem**, which is equal to 16 pixels (based on the default base font size of 16 pixels).
+
+However, if your application uses a different base font size, such as **10 pixels** for example, this can cause issues with the sizing of elements in the application. To account for this, you can set the `htmlFontSize` to the appropriate value for your application's base font size. This will adjust the `rem` based values in Spark to be relative to the new base font size.
+
+This will ensure that the `rem`-based values are accurately calculated according to your application's HTML font size.
+
+<Alert>
+To better understand what happens when you adjust `htmlFontSize`, it's useful to know that we use CSS custom properties to define the values of our design tokens, such as `spacing.lg`.
+
+By default, the value for this token is expressed as `--spacing-lg: 1rem;`. However, when you define a `htmlFontSize` of 10, for example, this value will be updated to `--spacing-lg: 1.6rem;`
+
+</Alert>

package/spark-theme/utils.js

@@ -0,0 +1,83 @@
+function isObject(x) {
+  return !!x && x.constructor === Object
+}
+
+function isStringOrNumber(value) {
+  return typeof value === 'string' || typeof value === 'number'
+}
+
+function isHex(value) {
+  if (typeof value === 'number') {
+    return false
+  }
+
+  const regexp = /^#[0-9a-fA-F]+$/
+
+  return regexp.test(value)
+}
+
+function isAlphanumericWithLeadingLetter(v) {
+  return /^[a-zA-Z](?=.*\d)[a-zA-Z\d]*$/.test(v)
+}
+
+function isCamelCase(value) {
+  return /[A-Z]/.test(value.slice(1))
+}
+
+function hasNumber(value) {
+  return /\d/.test(value)
+}
+
+function getRemEquivalentValue(remValue, htmlFontSize) {
+  const defaultBrowserBase = 16
+  const pxValue = parseFloat(remValue) * defaultBrowserBase
+
+  return `${pxValue / htmlFontSize}rem`
+}
+
+function toKebabCase(v) {
+  return v.replace(/[A-Z]+(?=[a-z0-9])|\d+/g, match => '-' + match.toLowerCase())
+}
+
+const doubleHyphensRegex = /(?<!var\()--+/g
+
+function getAllObjectKeys(obj, path = '') {
+  return Object.keys(obj).flatMap(key => {
+    const newPath = path ? `${path}.${key}` : key
+    if (isObject(obj[key])) {
+      return getAllObjectKeys(obj[key], newPath)
+    }
+
+    return newPath
+  })
+}
+
+function difference(as, bs) {
+  const set = new Set(bs)
+
+  return as.filter(a => !set.has(a))
+}
+
+function retrieveArrayDifferences({ ref, comp }) {
+  const additionalItems = difference(comp, ref)
+  const missingItems = difference(ref, comp)
+
+  return {
+    additionalItems,
+    missingItems,
+  }
+}
+
+module.exports = {
+  isObject,
+  isStringOrNumber,
+  isHex,
+  isAlphanumericWithLeadingLetter,
+  isCamelCase,
+  hasNumber,
+  getRemEquivalentValue,
+  toKebabCase,
+  doubleHyphensRegex,
+  getAllObjectKeys,
+  retrieveArrayDifferences,
+}