[locked] RFC: Buttons Standartization

[silviyaboteva]

Quick Overview

The main concept is described here: #1617

This discussion covers the Button and ButtonGroup.

In this discussion, we will write down the questions that arise during the process of standardizing the Buttons and the decisions we make. After all discussed cases are addressed, in the corresponding issue we will list the statements and the expected result of the task.

Now up to the new features:

New class

The Button will set k-button class by default.

We will keep k-button class.

Fill Mode

We utilize the following main fill modes - solid, outline, flat, and link. The CSS classes for the same will be k-button-solid, k-button-outline, k-button-flat, k-button-link.

Default rendering will add the k-button-solid class. There will be an option to reset the fill mode (the none value), which won't add fill class.

Sizes

We utilize 3 main sizes that will be used across components - small, medium and large. The CSS classes for the same will be k-button-sm, k-button-md, k-button-lg.

Default rendering will add the k-button-md class. There will be an option to reset the sizing (the none value), which won't add sizing class.

Note: Have in mind that in the component props, the values will be the whole word, a.k.a size={'medium'}.

Shape

To produce shapes for the buttons there are 2 steps (render 2 CSS classes):

Utilize the base shape

To create only the base structure of the component, we will use component-specific classes. For example: k-button-rectangle and k-button-square.

• shape property sets only the base structure of the component.
  • rectangle - grows with the content
  • square - have hard-coded dimensions (width = height)

Default rendering will add the k-button-rectangle class. There will be an option to reset the shape (the none value), which won't add class.

As the aspect-ratio is not supported for IE and Safari at this moment, we will go ahead and set both aspect-ratio and then calculated width and height of the element, so if the browser doesn't understand the first, it will fallback to the second styles. Once we drop the IE support, we can remove the hard-coded dimensions.

Add additional border radius

We will use utility classes for setting the border-radius of the components. They will be: k-rounded-sm, k-rounded-md, k-rounded-lg, k-rounded-circle(it will make the rectangular button as an elipse and square button as a circle). and k-rounded-pill(it will make the rectangular button as a pill and square button as a circle as well).

Additionally, we can implement other generic classes for rounding the sides separately and rounding the corners separately
Reference: https://tailwindcss.com/docs/border-radius.

If the users want to add custom rounding value, they can always use style property and set rounded to none. For example (rounded square): .my-button-custom-shape { aspect-ratio: 1; border-radius: 7px; }

Default rendering will add the k-rounded-md class by default (for all sizes). There will be an option to reset the border-radius (the none value), which won't add class.

ThemeColor

We utilize 11 component-specific classes as theme colors - k-button-solid-base, k-button-solid-primary, k-button-solid-secondary, k-button-solid-tertiary, k-button-solid-info, k-button-solid-success, k-button-solid-warning, k-button-solid-error, k-button-solid-dark, k-button-solid-light, k-button-solid-inverse.

Depending on the fillMode the classes will change to for example k-button-outline-base, k-button-flat-base, k-button-link-base, etc.
Default rendering will add the k-button-solid-base class. There will be an option to reset the coloring (the none value), which won't add color class.

The none concept

As described above, all properties will have a none value which will remove the default set CSS class.
In this case do we meet the Unstyled Components concept: https://material-ui.com/pt/customization/unstyled-components/. If yes, then we should promote it properly.

Rendering

<!-- default rendering -->
<button class="k-button k-button-solid k-button-md k-button-rectangle k-rounded-md k-button-solid-base">Button</button>

<-- classes variants --> 
<button type="button" class="
   k-button 
   k-button-solid | k-button-outline | k-button-flat | k-button-link | undefined
   k-button-md | k-button-sm | k-button-lg | undefined
   k-button-rectangle | k-button-square
   k-rounded-md | k-rounded-sm | k-rounded-lg | k-rounded-circle | k-rounded-pill | undefined
   k-button-solid-base | k-button-solid-primary | k-button-solid-secondary | k-button-solid-tertiary | k-button-solid-info | k-button-solid-success | k-button-solid-warning | k-button-solid-error | k-button-solid-dark | k-button-solid-light | k-button-solid-inverse | 
    k-button-outline-base | k-button-outline-primary | k-button-outline-secondary | k-button-outline-tertiary | k-button-outline-info | k-button-outline-success | k-button-outline-warning | k-button-outline-error | k-button-outline-dark | k-button-outline-light | k-button-outline-inverse | 
    k-button-flat-base | k-button-flat-primary | k-button-flat-secondary | k-button-flat-tertiary | k-button-flat-info | k-button-flat-success | k-button-flat-warning | k-button-flat-error | k-button-flat-dark | k-button-flat-light | k-button-flat-inverse | 
    k-button-link-base | k-button-link-primary | k-button-link-secondary | k-button-link-tertiary | k-button-link-info | k-button-link-success | k-button-link-warning | k-button-link-error | k-button-link-dark | k-button-link-light | k-button-link-inverse | undefined
">
    <span class="k-button-icon k-icon k-i-folder"></span>
    <span class="k-button-text">Button</span></button>
</button>

Docs

TODO

Tests (visual)

Tests should be created in tests/visual/src/reference/ folder as following:

• buttons/buttons-${suite}.html
• dropdownbuttons/dropdownbuttons-${suite}.html
• splitbuttons/splitbuttons-${suite}.html

Component API

In this section, we can think and write down the list of the props that will be added to the component. I'll start with the React Buttons:

 <Button
    icon="folder"
    iconPosition={'start (Default) | end'}
    size={'small | medium (Default) | large | none'}
    themeColor={'base (Default) | primary | secondary | tertiary | info | success | warning | error | dark | light | inverse | none'}
    shape={ 'rectangle (Default) | square | none' }
    rounded={'small | medium | large | circle | pill | none '}
    fillMode={'solid (Default) | outline | flat | | link | none'}
    >
    Browse
</Button>

Notes:

• The iconPosition property allows rendering the icon before or after the text. It will not add any CSS class. Rather than that, the component will render the <span> element with the icon either above the text or below it. Example:

<!-- iconPosition={'end'} -->
<button class="k-button k-button-solid k-button-md k-button-rectangle k-rounded-md k-button-solid-base">
    <span class="k-button-text">Button</span></button>
    <span class="k-button-icon k-icon k-i-folder"></span>
</button>

<!-- iconPosition={'start'} -->
<button class="k-button k-button-solid k-button-md k-button-rectangle  k-rounded-md k-button-solid-base">
    <span class="k-button-icon k-icon k-i-folder"></span>
    <span class="k-button-text">Button</span></button>
</button>

• The shape and the rounded properties come hand-in-hand.
  • shape property sets only the base structure of the component. It's values will be:
    • rectangle - grows with the content
    • square - have hard-coded dimensions (width = height)
  • rounded property will modify the border-radius to produce the desired shape. It's values will be:
    • sm/md/lg - applies 1px/2px/4px border radius
    • circle - makes the recrangle -> elipse, makes square -> circle
    • pill - square -> circle and rectangle -> pill

Playground

https://stackblitz.com/edit/react-uvyvdj?file=app%2Fmain.tsx

[silviyaboteva]

Hey guys,
After the sync with the FE team yesterday, we've agreed to ask our team members about two things related to the Button.

1. Do you have any concerns of renaming the k-button to k-btn class?
   Pros: Having shorter class names like k-btn-${size}, or k-btn-${themeColor}, k-btn-${fillMode}, etc.
   Cons: We will have find and replace all k-button classes in our demos/demo apps/KBs that doesn't use the Button component, but an HTML element with a class.
2. Do you have any concerns of removing the clear button fill mode?
   Quick info about this. The clear button is used only in the simple Button and it is having one use-case: in textbox with an icon button. The styles for the clear button are like flat, but without styles for hover, active, selected states. We can simply use the flat fill mode inside textboxes and remove these styles from the theme via .k-textbox .k-button-flat { //remove the unwanted styles }.
   In general, as all of the base components like buttons (button, splitbutton, dropdownbutton), inputs, dateinputs etc. will expose only 3 fill modes: solid, outline, and flat.

The KendoReact team is ok with renaming the class to k-btn. Our demo apps/KBs have a fixed version of the themes and components packages. Once we update their version to v5, we will change the k-button class if any.
About the clear button, we agree to delete it and provide additional styles for flat button in a textbox.

Please share your thoughts on this @tapopov @Raisolution @zdravkov @jivanova @Xizario @VicTachev @nenchef

[Raisolution]

1. I am ok with both names, whichever gets decided to be used. Although if the only Pro in this case are the 3 symbols shorter class names, I don't see a huge win in this change, but rather a huge renaming effort for both us and the customers.

   1a. I am also ok with renaming look to fillMode.

2. I am against this removal. While our only internal use case might be in the Textbox, this fill mode is exposed for the customers to use on their own (so much more use cases). Since we have the styles for this ready to use (through k-button-clear/k-btn-clear), I would prefer to keep them present.

[silviyaboteva]

@Raisolution about the fillMode: solid | outline | flat, yes we will change it everywhere because in some places is called look (Buttons, Chip), in other places it is called just fill (Badge, Avatar). We will standardize on this name.

[joneff]

There are a couple of issues here, mostly related to how we name things. Because we are not using BEM, or something similarly verbose, it's not immediately visible what is a component (Block), what is a part (Element) and what is variation of sort (Modifier). Here is an example with our very own button:

Kendo buttons can have text and or icons. We referred to them with "text button" and "icon button", which is a correct naming vector, and if named them using BEM it would bek-text-button and k-icon-button. If we have named the inner parts, they would have been k-button__text and k-button__icon. However, instead we called the outer parts k-button-text and k-button-icon which made it impossibly hard to know are talking about the icon and text parts or the type of button... In other words, we lack clear naming convention!

More often than not, we don't do a great job of naming things. Sometimes a property name or a value is misleading. Take for example the discussion about themeColor, which initially I suggested we call color. Why is it misleading? color refers to both the css property color and our concept of colorful components. (That's also why fill will be called fillMode -- so it doesn't get confused with the related SVG attribute / property.)

Or let's look at a property value -- by popular suggestion size="auto" was dropped in favour of size="none". Yes, in css auto means "use the surrounding page to determine whatever", but in this particular case it's unclear what "auto" would mean. Where as "none" means exactly one thing -- lack of something else.

Finally, please consider how we pronounce things: we call a button with fillMode="solid" "a solid button", we call a button with themeColor="secondary" "a secondary button", we call the menu button like so and we call the icon of the button "button icon".

With the above in mind, let's go back to fillMode="clear" and its intended use. Also, It was a compromise from the very start to have a button that:

• is exactly like the flat button, but with no hover state (which makes it the only button in the universe with no hover state)
• serves only one purpose and that is to style the clear value actionable element in the inputs

(It could also be used to style other buttons in input prefixes / suffixes, but that was more of a secondary goal)

When you add the fact that we pronounce it "clear button" it gets immediately obvious that we did a bad job -- we already have selectors k-button-clear in kendo-jquery and some very nasty side effects.

So... what can we do?

The most obvious choice is, just like Silvia suggested, to drop clear from fillMode values. Then we need to either use k-clear-value for that very special action part or handle things with css for the same thing. I personally steer towards handling k-clear-value and leave the rest to the customers.

Still, if the majority of people agree on keeping it, sure we can keep, but we must rename it. The new value cannot be "clear", nor nor "text", nor "link", nor "ghost" or anything like it.

(Speaking of fillMode="link", I would much prefer to have that as an option.)

[Juveniel]

The renaming effort for the jQuery components will be huge as the majority of components utilize hardcoded buttons instead of using the Button component. There are also several VSX templates, sample apps and other resources that have to receive the same treatment. Thus, from the jQuery perspective, we would rather avoid changing the k-button class.

In terms of the clear button styles - in my opinion handling this with the .k-clear-value class seems to be a much cleaner solution(avoiding cascade issues and overriding styles) rather than having dedicated button styles for this purpose.

[Raisolution]

Speaking of fillMode="link", I would much prefer to have that as an option.

I am ok with this option too. Clear may indeed be a bad naming as it more implies a button that clears something (e.g. a value) and not a button with clear styles. Such option would enable us to keep the existing button type by removing the term clear.

handling this with the .k-clear-value

The clear value button is only one of the use cases. The next could be an eye that switches the input type from password to text, and the next something else (outside the textbox). Probably value (and as we got to the conclusion clear too) should not be part of the CSS class that applies the styling.