Skip to content
This repository has been archived by the owner on Sep 24, 2024. It is now read-only.

docs: README #83

Merged
merged 1 commit into from
Aug 16, 2023
Merged

docs: README #83

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
237 changes: 201 additions & 36 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
<p align="center">
<img src="./docs/docs/public/windi.svg" style="width:100px;" />
<h1 align="center">NuxtLabs-UI-Vue</h1>
<p align="center">Build Accessible Apps 10x faster</p>
</p>

## Features
Expand All @@ -19,87 +17,176 @@ Add `NuxtLabs-UI-Vue` to your project by running one of the following commands:
```bash

# pnpm
pnpm add windi-vue
pnpm add nuxtlabs-ui-vue

# yarn
yarn add windi-vue
yarn add nuxtlabs-ui-vue

# npm
npm install windi-vue
npm install nuxtlabs-ui-vue

```

And also add `@tailwindcss/forms` plugin by running the following command:

```bash

# pnpm
pnpm add -D @tailwindcss/forms

# yarn
yarn add --dev @tailwindcss/forms

# npm
npm install -D @tailwindcss/forms

```

## Usage

1. Add the NuxtLabs-UI-Vue theme file and the darkMode class in your tailwind.config.cjs file as shown below:
1. Register the `@tailwindcss/forms` plugin and add the NuxtLabs-UI-Vue theme file, the darkMode class and the tailwindCss colors configuration in your tailwind.config.cjs file as shown below:

```ts
import tailwindColors from './node_modules/tailwindcss/colors'

const colorSafeList = []

const deprecated = ['lightBlue', 'warmGray', 'trueGray', 'coolGray', 'blueGray']

for (const colorName in tailwindColors) {
if (deprecated.includes(colorName))
continue

const shades = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900]

const pallette = tailwindColors[colorName]

if (typeof pallette === 'object') {
shades.forEach((shade) => {
if (shade in pallette) {
colorSafeList.push(`text-${colorName}-${shade}`),
colorSafeList.push(`accent-${colorName}-${shade}`),
colorSafeList.push(`bg-${colorName}-${shade}`),
colorSafeList.push(`hover:bg-${colorName}-${shade}`),
colorSafeList.push(`focus:bg-${colorName}-${shade}`),
colorSafeList.push(`ring-${colorName}-${shade}`),
colorSafeList.push(`focus:ring-${colorName}-${shade}`),
colorSafeList.push(`border-${colorName}-${shade}`)
}
})
}
}
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ['./index.html', './src/**/*.{vue,js,ts,jsx,tsx}', 'node_modules/windi-vue/dist/theme/*.{js,jsx,ts,tsx,vue}'],
content: ['./index.html', './src/**/*.{vue,js,ts,jsx,tsx}', 'node_modules/nuxtlabs-ui-vue/dist/theme/*.{js,jsx,ts,tsx,vue}'],
darkMode: 'class',
safelist: colorSafeList,
theme: {
extend: {},
extend: {
colors: tailwindColors
},
},
plugins: [],
plugins: [require('@tailwindcss/forms')],
}
```

Since TailwindCss doesn't support dynamic class names, you need to configure the `tailwind.config.cjs` file as shown above. You can read more about safelisting tailwindcss classes [here](https://tailwindcss.com/docs/content-configuration#safelisting-classes)


### Component registration

With NuxtLabs-UI-Vue, you have the flexibility to register components precisely as you wish:

### Import All Components

To import all the components provided by `NuxtLabs-UI-Vue`, add `WindiUI` in your main entry file as shown below:
To import all the components provided by `NuxtLabs-UI-Vue`, add `NuxtLabsUI` in your main entry file as shown below:

```ts
import { createApp } from 'vue'
import windiTheme from 'windi-vue/dist/theme/windiTheme'
import WindiUI from 'windi-vue'
import './style.css'
import nuxtLabsTheme from 'nuxtlabs-ui-vue/dist/theme/nuxtlabsTheme'

import install from 'nuxtlabs-ui-vue'
import App from './App.vue'

const app = createApp(App)
app.use(WindiUI, windiTheme)
app.use(install, nuxtLabsTheme)
app.mount('#app')
```

**By doing this, you are importing all the components that are provided by NuxtLabs-UI-Vue and in your final bundle all the components including the ones you didn't use will be bundled. Use method of component registration if you are confident that you will use all the components.**
**By doing this, you are importing all the components that are provided by NuxtLabs-UI-Vue and in your final bundle all the components including the ones you didn't use will be bundled. Use this method of component registration if you are confident that you will use all the components.**

### Individual Components with Tree Shaking

Probably you might not want to globally register all the components but instead only import the components that you need. You can achieve this by doing the following:

1. Import the `createWindiUI` option as well as the components you need as shown below:
1. Import the `createNuxtLabsUI` option as well as the components you need as shown below:

```ts
import { createApp } from 'vue'
import './style.css'
import windiTheme from 'windi-vue/dist/theme/windiTheme'
import nuxtLabsTheme from 'nuxtlabs-ui-vue/dist/theme/nuxtlabsTheme'

import { WKbd, createWindiUI } from 'windi-vue'
import { UButton, UDropdown, createNuxtLabsUI } from 'nuxtlabs-ui-vue'

import App from './App.vue'

const app = createApp(App)

const UI = createWindiUI({
const UI = createNuxtLabsUI({
prefix: 'T',
components: [WKbd],
components: [UDropdown, UButton],
})

app.use(UI, windiTheme)
app.use(UI, nuxtLabsTheme)

app.mount('#app')
```

2. Now you can use the component as shown below:

```js
<script setup lang="ts">
const items = [
[{
label: 'Profile',
avatar: {
src: 'https://avatars.githubusercontent.com/u/739984?v=4'
}
}],
[{
label: 'Edit',
icon: 'heroicons:pencil-square-20-solid',
shortcuts: ['E'],
click: () => {
console.log('Edit')
}
}, {
label: 'Duplicate',
icon: 'heroicons:document-duplicate-20-solid',
shortcuts: ['D'],
disabled: true
}], [{
label: 'Archive',
icon: 'heroicons:archive-box-20-solid'
}, {
label: 'Move',
icon: 'heroicons:arrow-right-circle-20-solid'
}], [{
label: 'Delete',
icon: 'heroicons:trash-20-solid',
shortcuts: ['⌘', 'D']
}]
]
</script>

<template>
<div>
<TKbd>K</TKbd>
<div class="grid place-items-center w-full min-h-screen">
<div>
<TDropdown :items="items" :popper="{ placement: 'bottom-start' }">
<TButton color="white" label="Options" trailing-icon="heroicons:chevron-down-20-solid" />
</TDropdown>
</div>
</div>
</template>
```
Expand Down Expand Up @@ -134,19 +221,19 @@ npm i -D unplugin-vue-components
```ts
import { createApp } from 'vue'
import './style.css'
import windiTheme from 'windi-vue/dist/theme/windiTheme'
import nuxtLabsTheme from 'nuxtlabs-ui-vue/dist/theme/nuxtlabsTheme'

import { createWindiUI } from 'windi-vue'
import { createNuxtLabsUI } from 'nuxtlabs-ui-vue'

import App from './App.vue'

const app = createApp(App)

const UI = createWindiUI({
const UI = createNuxtLabsUI({
registerComponents: false,
})

app.use(UI, windiTheme)
app.use(UI, nuxtLabsTheme)

app.mount('#app')
```
Expand All @@ -155,44 +242,122 @@ app.mount('#app')

```ts
// other imports
import { WindiUIComponentResolver } from 'windi-vue'
import { NuxtLabsUIComponentResolver } from 'nuxtlabs-ui-vue'
import Components from 'unplugin-vue-components/vite'

export default defineConfig({
plugins: [
// other plugins
Components({
resolvers: [
WindiUIComponentResolver()
NuxtLabsUIComponentResolver()
]
}),
})
],
})
```

4. Now you can simply use any component that you want and it will be auto imported on demand ✨

```js
<script setup lang='ts'>
const items = [
[{
label: 'Profile',
avatar: {
src: 'https://avatars.githubusercontent.com/u/739984?v=4'
}
}], [{
label: 'Edit',
icon: 'heroicons:pencil-square-20-solid',
shortcuts: ['E'],
click: () => {
console.log('Edit')
}
}, {
label: 'Duplicate',
icon: 'heroicons:document-duplicate-20-solid',
shortcuts: ['D'],
disabled: true
}], [{
label: 'Archive',
icon: 'heroicons:archive-box-20-solid'
}, {
label: 'Move',
icon: 'heroicons:arrow-right-circle-20-solid'
}], [{
label: 'Delete',
icon: 'heroicons:trash-20-solid',
shortcuts: ['⌘', 'D']
}]
]
</script>

<template>
<div>
<WKbd>K</WKbd>
<div class="grid place-items-center w-full min-h-screen">
<div>
<UDropdown :items="items" :popper="{ placement: 'bottom-start' }">
<UButton color="white" label="Options" trailing-icon="heroicons:chevron-down-20-solid" />
</UDropdown>
</div>
</div>
</template>
```

## Troubleshooting TypeScript Error

If you're encountering the TypeScript error: **Cannot find module 'windi-vue/dist/theme/windiTheme' or its corresponding type declarations**, you can follow these steps to resolve it:
If you're encountering the TypeScript error: **Cannot find module 'nuxtlabs-ui-vue/dist/theme/nuxtlabsTheme' or its corresponding type declarations**, you can follow these steps to resolve it:

1. Create a `windi-vue.d.ts` declaration file in your `src` directory and inside it paste the following code:
1. Create a `nuxtlabs-ui-vue.d.ts` declaration file in your `src` directory and inside it paste the following code:

```ts
declare module 'windi-vue/dist/theme/windiTheme'
declare module 'nuxtlabs-ui-vue/dist/theme/nuxtlabsTheme'
```

The error should now be resolved.

This issue is set to be fixed in the next release of **NuxtLabs-UI-Vue v0.0.1 Alpha**
This issue is set to be fixed in the next release.


## Component Customizations

In regards to customization, NuxtLabs UI Vue offers two ways of customizing your components. The first way is through the `variants` property and the second way is by creating your own `theme file`.

Here is an example of customizing a `UButton` component through the `variants` property:

```js
<template>
<div>
<UButton :variants="{
'my-variant': {
rounded: 'rounded-full'
}
}" :variant="['my-variant']" color="red" label="Button" />
</div>
</template>
```

By default, the default `roundedness` of the `UButton` component is `rounded-md`. However, we have customized its appearance by using the variants property to change its `roundedness` and then we used the variant prop to pass our variant which is `my-variant` ( you can name it whatever you want) to the `variant` array and now the `UButton` component will be rendered with a fully rounded appearance (rounded-full).

You can customize each component this way using the component's preset which can be found [here](./src/theme/nuxtLabsTheme.ts)

For any component that uses the `variant` prop such as the `UButton`, `UBadge`, `UInput`, `UTextarea`, `USelect`, etc, use the `intent` prop instead as shown below:

```js
<template>
<div>
<UButton intent="soft" color="red" label="Button" />
</div>
</template>
```

```js
<template>
<div>
<UBadge color="red" intent="solid" label="Badge" />
</div>
</template>
```


🥳 Well done, you can now go ahead and build your web application with ease.
Expand All @@ -205,10 +370,10 @@ Developers interested in contributing should read the [Code of Conduct](./CODE_O

## Credits

- [@nuxtlabs-ui](https://github.com/nuxtlabs/ui)
- [@headlessui/vue](https://headlessui.com)
- [@vueuse/core](https://vueuse.org)
- [TailwindCss](https://tailwindcss.com)
- [UnoCss](https://unocss.com) for the landing page rainbow animation.

## License

Expand Down
2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,4 +44,4 @@
"pnpm lint:fix"
]
}
}
}
Loading
Loading