Add o-container__fill elements (#1491)

Author: tylersticka

.changeset/early-carrots-appear.md

@@ -0,0 +1,5 @@
+---
+'@cloudfour/patterns': minor
+---
+
+Add `o-container__fill` and `o-container__fill-pad` elements for content intended to stretch into inline container padding

src/mixins/_fluid.scss

@@ -108,6 +108,23 @@
   }
 }
 
+@mixin margin-inline($min-width, $max-width, $min, $max, $include-min: true) {
+  @if $include-min {
+    margin-inline-end: $min;
+    margin-inline-start: $min;
+  }
+
+  @media (min-width: $min-width) {
+    margin-inline-end: fluid-calc($min-width, $max-width, $min, $max);
+    margin-inline-start: fluid-calc($min-width, $max-width, $min, $max);
+  }
+
+  @media (min-width: $max-width) {
+    margin-inline-end: $max;
+    margin-inline-start: $max;
+  }
+}
+
 @mixin padding($min-width, $max-width, $min, $max, $include-min: true) {
   @if $include-min {
     padding: $min;

src/objects/container/container.scss

@@ -62,3 +62,60 @@ $pad-max: size.$padding-container-max;
     max-width: size.$max-width-prose;
   }
 }
+
+/**
+ * Child elements intended to "fill" the container width. This negates any
+ * inline padding and border radii.
+ */
+
+.o-container__fill,
+.o-container__fill-pad {
+  .o-container--pad &,
+  .o-container--pad-inline & {
+    @include fluid.margin-inline(
+      $pad-breakpoint-min,
+      $pad-breakpoint-max,
+      $pad-min * -1,
+      $pad-max * -1
+    );
+  }
+
+  .o-container--pad:not(.o-container--prose) &,
+  .o-container--pad-inline:not(.o-container--prose) & {
+    // Magic number corresponds to approximate size of fluid padding in addition
+    // to max width container without fluid font size applied (attempts to boil
+    // this down to a repeatable equation resulted in my head exploding). If we
+    // only tested by the max width, the rounded corners would be restored too
+    // early (before there was visible whitespace to either side).
+    @media (width < (size.$max-width-spread + 25em)) {
+      border-radius: 0;
+    }
+  }
+
+  .o-container--pad.o-container--prose &,
+  .o-container--pad-inline.o-container--prose & {
+    // See previous comment about magic number
+    @media (width < (size.$max-width-prose + 7em)) {
+      border-radius: 0;
+    }
+  }
+}
+
+/**
+ * The `__fill-pad` element differs from the `__fill` element in that it
+ * restores the parent element's padding (if any). This may be useful for cards
+ * and theme containers with inner content that wouldn't align with what was
+ * adjacent otherwise.
+ */
+
+.o-container__fill-pad {
+  .o-container--pad &,
+  .o-container--pad-inline & {
+    @include fluid.padding-inline(
+      $pad-breakpoint-min,
+      $pad-breakpoint-max,
+      $pad-min,
+      $pad-max
+    );
+  }
+}

src/objects/container/container.stories.mdx

@@ -1,5 +1,16 @@
-import { Story, Canvas, Meta } from '@storybook/addon-docs/blocks';
+import { Story, Canvas, Meta } from '@storybook/addon-docs';
 import basicDemo from './demo/basic.twig';
+// The '!!raw-loader!' syntax is a non-standard, Webpack-specific, syntax.
+// See: https://github.com/webpack-contrib/raw-loader#examples
+// For now, it seems likely Storybook is pretty tied to Webpack, therefore, we
+// are okay with the following Webpack-specific raw loader syntax. It's better
+// to leave the ESLint rule enabled globally, and only thoughtfully disable as
+// needed (e.g. within a Storybook docs page and not within an actual
+// component). This can be revisited in the future if Storybook no longer relies
+// on Webpack.
+// eslint-disable-next-line @cloudfour/import/no-webpack-loader-syntax
+import fillDemoSource from '!!raw-loader!./demo/fill.twig';
+import fillDemo from './demo/fill.twig';
 const basicDemoStory = (args) => {
   const modifiers = [];
   if (args.prose) {
@@ -24,7 +35,11 @@ embedded examples.
 
 <Meta
   title="Objects/Container"
-  parameters={{ docs: { inlineStories: false }, paddings: { disable: true } }}
+  parameters={{
+    layout: 'fullscreen',
+    docs: { inlineStories: false },
+    paddings: { disable: true },
+  }}
   argTypes={{
     prose: {
       control: {
@@ -117,3 +132,23 @@ Modifiers may be added to apply a consistent amount of responsive padding to con
 - `o-container--pad-inline`: Adds horizontal padding.
 
 Custom padding amounts may be applied through the use of [padding utilities](/docs/utilities-spacing--padding).
+
+## Fill
+
+There are times when a child element should attempt to fill the container content width, including padding. This can highlight visual elements (images and embeds) and align content within containers.
+
+Two child element classes exist for this purpose:
+
+- `o-container__fill`: Negates any inline padding so the element will reach the edges of the content container's padding.
+- `o-container__fill-pad`: Also applies padding to the element so its content will align with that of the container.
+
+<Canvas>
+  <Story
+    name="Fill"
+    height="500px"
+    argTypes={{}}
+    parameters={{ docs: { source: { code: fillDemoSource } } }}
+  >
+    {fillDemo.bind({})}
+  </Story>
+</Canvas>

src/objects/container/demo/fill.twig

@@ -0,0 +1,34 @@
+{% embed '@cloudfour/objects/container/container.twig' with {
+  class: 'o-container--prose o-container--pad'
+} only %}
+  {% block content %}
+    {% embed '@cloudfour/objects/rhythm/rhythm.twig' only %}
+      {% block content %}
+        <p>This card simply fills the content element:</p>
+        {% embed '@cloudfour/components/card/card.twig' with {
+          class: 'c-card--contained'
+        } only %}
+          {% block content %}
+            <p>.c-card.c-card--contained</p>
+          {% endblock %}
+        {% endembed %}
+        <p>This card attempts to fill the container, padding included:</p>
+        {% embed '@cloudfour/components/card/card.twig' with {
+          class: 'c-card--contained o-container__fill'
+        } only %}
+          {% block content %}
+            <p>.c-card.c-card--contained.o-container__fill</p>
+          {% endblock %}
+        {% endembed %}
+        <p>This card fills the container and applies padding to align its content with adjacent elements:</p>
+        {% embed '@cloudfour/components/card/card.twig' with {
+          class: 'c-card--contained o-container__fill-pad'
+        } only %}
+          {% block content %}
+            <p>.c-card.c-card--contained.o-container__fill-pad</p>
+          {% endblock %}
+        {% endembed %}
+      {% endblock %}
+    {% endembed %}
+  {% endblock %}
+{% endembed %}