Add basic clean-theme support and update card, frame patterns

[lyzadanger]

This PR solves #85 by:

• adding a theme mixin that other mixins can use to apply theme-specific styles
• Updating the card and frame mixins to theme for the clean theme

I'm hoping that the changes themselves will obviate further explanation here (that's the goal here, anyway).

To finish #85, after #88 is resolved, we'll want to go back in and see how the modal components look in a clean theme. We may wish, e.g., to apply borders to modals even in the clean theme. (This is done)

Fixes #85

[lyzadanger]

Both this comment and the one further down in this module are "x is 5"-type comments, but the point I'm trying to make is that we should document theme deviations and their intent.

[lyzadanger]

Derp. This argument was unused.

[robertknight]

The "clean" theme mainly exists to satisfy the needs of a specific customer in the client. We may need to have it in the pattern library for that reason but we probably don't want to encourage its use elsewhere. Perhaps this is just something that can be noted in the docs. I wonder whether this mechanism could potentially support something more generally useful like a dark theme in future?

[lyzadanger]

The "clean" theme mainly exists to satisfy the needs of a specific customer in the client.

And don't I know it! And there's more, because to get the intended full effect of the clean theme, you also need to configure the client with several branding configuration properties.

I'm going to think about this a little more. Maybe this customization belongs entirely in the client. There are kind of two problems involved here:

• Support for theming, in general. This approach would move toward that, but we don't need to solve that problem yet, necessarily.
• Support for this specific, customer-related theming which only applies to the Sidebar (and in a couple of places, the Notebook). That needs to be solved before we can use shared Dialogs/Panels/Modals in the client, but doesn't need to be solved here necessarily.

On a tactical level, I wonder if this package should aim to keep all non-component specificity at (0, 0, 1, 0) or lower (that translates to a single class selector), and leave higher specificity to applications that use it. That may be too extreme, but it's a thought...

[lyzadanger]

After some soul-searching and reflection, I would like to opt to move forward with this approach to theming, in which this package applies some clean-theme styles.

The “clean” theme is only relevant to the client application, true.

But there’s no way to implement the theming affordances for the client-only clean theme without leakage about that theming in some way:

• With this approach, this project’s package has to “know” about the clean theme and provide styling affordances for it.
• If we did the clean-theming in the client project, however, the client would have to “know” about the package enough to extend classes or mixins. And getting the theming right is easier if a lower-level mixin (in this case, the card and frame patterns) are themed. I don’t especially want to make those mixins part of the public API, especially not now.

In looking at those two, the first (this PR’s direction) seems less problematic to me at present, additionally because:

• The overall amount of stying needed to effect the clean theme is fairly minimal (there just isn’t that much of it). So, yes, this package knows a little about the clean theme, but it’s not a huge pile.
• It will centralize theming. Say we introduce a dark mode or something. We’ll be able to implement it with the same theming-mixin pattern and see how the two (dark vs. clean) play together (or don’t).
• No changes are required in the applications (i.e. client) to use the components and patterns; they just work out of the box.

A side note about Modals: Although Modals are styled with the card and frame patterns (through multi-level inheritance), which have clean-theme affordances, they will not apply clean-theme styles in the client when the clean theme is activated. That is, the Modal components look the same in the client whether or not clean theme is activated. This is actually fine, as modals look better with a border, even in the clean theme. The reason the styles aren’t picked up is that Modals are attached to document.body when they’re rendered, and are not inside the application container that has the theme-clean class. tl;dr no user-facing changes will arise when these changes are released because the one shared component in current use that this would ostensibly affect is not affected.

[codecov]

Codecov Report

Merging #89 (a421e98) into main (24cad39) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##              main       #89   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            8         8           
  Lines          121       121           
  Branches        36        36           
=========================================
  Hits           121       121           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 24cad39...a421e98. Read the comment docs.

[robertknight]

The reason the styles aren’t picked up is that Modals are attached to document.body when they’re rendered, and are not inside the application container that has the theme-clean class.

This is potentially a little brittle. We can probably accept the risk for the moment, but if we can find a way to more directly enforce the non-usage of the "clean" theme inside modals that might prevent accidental breakage in future.

[lyzadanger]

This is potentially a little brittle. We can probably accept the risk for the moment, but if we can find a way to more directly enforce the non-usage of the "clean" theme inside modals that might prevent accidental breakage in future.

I'm working on replacing Panel components in the client right now with the shared variant, and will address this in that work (it sounds unrelated, but it actually is).