Create abstraction for safer math.div usage

[tay1orjones]

Pointed out in #9850, math.div is only available in sass >=1.33.0. The Sass module system was introduced in 1.23.0. So it's possible for projects to be using sass modules, but still not have math.div available.

For these cases, it makes sense to wrap math.div usage in a conditional, using math.div when it's available, otherwise using legacy division:

@if meta.function-exists('div', 'math') {
  @return math.div($px, $base-font-size) * 1rem;
} @else {
  @return ($px / $base-font-size) * 1rem;
}

Unfortunately there is not a clean way to ensure this conditional is always used moving forward. Linting has a shortfall - the stylelint-scss plugin we use for stylelint rejected the proposal of a rule for no-division.

One way we could ensure correct usage would be to:

1. Abstract the conditional out into its own helper function, div(dividend, divisor)
   • This helper should effectively replace all usages of math.div and legacy division.
   • math.div is used across various different packages in the monorepo. To facilitate reuse, the helper needs to be published as it's own new package in the monorepo.
2. Ensure math.div is never used directly by disallowing it via Stylelint's function-disallowed-list rule.
   • The new helper function/package would need to disable/ignore this rule.
   • Ideally a custom error message would be displayed when someone tries to use math.div
     • Using math.div is not allowed, please use div() from @carbon/packageName instead

[tay1orjones]

This comment patternfly/patternfly#4096 (comment) is essentially what we'd be aiming for.

I'm not sure if there's a difference between map.has-key(meta.module-functions("math"), "div") and
meta.function-exists('div', 'math')

[joshblack]

@tay1orjones could we list sass@>=1.33.0 as a requirement for v11? I think we could list that version range as a peer dependency unless there is something else at play here 👀

[tay1orjones]

@joshblack Yep, that would be my preference. It sounds like you agree, so I'll close this.

For now we'll stick with the conditionals that were added in #9850. In v11 we can remove them.