Overview

Resolve all re-com styling issues.

Problems

The styling of re-com is currently a complex layer of:

• Bootstrap v3.3.5 (i.e. bootstrap.css)
• re-com.css
• Inline Styles
• Library user-provided styling arguments such as :class, :style, :parts etc.
• Any application specific stylesheets (e.g. my-app.css or my own application's Garden/Spade injections).

This leads to issues including:

• users must manually copy the correct bootstrap.css and re-com.css files to their own projects and include the appropriate links in their index.html file
• hard to understand / debug / develop re-com styles due to layering
• impossible to theme (Don't hardcode colors #33, Flexible configuration of complex components #123, Re-com should not install custom scrollbars globally #117)
• inability to use alternatives to Bootstrap (Feature request: re-com sans class #51, no bootstrap #283)
• issues that should be solvable by the library user end up as bugs e.g. accessibility, layout, device or resolution customization (Popover may easily render off-screen on small screens #191 , Accessibility Question - using larger zmdi icons #186, Splits shouldn't have 'overflow : hidden' hardcoded #182, h-split/v-split jump around when used inside an element with position: relative #181, input-text does not respect parent's flex settings #167, Popovers not positioned correctly for absolutely positioned anchors #112, Dropdown arrow is not stylable on high-res (without deep hacking) #101, Responsive layout container #68 )

Goals

• Colocation We want the code for CSS to be adjacent to the CLJS code for components which use them.
• Simplicity i.e. remove bootstrap.css, re-com.css and inline styles layers.
• Efficiency in repetitive performance critical code (e.g. v-table row renderers) we want classes, not inline styles. Some benchmarks indicate this should be faster
• Skinning/Theming We want to allow re-com library users to skin/theme re-com components in different ways:
  • Full replacement of all styles (e.g. use Material Design)
  • Full replacement of styles for a particular component (e.g. datepicker)
    • (Subset) Full replacement of styles for a particular component in a particular state (e.g. disabled?)
  • Just tweak the defaults a bit by changing a single property or amending a missing property (e.g. add some bottom margin).
• Shaking We want unused styles to be omitted in production builds e.g. if datepicker is not used the code for generating the CSS should not be included in the .js file and the <style> tag should not be registered at runtime.

Analysis

• A component is made of a tree of HTML elements which we call parts
• A component has some state related to:
  • its visual appearance
    • Disabled?
    • Dropdown open?
    • At any time, a datepicker is displaying a certain month
  • the model value being represented
    • InputText contains copies of model internally
    • what date is today?
    • what is the selected date?
• component state arises via:
  • passed in via args (eg disabled?)
  • caused by user actions, clicks, mouseover etc (to select a date, or open a dropdown). Some of these state changes are communicated
  • Internal code; e.g. for loop over dates in a month results in ‘state’ of a date per day
• A part’s existence is often dependent on state. For example, the “open” state for a dropdown causes the popover part to exist, which actually shows the dropdown.
• A part’s styling (classes) is often dependent on component state.

Proposal

Replace all existing styling with Garden and Spade.

Order of Components

First we will do dropdown (i.e. medium complexity) then we will do datepicker (i.e. most complex) to immediately verify our working model is good.

Process For Each Component

1. State Chart Model

First, we need to understand the abstract model of all the possible states of a component in order to be able to implement a way to style those states.

Write a state chart in PlantUML and embed it in a GitHub Markdown file named after the component (e.g. src/re_com/datepicker.cljs would be docs/datepicker.md).

E.g. for the dropdown component it might have a disabled? and an enabled? state, and in the enabled? state it might have states like open?, focused? etc which fundamentally impact the appearance of the component. Or in other words, what states exist that might need to have different styles or different classes associated with those states ?

Make a PR.

2. Parts Model

Second, we need to document all the possible parts (see 'Parts' at bottom of page) of a component.

Although the PlantUML component diagram is talking about a different type of component we could possibly use the 'Grouping Components' syntax as a rendering of part hierarchies. Otherwise, we could just represent it in pure Markdown. Either way, add to the Markdown file created in Step 1.

Make a PR.

3. Restyle Component

• Disable re-com.css and bootstrap.css (e.g. by commenting out <link.. tags in index.html)
• Remove all inline styles from the component
• Re-implement styles in Garden with Spade's defclass. :compose common styles (e.g. flex-child-style.
• Add an unstyled? parameter to the component that removes all classes and styling that defaults to false.

When the component is the same with unstyled? false as the existing styling, make a PR.

4. Expose Parts and State for Styling

• Ensure all documented parts are exposed via the :parts API
• If the :class or :style value in :parts is fn? then call it with a map of the current component state (e.g. {:disabled? true :open? false :today date}) and use the return value of the fn
• Watch Crafting Stateful Styles with State Machines by David Khourshid | CSSConf BP 2019
  
• Add data attribute to the component markup for all states (e.g. <div class="..." data-state="disabled">)

Make a PR.