Container Query Utilities for Carbon Grid

[m4olivei]

Problem/Motivation

tldr;

Provide utilities, in the form of Sass mixins, to more easily author container queries targetting Carbon grid columns.

--verbose

Container queries enable you to apply styles to an element based on the size of the element's container [...] Container queries are an alternative to media queries, which apply styles to elements based on viewport size
MDN

In our work on the ibm.com marketing site, we have encountered multiple instances of designs that define component style variations in terms of the Carbon grid. For instance, on the ibm.com marketing site, we have full width 16 column layouts, and also so called "table of contents" (TOC) layouts. In TOC layouts, the main content occupies 12 columns and the TOC is sticky in the remaining 4 columns. We see requirements from design like:

When the component occupies the full width, at the lg breakpoint and above, display the image. When the component is placed in the TOC layout (12 / 16 columns), hide the image at all breakpoints.

Carbon for AEM Promo Banner component at full width lg breakpoint

Carbon for AEM Promo Banner component TOC layout lg breakpoint

Notice that in both of the above screenshots, the viewport size is 1056px (lg breakpoint), however in the TOC layout the component is constrained to 12 columns, and thus doesn't have enough room for the image. You could achieve this using media queries, however you'd need to coordinate and target a modifier CSS class that would flag the TOC case. Container queries offer a cleaner alternative wherein the component can adapt to the inline-size of the container element to achieve the desired result. We can use the knowledge of the Carbon grid parameters (gutters, condensed, wide, narrow, grid margin, etc.) to compose a container query that targets a given number of columns.

In our specific use case, where components are developed by one team, and ingested and placed in the grid by another team, container queries allow us to encapsulate these types of requirements inside the component, and not have to coordinate with the component adopter.

Proposed resolution

Let's leverage container queries! While that's great, the details get tricky, so we're proposing additions / changes to Carbon to help make using container queries to target Carbon columns easier.

Set containment on .cds--css-grid

First, anytime you want to make use of conatiner queries, you first have to set containment on a parent element. This is not that big a deal, especially if you own the page markup as well as specific components that want to leverage container queries. However to be able to reliably target Carbon grid columns, and all their variations, we propose setting the following on the Grid wrapping element (.cds--css-grid). This provides a reliable container query target:

.cds--css-grid {
  container: carbon-grid / inline-size
}

Provide a Carbon Grid Column Container Query mixin

What we're really after is this:

@container carbon-grid (num-columns: 12) {
  caem-promo-wrapper img {
    display: none;
  }
}

Of course the browser doesn't understand what a 'column' is. We're left with querying against the inline-size, which looks something like this:

.cds--css-grid {
  container: carbon-grid / inline-size;
}

.cds--css-grid-column {
  container: carbon-grid-column / inline-size;
}

@container grid-column (calc(75cqi - 2rem - 2px) < inline-size < calc(75cqi - 2rem + 2px)) {
  caem-promo-wrapper img {
    display: none;
  }
}

That can work for this very specific use case of 12 / 16 columns, wide Carbon grid, but it become tedious to do the cqi math on your own, to subtract the right gutter amount, and to account for subpixel rendering issues (FF only, the +/- 2px offsets.

We need a mixin! Here is proposed API for the mixin:

/// Generate a container query for grid column occupying the given $fraction of total columns.
/// @param {Number} $fraction - The number of columns covered, expressed as a number between 0 and 1, eg. 12 / 16 or 0.75.
/// @param {String} $container-name [''] - Optional container name used with @container rule.
/// @param {Number} $grid-gutter [$grid-gutter] - The grid gutters, adjust for narrow and condensed grids
/// @access public
@mixin carbon--grid-column-container-query(
  $fraction,
  $container-name: 'carbon-grid',
  $grid-gutter: $grid-gutter
) {
}

It's use would look like this:

@include carbon--grid-column-container-query(math.div(12, 16)) {
  caem-promo-wrapper img {
    display: none;
  }
}

You can also compose it with media queries to be able to say things like "if occupying 12 columns at lg breakpoint and above":

@include grid.breakpoint(lg) {
  @include carbon--grid-column-container-query(math.div(12, 16), grid-column) {
    caem-promo-wrapper img {
      display: none;
    }
  }
}

Proof of Concept

https://stackblitz.com/edit/vitejs-vite-wsvmto?file=index.html,style.scss,utilities.scss

This Stackblitz shows a sample implementation of the mixin we're proposing. The API is the same as noted above. There are copious inline comments attempting to explain each piece. The index.html file shows a simple Carbon grid with some content that we then target with media queries in styles.scss.

Worth noting that this could also be backported to v10, although it's slightly more complicated in v10 b/c of negative margin use.

[alisonjoseph]

This is cool! Curious if this will still work in nested grid situations? What about at smaller breakpoints when the total column count changes? (4 columns at small, 8 at medium)

I wouldn't think it would be worth back-porting to v10 seeing as support ends in September.

[andy-blum]

Curious if this will still work in nested grid situations?

From our testing, yes, this will work in nested grids. The container query will climb the CSSOM to find the next container (if no container name is provided) or the next matching container (if a container name is provided).

What about at smaller breakpoints when the total column count changes? (4 columns at small, 8 at medium)

The way this is structured right now, you'd need to put container queries in media queries, and adjust the provided fraction value.

@include grid.breakpoint(sm) {
  @include carbon--grid-column-container-query(math.div(4, 4), grid-column) {
    ...
  }
}

@include grid.breakpoint(md) {
  @include carbon--grid-column-container-query(math.div(6 / 8), grid-column) {
    ...
  }
}

@include grid.breakpoint(lg) {
  @include carbon--grid-column-container-query(math.div(12, 16), grid-column) {
    ...
  }
}