@spark-ui/tailwind-plugins 2.1.2 → 2.2.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.2.0](https://github.com/adevinta/spark/compare/@spark-ui/tailwind-plugins@2.1.3...@spark-ui/tailwind-plugins@2.2.0) (2023-03-21)
+
+### Features
+
+- **tailwind-plugins:** consolidate tw plugin calls and auto-apply options ([c203355](https://github.com/adevinta/spark/commit/c2033552976cc611172de2a14f6927be76522e41))
+
+## [2.1.3](https://github.com/adevinta/spark/compare/@spark-ui/tailwind-plugins@2.1.2...@spark-ui/tailwind-plugins@2.1.3) (2023-03-21)
+
+**Note:** Version bump only for package @spark-ui/tailwind-plugins
+
 ## [2.1.2](https://github.com/adevinta/spark/compare/@spark-ui/tailwind-plugins@2.1.1...@spark-ui/tailwind-plugins@2.1.2) (2023-03-20)
 
 ### Bug Fixes

package/animations/index.js

@@ -43,11 +43,9 @@ module.exports = plugin.withOptions(
    */
   options =>
     ({ addUtilities, addVariant, matchUtilities, theme }) => {
-      const opts = options || {
-        variantPrefix: 'sp-anime',
-      }
+      const opts = options || {}
 
-      const { variantPrefix } = opts
+      const { variantPrefix = 'sp-anime' } = opts
 
       matchUtilities(
         {

package/index.js

@@ -2,9 +2,32 @@
 const animations = require('./animations')
 const sizings = require('./sizings')
 const sparkTheme = require('./spark-theme')
+const tailwindcssRadix = require('tailwindcss-radix')
+
+/**
+ * @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.
+ */
+const sparkConfig = ({ htmlFontSize, themes }) => {
+  return [
+    sparkTheme({ htmlFontSize, themes }),
+    sizings({ htmlFontSize }),
+    animations(),
+    tailwindcssRadix({ variantPrefix: 'spark' }),
+  ]
+}
 
 module.exports = {
   animations,
   sizings,
   sparkTheme,
+  sparkConfig,
 }

package/index.stories.mdx

@@ -8,6 +8,7 @@ import { Alert } from '@docs/helpers/Alert'
 
 Below is a list of our Tailwind plugins:
 
+- [spark config](?path=/docs/utils-tailwind-plugins-spark-config--docs)
 - [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,13 +1,14 @@
 {
   "name": "@spark-ui/tailwind-plugins",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Spark Tailwind plugins",
   "publishConfig": {
     "access": "public"
   },
   "main": "index.js",
   "dependencies": {
-    "@spark-ui/theme-utils": "^2.9.1"
+    "@spark-ui/theme-utils": "^2.9.1",
+    "tailwindcss-radix": "^2.8.0"
   },
   "peerDependencies": {
     "tailwindcss": "^3.2.7"
@@ -17,5 +18,5 @@
     "url": "git@github.com:adevinta/spark.git",
     "directory": "packages/utils/tailwind-plugins"
   },
-  "gitHead": "6efd4ae4a8f830e228ba06081f8fd2a242e0f86a"
+  "gitHead": "5807dd41683a7e1196bc24311e7d7afcb43e2b47"
 }

package/sizings/index.js

@@ -46,11 +46,9 @@ module.exports = plugin.withOptions(
    */
   options =>
     ({ addBase }) => {
-      const opts = options || {
-        htmlFontSize: 16,
-      }
+      const opts = options || {}
 
-      const { htmlFontSize } = opts
+      const { htmlFontSize = 16 } = opts
 
       addBase({
         ':root': getCSSVariableDeclarations(htmlFontSize),

package/spark-config.stories.mdx

@@ -0,0 +1,136 @@
+import { Meta } from '@storybook/blocks'
+import { StoryHeading } from '@docs/helpers/StoryHeading'
+import { Alert } from '@docs/helpers/Alert'
+
+<Meta title="utils/Tailwind plugins/spark config" />
+
+# Tailwind spark config 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.sparkConfig({
+      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 streamlines the setup process by wrapping the call to all our other plugins (plus some external ones) with the appropriate options applied.
+
+This approach eliminates the need for manually calling each of our plugins. Here's a comparison:
+
+**without the plugin:**
+
+```js
+const sparkPlugins = require('@spark-ui/tailwind-plugins')
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ['./packages/**/*.{js,ts,jsx,tsx}', './documentation/**/*.{js,ts,jsx,tsx,mdx}'],
+  plugins: [
+    sparkPlugins.sparkTheme({
+      htmlFontSize: 10,
+      themes: {
+        default: themeUtils.defaultTheme,
+        dark: themeUtils.defaultThemeDark,
+      },
+    }),
+    sparkPlugins.sizings({ htmlFontSize: 10 }),
+    sparkPlugins.animations(),
+    ...
+  ],
+}
+```
+
+**with the plugin:**
+
+```js
+const sparkPlugins = require('@spark-ui/tailwind-plugins')
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: ['./packages/**/*.{js,ts,jsx,tsx}', './documentation/**/*.{js,ts,jsx,tsx,mdx}'],
+  plugins: [
+    ...sparkPlugins.sparkConfig({
+      htmlFontSize: 10,
+      themes: {
+        default: themeUtils.defaultTheme,
+        dark: themeUtils.defaultThemeDark,
+      },
+    }),
+  ],
+}
+```
+
+For more details about our other plugins, please refer to the [**Tailwind plugins documentation**](?path=/docs/utils-tailwind-plugins--docs).
+
+<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>