Skip to content

Commit

Permalink
GITBOOK-8: No subject
Browse files Browse the repository at this point in the history
  • Loading branch information
@itsJohnnyGrid @gitbook-bot
itsJohnnyGrid authored and gitbook-bot committed Apr 29, 2024
1 parent 68767b3 commit 93525be
Show file tree
Hide file tree
Showing 4 changed files with 281 additions and 87 deletions.
47 changes: 23 additions & 24 deletions docs/customization/colors.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,8 @@
Components are based on a `brand` and a `gray` color. 

<pre class="language-js" data-title="vueless.config.js"><code class="lang-js">export default {
brand: "green",
gray: "zinc",
brand: "blue",
gray: "stone",
}<a data-footnote-ref href="#user-content-fn-1">;</a>
</code></pre>

Expand All @@ -17,11 +17,17 @@ Vueless uses Tailwind CSS under the hood, so you can use any of the [Tailwind CS
* the `brand` color is `green`,
* the `gray` color is `zinc`.

## Custom colors
{% hint style="info" %}
We'd advise you to use brand colors in your components and pages, e.g. `text-brand-700 dark:text-brand-300`, etc.
{% endhint %}

**Default shade**

When [using custom colors](https://tailwindcss.com/docs/customizing-colors#using-custom-colors) or [adding additional colors](https://tailwindcss.com/docs/customizing-colors#adding-additional-colors) through the `extend` key in your `tailwind.config.js`, you'll need to make sure to define all the shades from `50` to `950` as most of them are used in the package components.
The `brand` color has a `default` shade. It is `500` in light mode and `400` in dark mode. You can use it as a shortcut in your components and pages, e.g. `bg-brand`, `focus-visible:ring-brand`, etc.

You can [generate your colors](https://tailwindcss.com/docs/customizing-colors#generating-colors) using tools such as https://uicolors.app for example.
## Custom colors

When [using custom colors](https://tailwindcss.com/docs/customizing-colors#using-custom-colors) or [adding additional colors](https://tailwindcss.com/docs/customizing-colors#adding-additional-colors) through the `extend` key in your `tailwind.config.js`, you'll need to make sure to define all the shades from `50` to `950` as most of them are used in the Vueless components.

{% code title="tailwind.config.js" %}
```js
Expand Down Expand Up @@ -49,40 +55,31 @@ export default {
```
{% endcode %}

## Brand CSS Variable

To provide dynamic brand color that can be changed at runtime, this module uses CSS variable.
You can [generate your colors](https://tailwindcss.com/docs/customizing-colors#generating-colors) using tools such as [uicolors](https://uicolors.app) for example.

> We'd advise you to use that color in your components and pages, e.g. `text-brand dark:text-brand`, etc. so your app automatically adapts when changing your `vueless.config.js`.
## Changing `brand` color at runtime

To change the brand color, you should call this function whatever you need:
To change the brand color at runtime, you can call the function below:

```js
import { setBrandColor } from "vueless/service.ui";

// set default brand color
setBrandColor();

// or set brand color from tailwind colors palette
setBrandColor("red");

// or set your own custom brand color
setBrandColor("#00C16A");
```

The `brand` color also has a `DEFAULT` shade that changes based on the theme. It is `500` in light mode and `400` in dark mode. You can use it as a shortcut in your components and pages, e.g. `text-brand`, `bg-brand`, `focus-visible:ring-brand`, etc.

> For custom hex color, there is only one shade for dark and light themes.
***

## Smart Safelisting

Components having a `color` prop like `UAvatar`, `UButton`, `URadioGroup`, `UCheckbox`, `UHeader` etc. will use the `brand` or `grayscale` color by default, but will handle all the colors defined in your `tailwind.config.ts` or the default Tailwind CSS colors.
Components having a `color` prop like `UAvatar`, `UButton`, `URadioGroup`, `UCheckbox`, `UHeader` etc. will use the `brand` or `grayscale` color by default, but will handle all the colors defined in your `tailwind.config.js` or the default Tailwind CSS colors.

Variant classes of those components are defined with a syntax like `bg-{color}-500 dark:bg-{color}-400` so they can be used with any color. However, this means that Tailwind will not find those classes and therefore will not generate the corresponding CSS.
Variant classes of those components are defined with a syntax like `bg-{color}-500 dark:bg-{color}-400` so they can be used with any color. However, this means that Tailwind CSS will not find those classes and therefore will not generate the corresponding CSS.

The library uses the [Tailwind CSS safelist](https://tailwindcss.com/docs/content-configuration#safelisting-classes) feature to force the generation of component colors.

The Vueless will **automatically** detect when you use one of those components with a color and will safelist it for you. This means that if you use a `red` color for a UButton component, the `red` color classes will be safelisted for the UButton component only. This will allow to keep the CSS bundle size as small as possible.
Vueless will **automatically** detect when you use one of those components with a color and will safelist it for you.&#x20;

This means that if you use a `red` color for a `UButton` component, the `red` color classes will be safelisted for this component. This will allow to keep the CSS bundle size as small as possible.

If you bind a dynamic color to a component: `<UBadge :color="color" />`, `<UButton :color="statuses[button.status]" />`, etc. You'll need to safelist the possible color values manually as well.

Expand All @@ -99,9 +96,11 @@ export default {
```
{% endcode %}

To reduce the app bundle size It's better to safelist colors for particular components.

## Replacing safelist patterns

In some specific cases you can replace safelist config as well:
In some specific cases you may need to replace [Tailwind CSS safelist config](https://tailwindcss.com/docs/content-configuration#using-regular-expressions) as well, so for that reason you can use `safelist` callback function in particular component config.

{% code title="vueless.config.js" %}
```js
Expand Down
143 changes: 96 additions & 47 deletions docs/customization/components.md
View file
Original file line number Diff line number Diff line change
@@ -1,62 +1,125 @@
# Components

#### `vueless.config.js`
As you may already know the Vueless components are styled with [Tailwind CSS](https://tailwindcss.com/). All default component classes which appies to each HTML tag available in [Vueless UI docs](https://ui.vueless.com/) in **`Default config`** chapter (at the end of each page).

Components are styled with Tailwind CSS but classes are all defined in the default `configs/default.config.js` file located in each component folder. You can override those in your own `vueless.config.js`.
You can change the default classes of Vueless components in 3 ways:

```js
// vueless.config.js
* Globally in `vueless.config.js`,
* Locally by component `config` prop,
* Locally by component `class` attribute.

## Classes smart merging

Thanks to [tailwind-merge](https://github.com/dcastil/tailwind-merge), all those configs are smartly merged with the default config. This means you don't have to rewrite everything.

### **Merging priority**

* Component `class` attribute (highest priority)
* Component `config` prop
* Global `vueless.config.js`
* Component default config (lowest priority)

### Merging strategy

You can change a merge behaviour by changing the `strategy` key in the `vueless.config.js` or `config` prop:

* `merge` (default) – smartly merge provided custom classes with default config classes.
* `replace` – replace default config keys by provided custom keys (override only provided keys, the rest classes will be taken from the default config).
* `override` – override default config by provided custom config (keeps only custom config, removes all default classes).

{% code title="vueless.config.js" %}
```js
export default {
strategy: "override", // applies for all components
component: {
UButton: {
strategy: "merge", // applies only for UButton
button: {
base: "bg-red-500 w-full",
}
}
}
};
```
{% endcode %}

Thanks to [tailwind-merge](https://github.com/dcastil/tailwind-merge), the `vueless.config.js` is smartly merged with the default config. This means you don't have to rewrite everything.
## `CVA`

You can change this behavior by changing `strategy` in your `vueless.config.js` to:
For managing classes variants Vueless components use [cva](https://github.com/joe-bell/cva) (Class Variance Authority) under the hood. For more details you can read related [cva docs](https://cva.style/docs/getting-started/variants).

* `override` – override default config by custom defined config (keeps only custom config and remove everything else).
* `replace` – replace default config keys by custom defined config keys, (the rest classes takes from the default config).
* `merge` – smartly merge custom defined classes with default config classes (default strategy).
{% hint style="warning" %}
Due to configs merge feature Vueless doesn't support **arrays** for values in `compoundVariants` .
{% endhint %}

```js
// vueless.config.js
***

## `vueless.config.js`

Some examples of changing classes for a Vueless components globally.

{% code title="vueless.config.js" %}
```js
export default {
strategy: 'override',
component: {
/* simplified way of stiling */
UButton: {
button: {
base: "bg-red-500 w-full",
}
button: "bg-red-500 w-full",
text: "px-4 text-lg font-bold"
},
/* full way of stiling with variants */
UCard: {
wrapper: {
base: "border-gray-300",
variants: {
rounded: {
sm: "rounded-sm",
md: "rounded",
lg: "rounded-md",
},
padding: {
sm: "p-2 md:p-6",
md: "p-4 md:p-8",
lg: "p-6 md:p-10",
},
},
},
}
/* full way of stiling with compoundVariants */
ULabel: {
label: {
base: "font-bold",
compoundVariants: [
{ placement: "top", size: "sm", class: "m-0 p-0 text-sm" },
{ placement: "top", size: "md", class: "m-0 p-0 text-base" },
{ placement: "top", size: "lg", class: "m-0 p-0 text-lg" },
],
},
}
/* setting default props */
UMoney: {
defaultVariants: {
delimiter: ".",
symbolAlign: "left",
divided: false,
},
}
}
};
```
{% endcode %}

#### `config` prop
## `config` prop

Each component has a `config` prop that allows you to customize everything specifically.
Each component has a `config` prop that allows to customize everything specifically.

```jsx
<template>
<UButton :config="{ button: { base: 'max-w-2xl' } }">
<UButton :config="{ button: 'max-w-2xl' }">
<slot />
</UButton>
</template>
```

> You can find the default classes for each component under the `Config` section.
Thanks to [tailwind-merge](https://github.com/dcastil/tailwind-merge), the `config` prop is smartly merged with the config. This means you don't have to rewrite everything.

For example, the default preset of the `UEmpty` component looks like this:

```js
Expand Down Expand Up @@ -90,52 +153,37 @@ For example, the default preset of the `UEmpty` component looks like this:
}
```

To change the font of the `title`, you only need to write:
To change the font weight of the `title`, you only need to write:

```jsx
<UEmpty
title="The list is empty"
:config="{ title: { base: 'font-bold' } }"
title="The list is empty"
:config="{ title: 'font-bold' }"
/>
```

This will smartly replace the `font-medium` by `font-bold` and prevent any class duplication and any class priority issue.

You can change this behavior by setting `strategy` to `replace` or `override` inside the `config` prop:

```jsx
<UButton
label="Submmit"
:config="{
strategy: 'replace',
color: {
white: {
solid: 'bg-white dark:bg-gray-900'
}
}
}"
/>
```

#### `class` attribute
## `class` attribute

You can also use the `class` attribute to add classes to the component.

```vue
```html
<template>
<UButton label="Button" class="font-bold" />
</template>
```

Again, with [tailwind-merge](https://github.com/dcastil/tailwind-merge), this will smartly merge the classes with the `config` prop and the global and default configs.
In this case classes will be applied to the top level component's HTML tag.

#### Default values
***

## Default values

Some component props like `size`, `color`, `variant`, etc. have a default value that you can override in your `vueless.config.js` or by the `config` prop as well.

{% code title="vueless.config.js" %}
```js
// vueless.config.js

export default {
component: {
UButton: {
Expand All @@ -148,3 +196,4 @@ export default {
}
};
```
{% endcode %}
Loading

0 comments on commit 93525be

Please sign in to comment.