From a41e3b9947dad08bc03056857b283dd942494a55 Mon Sep 17 00:00:00 2001 From: Selemondev Date: Wed, 16 Aug 2023 11:24:23 +0300 Subject: [PATCH] docs: README --- README.md | 237 +++++++++++++++--- package.json | 2 +- packages/nuxtlabs-ui-vue/README.md | 384 +++++++++++++++++++++++++++-- 3 files changed, 564 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 7a888ec..69c6973 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@

-

NuxtLabs-UI-Vue

-

Build Accessible Apps 10x faster

## Features @@ -19,32 +17,81 @@ 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 @@ -52,44 +99,46 @@ With NuxtLabs-UI-Vue, you have the flexibility to register components precisely ### 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') ``` @@ -97,9 +146,47 @@ app.mount('#app') 2. Now you can use the component as shown below: ```js + + ``` @@ -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') ``` @@ -155,7 +242,7 @@ 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({ @@ -163,9 +250,9 @@ export default defineConfig({ // other plugins Components({ resolvers: [ - WindiUIComponentResolver() + NuxtLabsUIComponentResolver() ] - }), + }) ], }) ``` @@ -173,26 +260,104 @@ export default defineConfig({ 4. Now you can simply use any component that you want and it will be auto imported on demand ✨ ```js + + ``` ## 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 + +``` + +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 + +``` + +```js + +``` 🥳 Well done, you can now go ahead and build your web application with ease. @@ -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 diff --git a/package.json b/package.json index 52cce61..c1ec98b 100644 --- a/package.json +++ b/package.json @@ -44,4 +44,4 @@ "pnpm lint:fix" ] } -} \ No newline at end of file +} diff --git a/packages/nuxtlabs-ui-vue/README.md b/packages/nuxtlabs-ui-vue/README.md index 3aa1b7d..69c6973 100755 --- a/packages/nuxtlabs-ui-vue/README.md +++ b/packages/nuxtlabs-ui-vue/README.md @@ -1,40 +1,380 @@ -# nuxtlabs-ui-vue +

+

NuxtLabs-UI-Vue

+

-This template should help get you started developing with Vue 3 in Vite. +## Features -## Recommended IDE Setup +- 🦾 **TypeScript Support** - Built with TypeScript in mind and from the ground up. +- 🔥 **Icon** - Use any icon from [Iconify](https://icones.netlify.app/) in your project from your favourite icon set. +- 🛠️ **On Demand Import** - NuxtLabs-UI-Vue comes with an intelligent resolver that automatically imports only used components. +- ⚡️ **Powerful Tools** - NuxtLabs-UI-Vue is built on top of powerful tools such as TailwindCss, VueUse, Headless UI etc. +- 🎨 **Themeable** - Customize any part of our beautiful components to match your style. -[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin). +## Getting Started -## Type Support for `.vue` Imports in TS +Add `NuxtLabs-UI-Vue` to your project by running one of the following commands: -TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) to make the TypeScript language service aware of `.vue` types. +```bash -If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a [Take Over Mode](https://github.com/johnsoncodehk/volar/discussions/471#discussioncomment-1361669) that is more performant. You can enable it by the following steps: +# pnpm +pnpm add nuxtlabs-ui-vue -1. Disable the built-in TypeScript Extension - 1) Run `Extensions: Show Built-in Extensions` from VSCode's command palette - 2) Find `TypeScript and JavaScript Language Features`, right click and select `Disable (Workspace)` -2. Reload the VSCode window by running `Developer: Reload Window` from the command palette. +# yarn +yarn add nuxtlabs-ui-vue -## Customize configuration +# npm +npm install nuxtlabs-ui-vue -See [Vite Configuration Reference](https://vitejs.dev/config/). +``` + +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. 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 = [] -## Project Setup +const deprecated = ['lightBlue', 'warmGray', 'trueGray', 'coolGray', 'blueGray'] -```sh -npm install +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/nuxtlabs-ui-vue/dist/theme/*.{js,jsx,ts,tsx,vue}'], + darkMode: 'class', + safelist: colorSafeList, + theme: { + extend: { + colors: tailwindColors + }, + }, + plugins: [require('@tailwindcss/forms')], +} ``` -### Compile and Hot-Reload for Development +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: -```sh -npm run dev +### Import All Components + +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 './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(install, nuxtLabsTheme) +app.mount('#app') ``` -### Type-Check, Compile and Minify for Production +**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 `createNuxtLabsUI` option as well as the components you need as shown below: + +```ts +import { createApp } from 'vue' +import './style.css' +import nuxtLabsTheme from 'nuxtlabs-ui-vue/dist/theme/nuxtlabsTheme' + +import { UButton, UDropdown, createNuxtLabsUI } from 'nuxtlabs-ui-vue' + +import App from './App.vue' + +const app = createApp(App) + +const UI = createNuxtLabsUI({ + prefix: 'T', + components: [UDropdown, UButton], +}) + +app.use(UI, nuxtLabsTheme) + +app.mount('#app') +``` + +2. Now you can use the component as shown below: + +```js + + + +``` + +The `prefix` option is only available for individual component imports. + +### Auto Imports with Tree Shaking + +**NuxtLabs-UI-Vue** comes with an intelligent resolver that automatically imports only used components. + +This is made possible by leveraging a tool known as [unplugin-vue-components](https://github.com/antfu/unplugin-vue-components) which lets you auto import components on demand thus omitting import statements and still get the benefits of tree shaking. + +To achieve this you need to do the following: + +1. Install the `unplugin-vue-components` package by running one of the following commands: + +```bash + +#pnpm +pnpm add -D unplugin-vue-components + +#yarn +yarn add -D unplugin-vue-components + +#npm +npm i -D unplugin-vue-components -```sh -npm run build ``` + +2. Head over to your `main.ts` or `main.js` file and set `registerComponents` to `false` as shown below: + +```ts +import { createApp } from 'vue' +import './style.css' +import nuxtLabsTheme from 'nuxtlabs-ui-vue/dist/theme/nuxtlabsTheme' + +import { createNuxtLabsUI } from 'nuxtlabs-ui-vue' + +import App from './App.vue' + +const app = createApp(App) + +const UI = createNuxtLabsUI({ + registerComponents: false, +}) + +app.use(UI, nuxtLabsTheme) + +app.mount('#app') +``` + +3. Head over to your `vite.config.ts` or `vite.config.js` file and add the following: + +```ts +// other imports +import { NuxtLabsUIComponentResolver } from 'nuxtlabs-ui-vue' +import Components from 'unplugin-vue-components/vite' + +export default defineConfig({ + plugins: [ + // other plugins + Components({ + resolvers: [ + NuxtLabsUIComponentResolver() + ] + }) + ], +}) +``` + +4. Now you can simply use any component that you want and it will be auto imported on demand ✨ + +```js + + + +``` + +## Troubleshooting TypeScript Error + +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 `nuxtlabs-ui-vue.d.ts` declaration file in your `src` directory and inside it paste the following code: + +```ts +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. + + +## 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 + +``` + +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 + +``` + +```js + +``` + + +🥳 Well done, you can now go ahead and build your web application with ease. + +## Contributions + +Contributions are welcome and encouraged! If you have any ideas or suggestions for new features, or if you encounter any bugs or issues, please open an issue or submit a pull request on the GitHub repository. + +Developers interested in contributing should read the [Code of Conduct](./CODE_OF_CONDUCT.md) and the [Contributing Guide](./CONTRIBUTING.md). + +## Credits + +- [@nuxtlabs-ui](https://github.com/nuxtlabs/ui) +- [@headlessui/vue](https://headlessui.com) +- [@vueuse/core](https://vueuse.org) +- [TailwindCss](https://tailwindcss.com) + +## License + +[MIT](./LICENSE) License © 2023 [Selemondev](https://github.com/selemondev) \ No newline at end of file