@spark-ui/tailwind-plugins 1.1.2 → 2.0.0

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [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,8 @@
-/* eslint-disable-next-line @typescript-eslint/no-var-requires */
+/* eslint-disable @typescript-eslint/no-var-requires */
 const animations = require('./animations')
+const sizings = require('./sizings')
 
 module.exports = {
   animations,
+  sizings,
 }

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,6 +1,6 @@
 {
   "name": "@spark-ui/tailwind-plugins",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "description": "Spark Tailwind plugins",
   "publishConfig": {
     "access": "public"
@@ -14,5 +14,5 @@
     "url": "git@github.com:adevinta/spark.git",
     "directory": "packages/utils/tailwind-plugins"
   },
-  "gitHead": "a1686f8fd79eee57d1515c6926d84c8e7c7f90a2"
+  "gitHead": "843a4c9ef31a1f346e4052685ccddceb494fc7bd"
 }

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.