As discussed offline:

• v1 milestone: We will develop a web component <nimiq-checkout-button>, which is styled as a Nimiq primary button by default. The shop user can tweak the styles a little bit by using properties such as buttonColor, small, inverse and pill.

• v2 milestone: We will provide a plain JavaScript solution for a more advanced shop user to style everything he/she want. Also the user is free to use the library in any JS context or framework.

from nimiq-popup-shop.

Research

A web component can be styled in very different ways, for example by defining styles as static styles properties or using a style element in a LitElement definition. However, we do need a way to style our <nimiq-checkout-button> web component from outside and there are two approaches to do that:

1 Using CSS selectors

Outside styles always win over styles defined in shadow DOM

(^ https://developers.google.com/web/fundamentals/web-components/shadowdom#stylefromoutside)

With this ^, we can use <nimiq-checkout-button> as a tag name selector:

<style>
nimiq-checkout-button {
    /* ...any styles... */
}
</style>

<nimiq-checkout-button>
</nimiq-checkout-button>

Or even better, we can add a CSS class directly to it:

<style>
.myButton {
    /* ...any styles... */
}
</style>

<nimiq-checkout-button
  class="myButton">
</nimiq-checkout-button>

Also we can easily style our button as a primary Nimiq button

<!-- Following does not work -->
<nimiq-checkout-button
  class="nq-button">
</nimiq-checkout-button>

Note that in that case ^ the web component can only have a single <button> as a :host element, but not any other childrens or :slotted elements.

2 Using custom CSS properties

Custom properties (sometimes referred to as CSS variables or cascading variables) are entities defined by CSS authors that contain specific values to be reused throughout a document.

(^ https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)

By using CSS custom properties we could provide styling options for component consumers:

nimiq-checkout-button.js

<style>
  :host {
    background-color: var(--bgButton, yellow);
    /* ... and more styles if needed ... */
  }
</style>

index.html

<style>
  nimiq-checkout-button {
    --bgButton: black;
  }
</style>

Summary

Approach 1 gives an user the option to style anything he/she want. The only downside is, that a web component can include just one :host element, but not any nested children. In our case a single <button> would be fine. To display error messages or something else, we can provide a property onError (or something) to <nimiq-checkout-button> to add a callback function for error handling. With this the shop user can handle and display any errors he/she would like.

Approach 2 is more a way to provide a theming for the <nimiq-checkout-button>. That means, the web component itself defined all needed styles by itself. And the user can select a theme, but can not define or add own styles.

I would recommend approach 1.

UPDATE:

• Shadow root does not inherited all CSS properties, which is a default behavior of CSS. Inherited CSS properties include:

  • color and background-color
  • font-family and other font-* properties
  • All CSS custom properties (--*)
    ^ https://lit-element.polymer-project.org/guide/styles#inheritance

• If a CSS class added to <nimiq-checkout-button> contains cursor: pointer, the click event does not work at :host component level.

• A disable style defined in a CSS class added to <nimiq-checkout-button> cant be inherit at :host` component level.

• Approach 1 is not an option anymore.

@svub Any feedback are welcome!

from nimiq-popup-shop.

From our conversation, let's add a summery here and close the issue.

What I recall:

• We'll have a JavaScript lib (or TypeScript?) that comes without any UI - so that is the one you want to use when you want to deeply customize stuff, and
• And then there is the web component version that comes prepacked with styling and works out of the box. Maybe we some custom color switches but in general as is.

from nimiq-popup-shop.