tailwind-clamp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nicolas Cusan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# Tailwind clamp
+
+Tailwind CSS utilities & plugin to use CSS `clamp` in your project. Enabling fluid interfaces using Tailwind syntax.
+
+The plugin is based on the formula presented in this [article](https://chriskirknielsen.com/blog/modern-fluid-typography-with-clamp/)
+
+## Features
+
+- Clamp values between a min and max viewport width, making it grow / shrink with the viewport.
+- Possibility to use small to large, large to small, negative to positive, positive to negative and negative to negative values. (Negative values only work on properties that allow them, e.g. `margin`)
+- Helper functions to simplify the definition of clamped values in your config.
+- Tailwind plugin to allow the usage of arbitrary values using the `clamp-[...]` syntax.
+- Values are interpreted as pixels and output as `rem`
+
+## Installation
+
+Install the plugin from npm:
+
+```sh
+npm install nicolas-cusan/tailwind-clamp
+```
+
+## Usage
+
+### Predefine values in your config
+
+The package provides two helper functions to help you define "clamped" values in your config:
+
+#### `clamp(start, end, [minViewportWidth=375, maxViewportWidth=1440])`
+
+##### Arguments
+
+- `start` `{number}`: Value at `minViewportWidth` viewport size. The value is interpreted as pixels and outputted as `rem` in the generated CSS.
+- `end` `{number}`: Value at `maxViewportWidth` viewport size. The value is interpreted as pixels and outputted as `rem` in the generated CSS.
+- `[minViewportWidth=375]` `{number}`: Viewport size, where the clamp starts, defaults to `375`. The value is interpreted as pixels. Value should be smaller than `maxViewportWidth`.
+- `[maxViewportWidth=1440]` `{number}`: Viewport size, where the clamp stops, defaults to `1440` The value is interpreted as pixels. Value should be smaller than `minViewportWidth`.
+
+#### `clampFs(start, end, [tracking=null, minViewportWidth=375, maxViewportWidth=1440])`
+
+##### Arguments
+
+- `start` `{[fontSize: number, lineHeight: number]}`: Array of two numbers: `font-size` and `line-height` respectively at `minViewportWidth` viewport size. Both values are interpreted as pixels and outputted as `rem` in the generated CSS.
+- `end` `{[fontSize: number, lineHeight: number]}`: Array of two numbers: `font-size` and `line-height` respectively at `maxViewportWidth` viewport size. Both values are interpreted as pixels and outputted as `rem` in the generated CSS.
+- `[tracking=null]` `{string|null}`: `letter-spacing` setting, it is recommended to use the `em` unit as it proportional to the font size, e.g. `-0.01em`
+- `[minViewportWidth=375]` `{number}`: Viewport size, where the clamp starts, defaults to `375`. The value is interpreted as pixels. Value should be smaller than `maxViewportWidth`.
+- `[maxViewportWidth=1440]` `{number}`: Viewport size, where the clamp stops, defaults to `1440` The value is interpreted as pixels. Value should be smaller than `minViewportWidth`.
+
+```js
+// tailwind.config.js
+const { setupClamp } = require('../src/utils.js');
+
+const clampOptions = {
+  minViewportWidth: 375,
+  maxViewportWidth: 1440,
+};
+
+// Setup the clamp helper functions with the default min and max viewport sizes you want to use
+const { clamp, clampFs } = setupClamp(options);
+
+module.exports = {
+  theme: {
+    // ...
+    extend: {
+      spacing: {
+        // Use
+        grid: clamp(10, 20),
+      },
+
+      fontSize: {
+        base: clampFs([16, 20], [24, 28], '-0.01em'),
+      },
+    },
+  },
+  // ...
+};
+```
+
+### Use the plugin with `clamp-[...]`
+
+The package also provides a plugin to use arbitrary values via the `clamp-[...]` syntax.
+
+```js
+// tailwind.config.js
+const clampOptions = {
+  minViewportWidth: 375,
+  maxViewportWidth: 1440,
+};
+
+module.exports = {
+  theme: {
+    // ...
+  },
+  plugins: [
+    require('tailwind-clamp')(clampOptions),
+    // ...
+  ],
+};
+```
+
+#### Configuration
+
+This plugin allows two configuration options:
+
+| Name               | Description                          | Default value |
+| ------------------ | ------------------------------------ | ------------- |
+| `minViewportWidth` | Viewport size where the clamp starts | `375`         |
+| `maxViewportWidth` | Viewport size where the clamp end    | `1440`        |
+
+#### Using the plugin
+
+The arbitrary values syntax for clamp requires at least three arguments separated by commas without whitespace:
+
+#### `clamp-[<property>,<start>,<end>,[minViewportWidth,maxViewportWidth]]`
+
+##### Arguments
+
+- `property` `{string}`: Property that the value should be applied to. See a list of all supported properties below.
+- `start` `{number}`: Value at `minViewportWidth` viewport size. The value is interpreted as pixels and output as `rem` in the generated CSS.
+- `end` `{number}`: Value at `maxViewportWidth` viewport size. The value is interpreted as pixels and output as `rem` in the generated CSS.
+- `[minViewportWidth=375]` `{number}`: Viewport size, where the clamp starts, defaults to `375`. The value is interpreted as pixels. Value should be smaller than `maxViewportWidth`.
+- `[maxViewportWidth=1440]` `{number}`: Viewport size, where the clamp stops, defaults to `1440` The value is interpreted as pixels. Value should be smaller than `minViewportWidth`.
+
+##### Example
+
+```html
+<div class="clamp-[px,20,40] clamp-[py,10,18]">
+  Add some fluid padding here.
+</div>
+```
+
+##### Supported properties
+
+- `p` including `pt`, `pb`, `pl`, `pr`, `px`, `py`.
+- `m` including `mt`, `mb`, `ml`, `mr`, `mx`, `my`.
+- `inset`
+- `top`
+- `left`
+- `right`
+- `bottom`
+- `text` applied to `font-size`.
+- `gap` including `gap-x`, `gap-y`.
+- `w`
+- `h`
+- `size`
+- `min-w`
+- `min-h`
+- `max-w`
+- `max-h`
+- `rounded` including `rounded-t`, `rounded-r`, `rounded-b`, `rounded-l`, `rounded-tl`, `rounded-tr`, `rounded-bl`, `rounded-br`.
+- `translate-x`
+- `translate-y`
+- `text-stroke`
+- `stroke`
+- `leading`
+- `border` including `border-t`, `border-b`, `border-l`, `border-r`, `border-x`, `border-y`.
+- `scroll-m`
+
+## Roadmap
+
+- Support other units e.g `%`
+- Support directional properties e.g. `ps`
+- Add showcase

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "tailwind-clamp",
+  "version": "1.0.0",
+  "description": "Tailwind CSS plugin to use CSS clamp in your projects",
+  "main": "src/index.js",
+  "scripts": {
+    "dev": "next dev demo",
+    "build": "next build demo",
+    "start": "next start demo",
+    "lint": "next lint demo"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nicolas-cusan/tailwind-clamp.git"
+  },
+  "keywords": [
+    "tailwind",
+    "css",
+    "clamp"
+  ],
+  "author": "Nicolas Cusan",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/nicolas-cusan/tailwind-clamp/issues"
+  },
+  "homepage": "https://github.com/nicolas-cusan/tailwind-clamp#readme",
+  "dependencies": {
+    "react": "^18",
+    "react-dom": "^18",
+    "next": "14.1.4"
+  },
+  "devDependencies": {
+    "autoprefixer": "^10.0.1",
+    "postcss": "^8",
+    "tailwindcss": "^3.3.0"
+  }
+}

package/src/index.js

@@ -0,0 +1,291 @@
+const plugin = require('tailwindcss/plugin');
+const { clamp } = require('./utils.js');
+
+let cssTransformValue = [
+  'translate(var(--tw-translate-x), var(--tw-translate-y))',
+  'rotate(var(--tw-rotate))',
+  'skewX(var(--tw-skew-x))',
+  'skewY(var(--tw-skew-y))',
+  'scaleX(var(--tw-scale-x))',
+  'scaleY(var(--tw-scale-y))',
+].join(' ');
+
+function resolveProperty(property, value) {
+  switch (property) {
+    case 'p':
+      return {
+        padding: value,
+      };
+    case 'pt':
+      return {
+        paddingTop: value,
+      };
+    case 'pb':
+      return {
+        paddingBottom: value,
+      };
+    case 'pl':
+      return {
+        paddingLeft: value,
+      };
+    case 'pr':
+      return {
+        paddingRight: value,
+      };
+    case 'px':
+      return {
+        paddingLeft: value,
+        paddingRight: value,
+      };
+    case 'py':
+      return {
+        paddingTop: value,
+        paddingBottom: value,
+      };
+    case 'm':
+      return {
+        margin: value,
+      };
+    case 'mt':
+      return {
+        marginTop: value,
+      };
+    case 'mb':
+      return {
+        marginBottom: value,
+      };
+    case 'ml':
+      return {
+        marginLeft: value,
+      };
+    case 'mr':
+      return {
+        marginRight: value,
+      };
+    case 'mx':
+      return {
+        marginLeft: value,
+        marginRight: value,
+      };
+    case 'my':
+      return {
+        marginTop: value,
+        marginBottom: value,
+      };
+    case 'inset':
+      return {
+        top: value,
+        left: value,
+        right: value,
+        bottom: value,
+      };
+    case 'top':
+      return {
+        top: value,
+      };
+    case 'left':
+      return {
+        left: value,
+      };
+    case 'right':
+      return {
+        right: value,
+      };
+    case 'bottom':
+      return {
+        bottom: value,
+      };
+    case 'text':
+      return {
+        fontSize: value,
+      };
+    case 'gap':
+      return {
+        gap: value,
+      };
+    case 'gap-x':
+      return {
+        columnGap: value,
+      };
+    case 'gap-y':
+      return {
+        rowGap: value,
+      };
+    case 'w':
+      return {
+        width: value,
+      };
+    case 'h':
+      return {
+        height: value,
+      };
+    case 'size':
+      return {
+        width: value,
+        height: value,
+      };
+    case 'min-w':
+      return {
+        minWidth: value,
+      };
+    case 'min-h':
+      return {
+        minHeight: value,
+      };
+    case 'max-w':
+      return {
+        maxWidth: value,
+      };
+    case 'max-h':
+      return {
+        maxHeight: value,
+      };
+    case 'rounded':
+      return {
+        borderRadius: value,
+      };
+    case 'rounded-t':
+      return {
+        borderTopLeftRadius: value,
+        borderTopRightRadius: value,
+      };
+    case 'rounded-r':
+      return {
+        borderTopRightRadius: value,
+        borderBottomRightRadius: value,
+      };
+    case 'rounded-b':
+      return {
+        borderBottomLeftRadius: value,
+        borderBottomRightRadius: value,
+      };
+    case 'rounded-l':
+      return {
+        borderTopLeftRadius: value,
+        borderBottomLeftRadius: value,
+      };
+    case 'rounded-tl':
+      return {
+        borderTopLeftRadius: value,
+      };
+    case 'rounded-tr':
+      return {
+        borderTopRightRadius: value,
+      };
+    case 'rounded-bl':
+      return {
+        borderBottomLeftRadius: value,
+      };
+    case 'rounded-br':
+      return {
+        borderBottomRightRadius: value,
+      };
+    case 'translate-x':
+      return {
+        '--tw-translate-x': value,
+        '@defaults transform': {},
+        transform: cssTransformValue,
+      };
+    case 'translate-y':
+      return {
+        '--tw-translate-y': value,
+        '@defaults transform': {},
+        transform: cssTransformValue,
+      };
+    case 'text-stroke':
+      return {
+        '-webkit-text-stroke': value,
+        textStroke: value,
+      };
+    case 'stroke':
+      return {
+        strokeWidth: value,
+      };
+    case 'leading':
+      return {
+        lineHeight: value,
+      };
+    case 'border':
+      return {
+        borderWidth: value,
+      };
+    case 'border-t':
+      return {
+        borderTopWidth: value,
+      };
+    case 'border-b':
+      return {
+        borderBottomWidth: value,
+      };
+    case 'border-l':
+      return {
+        borderLeftWidth: value,
+      };
+    case 'border-r':
+      return {
+        borderRightWidth: value,
+      };
+    case 'border-x':
+      return {
+        borderLeftWidth: value,
+        borderRightWidth: value,
+      };
+    case 'border-y':
+      return {
+        borderTopWidth: value,
+        borderBottomWidth: value,
+      };
+    case 'scroll-m':
+      return {
+        scrollMargin: value,
+      };
+    default:
+      return null;
+  }
+}
+
+module.exports = plugin.withOptions(function (
+  options = {
+    minViewportWidth: 375,
+    maxViewportWidth: 1440,
+  }
+) {
+  return function ({ matchUtilities, theme }) {
+    matchUtilities(
+      {
+        clamp: (value) => {
+          const props = value.split(',');
+          props[1] = parseFloat(props[1]);
+          props[2] = parseFloat(props[2]);
+
+          if (props.length < 3) {
+            throw new Error('The clamp utility requires at least 3 arguments.');
+          }
+
+          if (typeof props[1] !== 'number' || typeof props[2] !== 'number') {
+            throw new Error(
+              'The clamp utility requires that the second and third arguments are numbers representing a pixel value.'
+            );
+          }
+
+          const prop = resolveProperty(
+            props[0],
+            clamp(
+              props[1],
+              props[2],
+              props[3] || options.minViewportWidth,
+              props[4] || options.maxViewportWidth
+            )
+          );
+
+          if (prop === null) {
+            throw new Error(`Property "${props[0]}" is not supported.`);
+          }
+
+          return prop;
+        },
+      },
+      { values: theme('clamp') }
+    );
+  };
+});

package/src/utils.js

@@ -0,0 +1,82 @@
+// https://chriskirknielsen.com/blog/modern-fluid-typography-with-clamp/
+
+const clamp = (_start, _end, minvw = 375, maxvw = 1440) => {
+  let start = _start;
+  let end = _end;
+  let negative = false;
+
+  if (_end < _start && _start < 0 && _end < 0) {
+    start = Math.abs(_start);
+    end = Math.abs(_end);
+    negative = true;
+  } else if (_end < _start && _start > 0 && _end > 0) {
+    start = _start * -1;
+    end = _end * -1;
+    negative = true;
+  } else if (_end < _start) {
+    start = Math.abs(_start) * -1;
+    end = Math.abs(_end);
+    negative = true;
+  }
+
+  const rem = (px) => `${px / 16}rem`;
+  const factor = (1 / (maxvw - minvw)) * (end - start);
+  const calc = `${rem(start - minvw * factor)} + ${100 * factor}vw`;
+
+  const value = `clamp(${rem(start)}, ${calc}, ${rem(end)})`;
+
+  return negative ? `calc(${value} * -1)` : value;
+};
+
+const clampFs = (start, end, tracking = null, minvw = 375, maxvw = 1440) => {
+  const [startFs, startLh] = start;
+  const [endFs, endLh] = end;
+
+  const sameLh =
+    (startFs == startLh && endFs === endLh) ||
+    startLh / startFs === endLh / endFs;
+
+  const settings = [
+    clamp(startFs, endFs, minvw, maxvw),
+    {
+      lineHeight: sameLh
+        ? startLh / startFs
+        : clamp(startLh, endLh, minvw, maxvw),
+    },
+  ];
+
+  if (tracking) {
+    settings[1].letterSpacing = tracking;
+  }
+
+  return settings;
+};
+
+const setupClamp = (
+  options = {
+    minViewportWidth: 375,
+    maxViewportWidth: 1440,
+  }
+) => {
+  return {
+    clamp: (
+      start,
+      end,
+      minvw = options.minViewportWidth,
+      maxvw = options.maxViewportWidth
+    ) => clamp(start, end, minvw, maxvw),
+    clampFs: (
+      start,
+      end,
+      tracking = null,
+      minvw = options.minViewportWidth,
+      maxvw = options.maxViewportWidth
+    ) => clampFs(start, end, tracking, minvw, maxvw),
+  };
+};
+
+module.exports = {
+  clamp,
+  clampFs,
+  setupClamp,
+};