docs: migrate to @nuxthq/ui-kit (#405)

Co-authored-by: Sébastien Chopin <seb@nuxt.com>
This commit is contained in:
Benjamin Canac
2023-07-17 14:49:50 +02:00
committed by GitHub
parent 2ec28e7cbd
commit 31d571abb5
71 changed files with 2155 additions and 2638 deletions

View File

@@ -8,7 +8,7 @@ head:
This module has been developed by the [NuxtLabs](https://nuxtlabs.com/) team for [Volta](https://volta.net) and [Nuxt Studio](https://nuxt.studio/), its goal is to provide everything related to UI when building a Nuxt app. This includes components, icons, colors, dark mode but also keyboard shortcuts.
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
[Volta](https://volta.net/) entire UI is built with this module alongside the 50+ keyboard shortcuts defined.
::
@@ -31,7 +31,3 @@ This module has been developed by the [NuxtLabs](https://nuxtlabs.com/) team for
- [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui)
- [vueuse/vueuse](https://github.com/vueuse/vueuse)
- [egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons)
::alert{icon="i-heroicons-exclamation-triangle"}
This documentation is still a work in progress and will be updated regularly.
::

View File

@@ -2,6 +2,8 @@
description: 'Learn how to install and configure the module in your Nuxt app.'
---
## Quick Start
1. Install `@nuxthq/ui` dependency to your project:
::code-group
@@ -30,14 +32,10 @@ export default defineNuxtConfig({
That's it! You can now use all the components and composables in your Nuxt app ✨
::alert{icon="i-heroicons-exclamation-triangle"}
::callout{icon="i-heroicons-exclamation-triangle"}
As this module installs [@nuxtjs/tailwindcss](https://tailwindcss.nuxtjs.org/) and [@nuxtjs/color-mode](https://color-mode.nuxtjs.org/) for you, you should remove them from your `modules` and `dependencies` if you've previously installed them manually.
::
## Playground
:u-button{icon="i-simple-icons-stackblitz" label="Play on StackBlitz" size="lg" to="https://stackblitz.com/edit/nuxtlabs-ui?file=app.config.ts,app.vue" target="_blank"}
## IntelliSense
If you're using VSCode, you can install the [Tailwind CSS IntelliSense](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) extension to get autocompletion for the classes.

View File

@@ -19,7 +19,7 @@ export default defineAppConfig({
})
```
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
Try to change the `primary` and `gray` colors by clicking on the :u-icon{name="i-heroicons-swatch-20-solid" class="w-4 h-4 align-middle text-primary-500 dark:text-primary-400"} button in the header.
::
@@ -29,11 +29,11 @@ To provide dynamic colors that can be changed at runtime, this module uses CSS v
Likewise, you can't define a `primary` color in your `tailwind.config.ts` as it would conflict with the `primary` color defined by the module.
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
We'd advise you to use those colors in your components and pages, e.g. `text-primary-500 dark:text-primary-400`, `bg-gray-100 dark:bg-gray-900`, etc. so your app automatically adapts when changing your `app.config.ts`.
::
Components having a `color` prop like [Avatar](/elements/avatar#chip), [Badge](/elements/badge#style), [Button](/elements/button#style), [Input](/elements/input#style) (inherited in [Select](/forms/select) and [SelectMenu](/forms/select-menu)), [Radio](/forms/radio), [Checkbox](/forms/checkbox), [Toggle](/forms/toggle), [Range](/forms/range) and [Notification](/overlays/notification#timeout) will use the `primary` 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 [Avatar](/elements/avatar#chip), [Badge](/elements/badge#style), [Button](/elements/button#style), [Input](/forms/input#style) (inherited in [Select](/forms/select) and [SelectMenu](/forms/select-menu)), [Radio](/forms/radio), [Checkbox](/forms/checkbox), [Toggle](/forms/toggle), [Range](/forms/range) and [Notification](/overlays/notification#timeout) will use the `primary` color by default but will handle all the colors defined in your `tailwind.config.ts` 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.
@@ -73,7 +73,7 @@ All the components are styled with dark mode in mind.
Thanks to [Tailwind CSS dark mode](https://tailwindcss.com/docs/dark-mode#toggling-dark-mode-manually) class strategy and the [@nuxtjs/color-mode](https://github.com/nuxt-modules/color-mode) module, you literally have nothing to do.
::alert{icon="i-heroicons-puzzle-piece"}
::callout{icon="i-heroicons-puzzle-piece"}
Learn how to build a color mode button in the [Examples](/getting-started/examples#color-mode-button) page.
::
@@ -87,7 +87,7 @@ export default defineNuxtConfig({
})
```
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
If you're stuck in dark mode even after changing this setting, you might need to remove the `nuxt-color-mode` entry from your browser's local storage.
::
@@ -115,7 +115,7 @@ Each component has a `ui` prop that allows you to customize everything specifica
</template>
```
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
You can find the default classes for each component under the `Preset` section.
::
@@ -165,7 +165,7 @@ export default defineNuxtConfig({
})
```
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
Search the icon you want to use on https://icones.js.org built by [@antfu](https://github.com/antfu).
::

View File

@@ -21,7 +21,7 @@ Shortcuts are displayed and styled through the [Kbd](/elements/kbd) component.
</template>
```
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
You will have a preview of how shortcuts are rendered in each component page.
::

View File

@@ -3,7 +3,7 @@ title: Examples
description: Discover some real-life examples of components you can build.
---
::alert{icon="i-heroicons-wrench-screwdriver"}
::callout{icon="i-heroicons-wrench-screwdriver"}
If you have any ideas of examples you'd like to see, please comment on [this issue](https://github.com/nuxtlabs/ui/issues/297).
::
@@ -153,7 +153,7 @@ padding: false
:command-palette-theme-algolia{class="max-h-[480px] rounded-md"}
::
::alert{icon="i-simple-icons-github" to="https://github.com/nuxtlabs/ui/blob/dev/docs/components/content/themes/CommandPaletteThemeAlgolia.vue#L23"}
::callout{icon="i-simple-icons-github" to="https://github.com/nuxtlabs/ui/blob/dev/docs/components/content/themes/CommandPaletteThemeAlgolia.vue#L23"}
Take a look at the component!
::
@@ -168,7 +168,7 @@ padding: false
:command-palette-theme-raycast{class="max-h-[480px] rounded-md"}
::
::alert{icon="i-simple-icons-github" to="https://github.com/nuxtlabs/ui/blob/dev/docs/components/content/themes/CommandPaletteThemeRaycast.vue#L30"}
::callout{icon="i-simple-icons-github" to="https://github.com/nuxtlabs/ui/blob/dev/docs/components/content/themes/CommandPaletteThemeRaycast.vue#L30"}
Take a look at the component!
::
@@ -261,6 +261,6 @@ Here are some examples of how components look like in RTL mode.
:pagination-example-r-t-l
::
::alert{icon="i-simple-icons-github" to="https://github.com/nuxtlabs/ui/blob/dev/docs/components/content/examples/PaginationExampleRTL.vue"}
::callout{icon="i-simple-icons-github" to="https://github.com/nuxtlabs/ui/blob/dev/docs/components/content/examples/PaginationExampleRTL.vue"}
Take a look at the component!
::

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display an image that represents a resource or a group of resources.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/elements/Avatar.vue
---
## Usage

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display a short text to represent a status or a category.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/elements/Badge.vue
---
## Usage

View File

@@ -1,6 +1,9 @@
---
github: true
description: Create a button with icon or link capabilities.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/elements/Button.vue
---
## Usage

View File

@@ -1,9 +1,12 @@
---
github: true
description: Display a list of actions in a dropdown menu.
headlessui:
label: 'Menu'
to: 'https://headlessui.com/vue/menu'
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/elements/Dropdown.vue
- label: Menu
icon: i-simple-icons-headlessui
to: https://headlessui.com/vue/menu
---
## Usage

View File

@@ -1,9 +1,12 @@
---
github: true
description: Display togglable accordion panels.
headlessui:
label: 'Disclosure'
to: 'https://headlessui.com/vue/disclosure'
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/elements/Accordion.vue
- label: Disclosure
icon: i-simple-icons-headlessui
to: 'https://headlessui.com/vue/disclosure'
navigation:
badge: 'Edge'
---

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display an icon from Iconify library.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/elements/Icon.vue
---
## Usage
@@ -12,7 +15,7 @@ props:
---
::
::alert{icon="i-heroicons-exclamation-triangle"}
::callout{icon="i-heroicons-exclamation-triangle"}
When playing with the `name` prop above, you won't be able to use any icon you want as icons are bundled on build as explained in the [theming section](/getting-started/theming#icons).
::

View File

@@ -1,7 +1,10 @@
---
github: true
title: 'Keyboard Key'
description: Display a keyboard key in a text block.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/elements/Kbd.vue
navigation:
title: 'Kbd'
---

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display an input field.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/forms/Input.vue
---
## Usage
@@ -218,7 +221,7 @@ const q = ref('')
```
::
::alert{icon="i-heroicons-exclamation-triangle-20-solid"}
::callout{icon="i-heroicons-exclamation-triangle-20-solid"}
As leading and trailing icons are wrapped around a `pointer-events-none` class, if you inject a clickable element in the slot, you need to remove this class to make it clickable by adding `:ui="{ icon: { trailing: { pointer: '' } } }"` to the Input.
::

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display a textarea field.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/forms/Textarea.vue
---
## Usage

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display a select field.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/forms/Select.vue
---
## Usage

View File

@@ -1,9 +1,12 @@
---
github: true
description: Display a select menu with advanced features.
headlessui:
label: 'Listbox'
to: 'https://headlessui.com/vue/listbox'
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/forms/SelectMenu.vue
- label: 'Listbox'
icon: i-simple-icons-headlessui
to: 'https://headlessui.com/vue/listbox'
---
## Usage
@@ -122,7 +125,7 @@ excludedProps:
---
::
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
Learn how to customize icons from the [Select](/forms/select#icon) component.
::

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display a checkbox field.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/forms/Checkbox.vue
---
## Usage

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display a radio field.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/forms/Radio.vue
---
## Usage

View File

@@ -1,9 +1,12 @@
---
github: true
description: Display a toggle field.
headlessui:
label: 'Switch'
to: 'https://headlessui.com/vue/switch'
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/forms/Toggle.vue
- label: 'Switch'
icon: i-simple-icons-headlessui
to: 'https://headlessui.com/vue/switch'
---
## Usage

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display a range field
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/forms/Range.vue
navigation:
badge: New
---

View File

@@ -1,7 +1,9 @@
---
github:
suffix: .ts
description: Display a label and additional informations around a form element.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/forms/FormGroup.ts
---
@@ -128,7 +130,7 @@ code: >-
You can also use the `error` prop as a boolean to mark the form element as invalid.
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
The `error` prop will automatically set the `color` prop of the form element to `red`.
::

View File

@@ -1,6 +1,9 @@
---
github: true
description: 'Display data in a table.'
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/data/Table.vue
---
## Usage
@@ -210,7 +213,7 @@ You can specify a default sort for the table through the `sort` prop. It's an ob
- `column` - The column to sort by.
- `direction` - The sort direction. Can be either `asc` or `desc` and defaults to `asc`.
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
This will set the default sort and will work even if no column is set as `sortable`.
::
@@ -289,7 +292,7 @@ Use the `sort-asc-icon` prop to set a different icon or change it globally in `u
Use the `sort-desc-icon` prop to set a different icon or change it globally in `ui.table.default.sortDescIcon`. Defaults to `i-heroicons-bars-arrow-down-20-solid`.
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
You can also customize the entire header cell, read more in the [Slots](#slots) section.
::
@@ -320,7 +323,7 @@ const selected = ref([people[1]])
```
::
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
You can use the `by` prop to compare objects by a field instead of comparing object instances. We've replicated the behavior of Headless UI [Combobox](https://headlessui.com/vue/combobox#binding-objects-as-values).
::
@@ -500,7 +503,7 @@ The `sort` property is an object with the following properties:
The `on-sort` property is a function that you can call to sort the table and accepts the column as parameter.
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
Even though you can customize the sort button as mentioned in the [Sortable](#sortable) section, you can use this slot to completely override its behavior, with a custom dropdown for example.
::

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display a vertical navigation.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/navigation/VerticalNavigation.vue
---
## Usage

View File

@@ -1,9 +1,12 @@
---
github: true
description: Add a customizable command palette to your app.
headlessui:
label: 'Combobox'
to: 'https://headlessui.com/vue/combobox'
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/navigation/CommandPalette.vue
- label: 'Combobox'
icon: i-simple-icons-headlessui
to: 'https://headlessui.com/vue/combobox'
---
## Usage
@@ -278,8 +281,8 @@ You can also highlight the matches in the command by setting the `fuse.fuseOptio
</template>
```
::alert{icon="i-heroicons-light-bulb"}
Try it yourself in this documentation's search by pressing :badge-shortcut{value="meta"} :badge-shortcut{value="K" class="ml-1"}.
::callout{icon="i-heroicons-light-bulb"}
Try it yourself in this documentation's search by pressing :kbd{value="meta"} :kbd{value="K" class="ml-1"}.
::
## Async search
@@ -319,7 +322,7 @@ const groups = computed(() => {
```
::
::alert{icon="i-heroicons-light-bulb"}
::callout{icon="i-heroicons-light-bulb"}
The `loading` state will automatically be enabled when a `search` function is loading. You can disable this behavior by setting the `loading-icon` prop to `null` or globally in `ui.commandPalette.default.loadingIcon`.
::

View File

@@ -1,6 +1,9 @@
---
github: true
description: Add a pagination to handle pages.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/navigation/Pagination.vue
---
## Usage

View File

@@ -1,9 +1,12 @@
---
github: true
description: Display a modal within your application.
headlessui:
label: 'Dialog'
to: 'https://headlessui.com/vue/dialog'
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/overlays/Modal.vue
- label: 'Dialog'
icon: i-simple-icons-headlessui
to: 'https://headlessui.com/vue/dialog'
---
## Usage

View File

@@ -1,9 +1,12 @@
---
github: true
description: Display a dialog that slides in from the edge of the screen.
headlessui:
label: 'Dialog'
to: 'https://headlessui.com/vue/dialog'
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/overlays/Slideover.vue
- label: 'Dialog'
icon: i-simple-icons-headlessui
to: 'https://headlessui.com/vue/dialog'
---
## Usage

View File

@@ -1,9 +1,12 @@
---
github: true
description: Display a non-modal dialog that floats around a trigger element.
headlessui:
label: 'Popover'
to: 'https://headlessui.com/vue/popover'
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/overlays/Popover.vue
- label: 'Popover'
icon: i-simple-icons-headlessui
to: 'https://headlessui.com/vue/popover'
---
## Usage

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display content that appears on hover next to an element.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/overlays/Tooltip.vue
---
## Usage

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display a menu that appears on right click.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/overlays/ContextMenu.vue
---
## Usage

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display a toast notification in your app.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/overlays/Notification.vue
---
## Usage

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display a card for content with a header, body and footer.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/layout/Card.vue
---
## Usage

View File

@@ -1,6 +1,9 @@
---
github: true
description: A container lets you center and constrain the width of your content.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/layout/Container.vue
---
## Usage

View File

@@ -1,6 +1,9 @@
---
github: true
description: Display a placeholder while content is loading.
links:
- label: GitHub
icon: i-simple-icons-github
to: https://github.com/nuxtlabs/ui/blob/dev/src/runtime/components/layout/Skeleton.vue
---
## Usage