USWDS - Prose: Placeholder fix. Resolves #5094 #5158

mahoneycm · 2023-02-15T21:41:37Z

Alternative solution from #4962

Summary

Reverts usa-prose placeholders to use typeset mixins to resolve compilation errors.

Breaking change

⚠️ This is potentially a breaking change. This PR removes usa-prose- mixins and placeholders. Users should instead use typeset- mixins in their place.

Site changelog PR

uswds/uswds-site#2095

Related issue

Closes #4962

Preview link

Prose →

Problem statement

This work resolves two separate issues:

Build errors while extending %usa-prose- placeholders.
Compilation errors with mixins nested under the & > selector

1: Build errors with placeholder:

Sass can throw errors when we rely on @extend and placeholders in certain situations.
From #4962:

I’m trying to configure USWDS inside an @layer rule using the load-css function from sass:meta. When I try to @use "uswds-core" in my own Sass modules so that I can access the tokens for my styles, I get a target selector not found error for %usa-prose-p.

2: Compilation errors with mixins nested under the `& >` selector

This would result in the unexpected assignment of the & selector and in turn, incorrectly attach styles to classes

Solution

Revert usa-prose placeholder to a mixin
Manually paragraph and heading styles from the typeset mixins and directly into the usa-prose style definitions
Removed redundant and unused usa-prose mixins in favor of typeset- mixins

From @amyleadem in #5043:
Sass seems to get confused when * + & is brought in from another file via a mixin (more details in #4576). Additionally, Sass can throw errors in limited circumstances when we rely on @extend and placeholders.

The key conclusion is that * + & does not currently seem to be a viable addition to mixins or placeholders. By moving all * + & out of mixins and placeholders and directly into the style definitions, we can remove the risk of Sass confusion.

Note: The downside of this solution is that it requires some code repetition, but that might be slightly mitigated by creating variables/settings for the heading and paragraph top margins.

Major changes

This PR removes usa-prose- mixins and placeholders. Users should instead use typeset- mixins in their place.

List of mixins removed:

usa-prose-link
usa-prose-display
usa-prose-p
usa-prose-heading
usa-prose-h1 through h6

New settings variables

$theme-heading-margin-top
$theme-paragraph-margin-top

Testing and review

Confirm that Sass compiles without error
Visit Prose Storybook
Inspect usa-prose styles and make sure * + & selectors are correctly targetting headings and p tags
Use npm link to create a symlink to the package
Clone this test repo
Use npm link @uswds/uswds to replace USWDS package with the symlink
Run npm build and confirm no build errors

Run git pull origin [base branch] to pull in the most recent updates from your base and check for merge conflicts. (Often, the base branch is develop).
Run npm run prettier:scss to format any Sass updates.
Run npm test and confirm that all tests pass.

mahoneycm · 2023-02-15T21:46:50Z

@mejiaj @amyleadem This is the alternative solution mentioned in James' comment

This maintains current develop styles but it does move them in the output CSS.

Here is an easel that shows the relevant difference between files and verifies all necessary prose styles are present.: usa prose refactor

I tried adding colored arrows to help connect the changes

amyleadem

Hi @mahoneycm, I have started my review but need to step away for a bit. In the meantime, I found an error when $theme-global-content-styles is set to true because it is looking for the now missing usa-prose-link. I've also added some comments below with notes and a couple questions about code redundancy. I will cycle back later, but let me know if you have questions in the meantime.

So far the new solution appears to be on track, but there just a couple things to look at.

packages/uswds-core/src/styles/mixins/typography/usa-prose.scss

packages/usa-content/src/styles/_usa-content.scss

packages/usa-paragraph/src/styles/_usa-paragraph.scss

amyleadem · 2023-02-22T17:11:14Z

packages/usa-prose/src/styles/_usa-prose.scss

+    p {
+      line-height: line-height($theme-body-font-family, $theme-body-line-height);
+      margin-bottom: 0;
+      margin-top: 0;
+      max-width: measure($theme-text-measure);
+
+      + * {
+        margin-top: $theme-paragraph-margin-top;
+      }
+    }


Curious - this appears to be redundant with a good chunk of the typeset-p mixin. Is there a way to reduce redundancy without having a negative impact?

I haven't been able to successfully use the typeset mixins without it incorrectly setting *+.usa-prose p as the top-margin selector, unfortunately.

Scratch that, I'm going to use @mejiaj's typset-base recommendation to alleviate some of the redundancy!

amyleadem · 2023-02-22T17:11:16Z

packages/usa-prose/src/styles/_usa-prose.scss

+      @include u-margin-y(0);
+      clear: both;
+
+      + * {
+        margin-top: $theme-paragraph-margin-top;
+      }


Same thing here - feels redundant with the rules with typeset-heading. Can we reduce code redundancy here?

packages/uswds-core/src/styles/settings/_settings-typography.scss

mejiaj

This solution outputs what I would expect. If we go this route we should consider adding guidance to users (if any) that were using the removed extends.

Alternatively, we should consider simplifying in the future. By doing something like:

.usa-prose {
  & > {
    @include usa-list-styles;
    @include usa-table-styles;

    // Adds consistent margin to *all* child elements
    * + * {
      margin-top: $theme-paragraph-margin-top !important;
    }

    …H1-H6 styles

    // Only override headers
    * + {
      h1,
      h2,
      h3,
      h4,
      h5,
      h6 {
        margin-top: $theme-heading-margin-top !important;
      }
    }
  }
}

mejiaj · 2023-02-22T20:46:52Z

packages/usa-prose/src/styles/_usa-prose.scss

+      line-height: line-height($theme-body-font-family, $theme-body-line-height);
+      margin-bottom: 0;
+      margin-top: 0;
+      max-width: measure($theme-text-measure);


To avoid duplication, you could create a typeset-heading-base and typeset-p-base that include these styles in typeset.scss.

// // typeset.scss // @mixin typeset-heading-base { @include u-margin-y(0); clear: both; } @mixin typeset-heading { @include typeset-heading-base; * + & { margin-top: $theme-heading-margin-top; } + * { margin-top: $theme-paragraph-margin-top; } } // typeset element mixins @mixin typset-p-base { line-height: line-height($theme-body-font-family, $theme-body-line-height); margin-bottom: 0; margin-top: 0; max-width: measure($theme-text-measure); } @mixin typeset-p { @include typset-p-base; * + & { margin-top: $theme-paragraph-margin-top; } + * { margin-top: $theme-paragraph-margin-top; } }

I like this idea. I think it'll clean up the usa-prose class nicely!

I was able to use the typset-p/heading-base mixin and I personally like the clean-up it offers!

Using * + * did not work as expected but I was able to use *:not(:first-child) to achieve the same result

This will assist us in eliminating repeated code for usa-prose

…-prose

… typeset-heading-base

…lector-fix

mahoneycm · 2023-03-01T18:05:48Z

@mejiaj @amyleadem ok! So I've completed some refactoring by a combination of creating typeset-heading-base and typeset-p-base to avoid some duplication and to correctly reset top and bottom margins. I also moved certain selectors around in order to have the styles apply correctly and used the owl selector * + * to correctly give all siblings of usa-prose children the correct top margin.

I've taken a stab at some basic SASS unit testing to make sure that our nested selectors are working as expected! I'd love your feedback whenever you have a chance to see if there are other enhancements I may be missing, or if we can test further with the unit tests!

…lector-fix

mejiaj

Looks good, minor comments!

packages/usa-prose/src/styles/_usa-prose.scss

packages/uswds-core/src/styles/settings/_settings-typography.scss

packages/uswds-core/src/test/tests.scss

…nt flags from usa-prose

amyleadem

@mahoneycm This is looking good! It is feeling cleaner with each iteration. Thanks a ton for hanging in there with this one. Only thing I have to flag is the failed Sass test that is causing the build error.

packages/usa-paragraph/src/styles/_usa-paragraph.scss

packages/usa-content/src/styles/_usa-content.scss

mejiaj · 2023-03-24T18:39:15Z

@mahoneycm can you please look into the failing test?

mahoneycm · 2023-03-27T13:47:27Z

@mejiaj @amyleadem Looks like when I broke it when I tried formatting the test scss. I believe it was only because of the order of the output not matching the expected order. Moving the expected results to match the actual outputs did the trick!

amyleadem

Thanks for fixing the test!

mahoneycm · 2023-04-03T16:59:25Z

@thisisdano Ready for final review!

thisisdano · 2023-05-08T20:56:30Z

I'll draw up a changelog PR for this change.
Changelog PR: uswds/uswds-site#2096

mahoneycm · 2023-05-09T13:27:45Z

@thisisdano I created a changelog of this one before I left yesterday as well, let me know if you want me to go ahead and close this ticket: uswds/uswds-site#2095

I also wanted to note I did mark it as a breaking change because it removes the usa-prose- mixin.

mahoneycm added 5 commits February 15, 2023 14:17

Remove unused placeholders

e3c6186

Remove usa-prose placeholder in favor of typset mixin

5b5300c

Remove typography placeholders in favor of typset mixin

cc67809

Create and utilize theme-paragraph/heading-margin-top variables

5a933e7

Replace usa-headings/paragraph-styles in usa-prose

8bafc83

mahoneycm requested review from amyleadem and mejiaj and removed request for amyleadem February 15, 2023 21:41

amyleadem self-assigned this Feb 22, 2023

amyleadem suggested changes Feb 22, 2023

View reviewed changes

mejiaj reviewed Feb 22, 2023

View reviewed changes

mahoneycm added 6 commits February 22, 2023 16:20

Replace usa-prose-link reference with typeset-link

91021fe

Create typset heading and p base mixins

a46ca22

This will assist us in eliminating repeated code for usa-prose

Utilize typset base mixins and set margin top for all children of usa…

1113798

…-prose

Reorder selectors to correct overrides

97b9b6b

Create usa-prose scss unit test

67780d3

Typeset-p-base: use margin-y utility on margin normalization to match…

a8bd3e6

… typeset-heading-base

mahoneycm mentioned this pull request Feb 27, 2023

USWDS - Prose: Placeholder fix. Resolves #4962 #5094

Closed

3 tasks

Remove comment

246e2ab

amyleadem mentioned this pull request Mar 1, 2023

[Test] Prose placeholder fix #5043

Closed

mahoneycm added 3 commits March 1, 2023 11:54

Merge branch 'develop' of github.com:uswds/uswds into cm-usa-prose-se…

55ed260

…lector-fix

Move child paragraph selector

30c44b9

Further sass testing

af5040a

mahoneycm requested review from amyleadem and mejiaj March 1, 2023 18:02

Merge branch 'develop' of github.com:uswds/uswds into cm-usa-prose-se…

8b52f9c

…lector-fix

mejiaj suggested changes Mar 20, 2023

View reviewed changes

mahoneycm added 3 commits March 20, 2023 15:16

Move prose-test to bottom of stylesheet

bdea598

Move y margin reset from typeset-p-base to typeset-p & remove importa…

7996dfb

…nt flags from usa-prose

Format scss test and run prettier

b4a1b1c

mahoneycm requested a review from mejiaj March 21, 2023 14:02

amyleadem suggested changes Mar 23, 2023

View reviewed changes

packages/usa-paragraph/src/styles/_usa-paragraph.scss Show resolved Hide resolved

packages/usa-content/src/styles/_usa-content.scss Show resolved Hide resolved

Reorder sass test declarations to match output

5a74e18

mahoneycm requested a review from amyleadem March 27, 2023 13:45

amyleadem approved these changes Mar 27, 2023

View reviewed changes

mejiaj approved these changes Mar 30, 2023

View reviewed changes

mahoneycm requested a review from thisisdano April 3, 2023 16:59

thisisdano approved these changes May 8, 2023

View reviewed changes

mahoneycm mentioned this pull request May 8, 2023

USWDS-Site - Prose: Create change log for PR #5158 uswds/uswds-site#2095

Closed

thisisdano mentioned this pull request May 8, 2023

Add changelog items for USWDS 3.5.0 uswds/uswds-site#2096

Merged

24 tasks

thisisdano merged commit c782687 into develop May 10, 2023

thisisdano deleted the cm-usa-prose-selector-fix branch May 10, 2023 21:35

thisisdano mentioned this pull request Jun 6, 2023

USWDS 3.5.0 #5323

Merged

USWDS - Prose: Placeholder fix. Resolves #5094 #5158

USWDS - Prose: Placeholder fix. Resolves #5094 #5158

Uh oh!

Conversation

mahoneycm commented Feb 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking change

Site changelog PR

Related issue

Preview link

Problem statement

1: Build errors with placeholder:

2: Compilation errors with mixins nested under the & > selector

Solution

Major changes

List of mixins removed:

New settings variables

Testing and review

Uh oh!

mahoneycm commented Feb 15, 2023

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amyleadem Feb 22, 2023

Choose a reason for hiding this comment

Uh oh!

mahoneycm Feb 22, 2023

Choose a reason for hiding this comment

Uh oh!

mahoneycm Feb 22, 2023

Choose a reason for hiding this comment

Uh oh!

amyleadem Feb 22, 2023

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

mejiaj Feb 22, 2023

Choose a reason for hiding this comment

Uh oh!

mahoneycm Feb 22, 2023

Choose a reason for hiding this comment

Uh oh!

mahoneycm Feb 23, 2023

Choose a reason for hiding this comment

Uh oh!

mahoneycm commented Mar 1, 2023

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amyleadem left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mejiaj commented Mar 24, 2023

Uh oh!

mahoneycm commented Mar 27, 2023

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

mahoneycm commented Apr 3, 2023

Uh oh!

thisisdano commented May 8, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

mahoneycm commented Feb 15, 2023 •

edited

Loading

2: Compilation errors with mixins nested under the `& >` selector

amyleadem left a comment •

edited

Loading

thisisdano commented May 8, 2023 •

edited

Loading