@spark-ui/tailwind-plugins 1.1.2 → 2.1.0

package/CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [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
+
+- **tailwind-plugins:** add sizings plugin ([25f76ac](https://github.com/adevinta/spark/commit/25f76ac8ccdece9db718e80eb7fd54a951b4fc22)), closes [#401](https://github.com/adevinta/spark/issues/401)
+- use new Tailwind sizings plugin ([4cbb16a](https://github.com/adevinta/spark/commit/4cbb16a535ffc4c473c729337278dce0cfab3f51)), closes [#401](https://github.com/adevinta/spark/issues/401)
+
+### BREAKING CHANGES
+
+- **tailwind-plugins:** Add sizings plugin
+
 ## [1.1.2](https://github.com/adevinta/spark/compare/@spark-ui/tailwind-plugins@1.1.1...@spark-ui/tailwind-plugins@1.1.2) (2023-03-13)
 
 **Note:** Version bump only for package @spark-ui/tailwind-plugins

package/README.md

@@ -0,0 +1 @@
+The documentation for this package is located within our Storybook at https://sparkui.vercel.app/?path=/docs/utils-tailwind-plugins--docs.

package/{animation.stories.mdx → animations/index.stories.mdx}

@@ -6,7 +6,9 @@ import { Alert } from '@docs/helpers/Alert'
 
 # Tailwind animation plugin
 
-To use our Tailwind animation plugins, simply install the `@spark-ui/tailwind-plugins` package and add the animation plugin to your `tailwind.config.js` file
+## Installation
+
+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
 
 ```bash
 $ npm i @spark-ui/tailwind-plugins
@@ -19,11 +21,13 @@ const sparkPlugins = require('@spark-ui/tailwind-plugins')
 
 module.exports = {
   ...,
-  plugins: [sparkPlugins.animation()],
+  plugins: [sparkPlugins.animations()],
 }
 
 ```
 
+## Usage
+
 This plugin provides the following **animation-related** declaration properties that are missing by default in **Tailwind**:
 
 - **animation-fill-mode**: `sp-anime-fill-{value}` (where `value` can be `forwards`, `backwards`, or `none`)
@@ -43,7 +47,7 @@ This plugin also includes four animation keyframes:
 - **animate-slide-bottom**: `animate-slide-bottom`
 - **animate-slide-left**: `animate-slide-left`
 
-<StoryHeading label="plugin options" as="h3" />
+<StoryHeading label="Configuration" as="h3" />
 
 You can customize the **CSS class prefix** using the `prefixVariant` option.
 
@@ -56,7 +60,7 @@ const sparkPlugins = require('@spark-ui/tailwind-plugins')
 
 module.exports = {
   ...,
-  plugins: [sparkPlugins.animation({ prefixVariant: 'bar' })],
+  plugins: [sparkPlugins.animations({ prefixVariant: 'bar' })],
 }
 
 ```

package/index.js

@@ -1,6 +1,10 @@
-/* eslint-disable-next-line @typescript-eslint/no-var-requires */
+/* 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

@@ -0,0 +1,12 @@
+import { Meta } from '@storybook/blocks'
+import { StoryHeading } from '@docs/helpers/StoryHeading'
+import { Alert } from '@docs/helpers/Alert'
+
+<Meta title="utils/Tailwind plugins" />
+
+# Tailwind plugins
+
+Below is a list of our Tailwind plugins:
+
+- [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": "1.1.2",
+  "version": "2.1.0",
   "description": "Spark Tailwind plugins",
   "publishConfig": {
     "access": "public"
   },
   "main": "index.js",
+  "dependencies": {
+    "@spark-ui/theme-utils": "^2.9.0"
+  },
   "peerDependencies": {
     "tailwindcss": "4.0.0"
   },
@@ -14,5 +17,5 @@
     "url": "git@github.com:adevinta/spark.git",
     "directory": "packages/utils/tailwind-plugins"
   },
-  "gitHead": "a1686f8fd79eee57d1515c6926d84c8e7c7f90a2"
+  "gitHead": "b02d8de6793827cb8783dcf1029c7345c7629974"
 }

package/sizings/index.js

@@ -0,0 +1,70 @@
+/* eslint-disable-next-line @typescript-eslint/no-var-requires */
+const plugin = require('tailwindcss/plugin')
+
+const sizingRange = [
+  0, 1, 2, 4, 6, 8, 10, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 56, 64, 80, 96, 112, 128, 144,
+  160, 176, 192, 208, 224, 240, 256, 288, 320, 384, 400, 416, 432, 448, 464, 480, 512, 544, 576,
+  608, 640, 672, 704, 736, 768, 800, 832, 864,
+]
+
+function pxToRem(pxValue, htmlFontSize) {
+  const remValue = pxValue / htmlFontSize
+
+  return `${remValue}rem`
+}
+
+function getCSSVariableDeclarations(htmlFontSize) {
+  const CSSVariableDeclarations = sizingRange.reduce((acc, size) => {
+    acc[`--sz-${size}`] = pxToRem(size, htmlFontSize)
+
+    return acc
+  }, {})
+
+  return CSSVariableDeclarations
+}
+
+function getCSSVariableReferences() {
+  const CSSVariableReferences = sizingRange.reduce((acc, size) => {
+    acc[`sz-${size}`] = `var(--sz-${size})`
+
+    return acc
+  }, {})
+
+  return CSSVariableReferences
+}
+
+module.exports = plugin.withOptions(
+  /**
+   * @typedef {Object} Options
+   * @property {number} htmlFontSize The base font size of your app.
+   */
+
+  /**
+   * @param {Object} options The options for the plugin.
+   * @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 || {
+        htmlFontSize: 16,
+      }
+
+      const { htmlFontSize } = opts
+
+      addBase({
+        ':root': getCSSVariableDeclarations(htmlFontSize),
+      })
+    },
+  () => ({
+    theme: {
+      extend: {
+        width: getCSSVariableReferences(),
+        maxWidth: getCSSVariableReferences(),
+        height: getCSSVariableReferences(),
+        maxHeight: getCSSVariableReferences(),
+        translate: getCSSVariableReferences(),
+      },
+    },
+  })
+)

package/sizings/index.stories.mdx

@@ -0,0 +1,74 @@
+import { Meta } from '@storybook/blocks'
+import { StoryHeading } from '@docs/helpers/StoryHeading'
+import { Alert } from '@docs/helpers/Alert'
+
+<Meta title="utils/Tailwind plugins/sizings" />
+
+# Tailwind sizing plugin
+
+## Installation
+
+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
+
+```bash
+$ npm i @spark-ui/tailwind-plugins
+```
+
+```js
+// tailwind.config.js
+
+const sparkPlugins = require('@spark-ui/tailwind-plugins')
+
+module.exports = {
+  ...,
+  plugins: [sparkPlugins.sizings({ htmlFontSize: 16 // The base font size for your application (default: 16)
+  })],
+}
+
+```
+
+## Usage
+
+This plugin predefines a sizing range with the following pixel values:
+
+```ts
+const sizingRange = [
+  0, 1, 2, 4, 6, 8, 10, 12, 14, 16, 20, 24, 28, 32, 36, 40, 44, 48, 56, 64, 80, 96, 112, 128, 144,
+  160, 176, 192, 208, 224, 240, 256, 288, 320, 384, 400, 416, 432, 448, 464, 480, 512, 544, 576,
+  608, 640, 672, 704, 736, 768, 800, 832, 864,
+]
+```
+
+These values are converted into rem units based on the specified **HTML font size** (see [configuration](#configuration)).
+
+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" />
+
+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:
+
+```tsx
+<div className="w-sz-10">...</div>
+```
+
+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" />
+
+You can customize the **base html font size** using the `htmlFontSize` option.
+
+By default, the base will be `16`, but you can change it like so:
+
+```js
+// tailwind.config.js
+
+const sparkPlugins = require('@spark-ui/tailwind-plugins')
+
+module.exports = {
+  ...,
+  plugins: [sparkPlugins.sizings({ htmlFontSize: 10 })],
+}
+
+```
+
+This will ensure that the `rem`-based values are accurately calculated according to your application's HTML font size.

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/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,
+}