Merge pull request #94 from studiometa/feature/custom-container-plugin

[Feature] Custom container plugin

packages/docs/.vuepress/config.js

@@ -18,6 +18,7 @@ module.exports = {
           { text: 'Breakpoint', link: '/plugins/breakpoint.html' },
           { text: 'Font-Face', link: '/plugins/font-face.html' },
           { text: 'Grid', link: '/plugins/grid.html' },
+          { text: 'Custom container', link: '/plugins/custom-container.html' },
           { text: 'Variants factory', link: '/plugins/variants-factory.html' },
           { text: 'Typography', link: '/plugins/typography.html' },
         ],

packages/docs/configuration/readme.md

@@ -16,22 +16,25 @@ Discover the [full config reference](./reference.md) for a quick overview of wha
 
 ## Theme
 
-### Container
+### Custom container
 
-The core container plugin is centered by default.
+The [container core plugin](https://tailwindcss.com/docs/container) is disabled and the [custom container plugin](/plugins/custom-container.html) has the following defaults:
 
-```js{3-5}
+```js{3-7}
 module.exports = {
   theme: {
-    container: {
+    customContainer: {
       center: true,
+      padding: '1rem',
+      maxWidth: '80rem',
     },
   },
+  corePlugins: {
+    container: false,
+  },
 };
 ```
 
-[Documentation](https://tailwindcss.com/docs/container#centering-by-default)
-
 ### Screens
 
 ```js{3-10}
@@ -137,7 +140,7 @@ module.exports = {
 
 ### Grid
 
-The [grid plugin](#grid-2) has the following defaults:
+The [grid plugin](/plugins/grid.html) has the following defaults:
 
 ```js{3-10}
 module.exports = {
@@ -160,6 +163,7 @@ module.exports = {
 - [Breakpoint](/plugins/breakpoint.html) to exposes the `screens` configuration in the CSS
 - [Font-Face](/plugins/font-face.html) to easily add custom `@font-face` declarations
 - [Grid](/plugins/grid.html) to add some grid classes
+- [Custom container](/plugins/custom-container.html) to add custom container classes
 - [Variants Factory](/plugins/variants-factory.html) to add custom variants on the go
 - [Typography](/plugins/typography.html) to improve the typography utilities
 

packages/docs/plugins/custom-container.md

@@ -0,0 +1,101 @@
+---
+sidebar: auto
+prev: ./grid.html
+next: ./variants-factory.html
+---
+
+# Custom container
+
+The custom container plugin creates component classes `container` and `container-reset` to override the default [container core plugin](https://tailwindcss.com/docs/container).
+
+## Usage
+
+You can use all the Tailwind variants to control the display of the container. Here's an example with the [responsive variants](https://tailwindcss.com/docs/responsive-design) to enable the container only for the breakpoints `s, l, xl, xxl` and disable it for the breakpoints `xxs, xs and m`:
+
+```html
+<div class="s:container m:container-reset l:container">
+  ...
+</div>
+```
+
+## Configuration
+
+The [container core plugin](https://tailwindcss.com/docs/container) is disabled and the plugin can be configured with the `theme.customContainer` property:
+
+```js{3-7}
+module.exports = {
+  theme: {
+    customContainer: {
+      center: true,
+      padding: '1rem',
+      maxWidth: '80rem',
+    },
+  },
+};
+```
+
+::: tip
+You should set the custom container properties with the `theme.extend` property to not override these defaults.
+:::
+
+### `center`
+
+- Type: `Boolean`
+- Default: `true`
+
+Set right and left margins to `auto` if enabled.
+
+### `padding`
+
+- Type: `[ String, Object ]`
+- Default: `'1rem'`
+
+Set right and left paddings. You can use an object to make this setting responsive. ([Learn how](#responsive-configuration))
+
+### `maxWidth`
+
+- Type: `[ String, Object ]`
+- Default: `'80rem'`
+
+Set the max width of the container. You can use an object to make this setting responsive. ([Learn how](#responsive-configuration))
+
+## Responsive configuration
+
+`padding` and `maxWidth` properties are responsive if defined using objects like this:
+
+```js{5-12}
+module.exports = {
+  theme: {
+    extend: {
+      customContainer: {
+        padding: {
+          DEFAULT: '1rem',
+          m: '2rem',
+        },
+        maxWidth: {
+          DEFAULT: '80rem',
+          xxl: '94rem',
+        },
+      },
+    }
+  },
+};
+```
+
+## Use the container core plugin
+
+You need to disable the custom container plugin and enable the core plugin:
+
+```js{3,8-10}
+module.exports = {
+  theme: {
+    customContainer: false,
+    container: {
+      center: true,
+    },
+  },
+  corePlugins: {
+    container: true,
+  },
+};
+```

packages/docs/plugins/grid.md

@@ -1,7 +1,7 @@
 ---
 sidebar: auto
 prev: ./font-face.html
-next: ./variants-factory.html
+next: ./custom-container.html
 ---
 
 # Grid

packages/docs/plugins/variants-factory.md

@@ -1,6 +1,6 @@
 ---
 sidebar: auto
-prev: ./grid.html
+prev: ./custom-container.html
 next: ./typography.html
 ---
 

packages/tailwind-config/index.js

@@ -32,8 +32,10 @@ const config = {
     /**
      * Container
      */
-    container: {
+    customContainer: {
       center: true,
+      padding: '1rem',
+      maxWidth: '80rem',
     },
 
     /**
@@ -125,6 +127,7 @@ const config = {
   },
   plugins: [
     require('./plugins/breakpoint'),
+    require('./plugins/custom-container'),
     require('./plugins/grid')(),
     require('./plugins/font-face')(),
     require('./plugins/font-smoothing'),
@@ -138,6 +141,9 @@ const config = {
       componentPrefix: 'type-',
     }),
   ],
+  corePlugins: {
+    container: false,
+  },
 };
 
 module.exports = {

packages/tailwind-config/plugins/custom-container.js

@@ -0,0 +1,74 @@
+const plugin = require('tailwindcss/plugin');
+
+/**
+ * is Object ?
+ * @param {*} value
+ */
+const isObject = (value) =>
+  typeof value === 'object' && !!value && value.toString() === '[object Object]';
+
+module.exports = plugin(({ addUtilities, theme }) => {
+  const config = theme('customContainer');
+  if (!config) {
+    return;
+  }
+
+  const allowedConfigProperties = [
+    'width',
+    'maxWidth',
+    'marginRight',
+    'marginLeft',
+    'paddingRight',
+    'paddingLeft',
+  ];
+
+  const containerDefault = {
+    width: '100%',
+  };
+
+  const containerMediaQueries = {};
+
+  if (config.center) {
+    config.marginRight = 'auto';
+    config.marginLeft = 'auto';
+    delete config.center;
+  }
+
+  if (config.padding) {
+    config.paddingRight = config.padding;
+    config.paddingLeft = config.padding;
+    delete config.padding;
+  }
+
+  Object.entries(config)
+    .filter(([propertyName]) => allowedConfigProperties.includes(propertyName))
+    .forEach(([propertyName, propertyValue]) => {
+      if (!isObject(propertyValue)) {
+        containerDefault[propertyName] = propertyValue;
+        return;
+      }
+
+      Object.entries(propertyValue).forEach(
+        ([breakpointName, propertyValueForCurrentBreakpoint]) => {
+          if (breakpointName === 'DEFAULT') {
+            containerDefault[propertyName] = propertyValueForCurrentBreakpoint;
+            return;
+          }
+
+          if (!containerMediaQueries[`@screen ${breakpointName}`]) {
+            containerMediaQueries[`@screen ${breakpointName}`] = {};
+          }
+
+          containerMediaQueries[`@screen ${breakpointName}`][propertyName] =
+            propertyValueForCurrentBreakpoint;
+        }
+      );
+    });
+
+  const container = { ...containerDefault, ...containerMediaQueries };
+
+  addUtilities({
+    '.container': container,
+    '.container-reset': Object.fromEntries(Object.keys(container).map((key) => [key, 'unset'])),
+  });
+});

packages/tests/index.html

@@ -9,3 +9,5 @@
 <div class="type-title"></div>
 <div class="type-body"></div>
 <div class="type-does-not-exists"></div>
+
+<div class="s:container m:container-reset xl:container"></div>

packages/tests/tailwind.config.js

@@ -29,5 +29,17 @@ module.exports = {
         letterSpacing: '1px',
       },
     }),
+    extend: {
+      customContainer: {
+        padding: {
+          DEFAULT: '1rem',
+          m: '2rem',
+        },
+        maxWidth: {
+          DEFAULT: '80rem',
+          xxl: '94rem',
+        },
+      },
+    },
   },
 };