From 37f1a1b5adc39e3f09b861ed593159016113b13e Mon Sep 17 00:00:00 2001 From: Benjamin Canac Date: Sat, 13 May 2023 23:22:07 +0200 Subject: [PATCH] docs: lots of improvements --- docs/components/content/Shortcut.vue | 20 --- docs/content/1.getting-started/1.index.md | 36 ++++ .../{1.installation.md => 2.installation.md} | 7 +- docs/content/1.getting-started/2.theming.md | 5 - docs/content/1.getting-started/3.shortcuts.md | 11 -- docs/content/1.getting-started/3.theming.md | 167 ++++++++++++++++++ docs/content/1.getting-started/4.shortcuts.md | 65 +++++++ docs/content/2.elements/3.button.md | 2 + docs/content/2.elements/5.icon.md | 20 +++ .../content/2.elements/{5.kbd.md => 6.kbd.md} | 1 + docs/content/3.forms/1.input.md | 27 +++ docs/content/3.forms/2.textarea.md | 55 ++++++ docs/content/3.forms/3.select.md | 101 ++++++++++- docs/content/3.forms/4.select-menu.md | 27 ++- docs/content/3.forms/5.checkbox.md | 59 +++++++ docs/content/3.forms/6.radio.md | 59 +++++++ .../content/4.navigation/2.command-palette.md | 2 + docs/tailwind.config.ts | 1 - 18 files changed, 605 insertions(+), 60 deletions(-) delete mode 100644 docs/components/content/Shortcut.vue create mode 100644 docs/content/1.getting-started/1.index.md rename docs/content/1.getting-started/{1.installation.md => 2.installation.md} (89%) delete mode 100644 docs/content/1.getting-started/2.theming.md delete mode 100644 docs/content/1.getting-started/3.shortcuts.md create mode 100644 docs/content/1.getting-started/3.theming.md create mode 100644 docs/content/1.getting-started/4.shortcuts.md create mode 100644 docs/content/2.elements/5.icon.md rename docs/content/2.elements/{5.kbd.md => 6.kbd.md} (98%) diff --git a/docs/components/content/Shortcut.vue b/docs/components/content/Shortcut.vue deleted file mode 100644 index f421c76d..00000000 --- a/docs/components/content/Shortcut.vue +++ /dev/null @@ -1,20 +0,0 @@ - - - diff --git a/docs/content/1.getting-started/1.index.md b/docs/content/1.getting-started/1.index.md new file mode 100644 index 00000000..98aeaffc --- /dev/null +++ b/docs/content/1.getting-started/1.index.md @@ -0,0 +1,36 @@ +--- +title: Introduction +description: 'Components library as a Nuxt module using TailwindCSS and HeadlessUI.' +--- + +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. + +Components are built on top of [TailwindCSS](https://tailwindcss.com/) and [HeadlessUI](https://headlessui.com/) to provide a set of fully customizable components with dark mode support. + +::alert{icon="i-heroicons-light-bulb"} +[Volta](https://volta.net/) entire UI is built with this module alongside the 50+ keyboard shortcuts defined. +:: + +## Features + +- Fully customizable components +- HMR support through Nuxt App Config +- Dark mode support +- Keyboard shortcuts +- Bundled icons +- Fully typed + +## Credits + +- [nuxt/nuxt](https://github.com/nuxt/nuxt) +- [nuxt-modules/color-mode](https://github.com/nuxt-modules/color-mode) +- [nuxt-modules/tailwindcss](https://github.com/nuxt-modules/tailwindcss) +- [tailwindlabs/tailwindcss](https://github.com/tailwindlabs/tailwindcss) +- [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui) +- [vueuse/vueuse](https://github.com/vueuse/vueuse) +- [egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons) +- [krisk/fuse](https://github.com/krisk/Fuse) + +::alert{icon="i-heroicons-exclamation-triangle"} +This documentation is still a work in progress and will be updated regularly. +:: diff --git a/docs/content/1.getting-started/1.installation.md b/docs/content/1.getting-started/2.installation.md similarity index 89% rename from docs/content/1.getting-started/1.installation.md rename to docs/content/1.getting-started/2.installation.md index 71698e1c..9c6d89ce 100644 --- a/docs/content/1.getting-started/1.installation.md +++ b/docs/content/1.getting-started/2.installation.md @@ -1,11 +1,8 @@ --- -title: 'nuxthq/ui' -description: 'Components library as a Nuxt module using TailwindCSS and HeadlessUI.' -navigation: - title: Installation +description: 'Learn how to install and configure the module in your Nuxt app.' --- -## Installation +## Overview 1. Install `@nuxthq/ui` dependency to your project: diff --git a/docs/content/1.getting-started/2.theming.md b/docs/content/1.getting-started/2.theming.md deleted file mode 100644 index 1c937dd9..00000000 --- a/docs/content/1.getting-started/2.theming.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -navigation: false ---- - -## Overview diff --git a/docs/content/1.getting-started/3.shortcuts.md b/docs/content/1.getting-started/3.shortcuts.md deleted file mode 100644 index dcd8fb51..00000000 --- a/docs/content/1.getting-started/3.shortcuts.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -navigation: false ---- - -## Overview - -## Composables - -## `defineShortcuts` - -## `useShortcuts` diff --git a/docs/content/1.getting-started/3.theming.md b/docs/content/1.getting-started/3.theming.md new file mode 100644 index 00000000..702a755e --- /dev/null +++ b/docs/content/1.getting-started/3.theming.md @@ -0,0 +1,167 @@ +--- +description: 'Learn how to customize the look and feel of the components.' +--- + +## Overview + +This module relies on Nuxt [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) file to customize the look and feel of the components at runtime with HMR (hot-module-replacement). + +## Colors + +Components are based on a `primary` and a `gray` color. You can change them in your `app.config.ts`. + +```ts [app.config.ts] +export default defineAppConfig({ + ui: { + primary: 'sky', + gray: 'cool' + } +}) +``` + +As this module uses TailwindCSS under the hood, you can use any of the [TailwindCSS colors](https://tailwindcss.com/docs/customizing-colors#color-palette-reference) or your own custom colors. By default, the `primary` color is `sky` and the `gray` color is `cool`. + +To provide dynamic colors that can be changed at runtime, this module uses CSS variables. As TailwindCSS already has a `gray` color, the module automatically renames it to `cool` to avoid conflicts (`coolGray` was renamed to `gray` when Tailwind CSS v3.0 was released). + +::alert{icon="i-heroicons-light-bulb"} +Try to change the `primary` and `gray` colors in the navbar and see the colors change live. +:: + +Components that have a `color` prop like [Avatar](/elements/avatar), [Badge](/elements/badge) and [Button](/elements/button) will use the `primary` color by default but will handle all the colors defined in your `tailwind.config.ts` or the default TailwindCSS colors. + +## Components + +Components are styled with TailwindCSS but classes are all defined in the default [app.config.ts](https://github.com/nuxtlabs/ui/blob/dev/src/runtime/app.config.ts) file. You can override them in your `app.config.ts`. + +```ts [app.config.ts] +export default defineAppConfig({ + ui: { + container: { + constrained: 'max-w-5xl' + } + } +}) +``` + +Each component has a `ui` prop that allows you to customize everything specifically. + +```vue + +``` + +::alert{icon="i-heroicons-light-bulb"} +You can find the default classes for each component under the `Preset` section. +:: + +Some component props like `size`, `color`, `variant`, etc. have a default value that you can override in your `app.config.ts`. + +```ts [app.config.ts] +export default defineAppConfig({ + ui: { + button: { + default: { + size: 'md', + color: 'gray', + variant: 'ghost' + } + } + } +}) +``` + +## Icons + +You can use any icon (100,000+) from [Iconify](https://iconify.design/). + +Most of the components have an `icon` prop that allows you to add an icon to the component. + +```vue + +``` + +You can also use the [Icon](/elements/icon) component to add an icon anywhere in your app by following this pattern: `i-{collection_name}-{icon_name}`. + +```vue + +``` + +By default, the module uses [Heroicons](https://heroicons.com/) but you can change it from the module options in your `nuxt.config.ts`. + +```ts [nuxt.config.ts] +export default defineNuxtConfig({ + ui: { + icons: ['mdi', 'simple-icons'] + } +}) +``` + +::alert{icon="i-heroicons-light-bulb"} +Search the icon you want to use on https://icones.js.org built by [@antfu](https://github.com/antfu). +:: + +Unlike the official [nuxt-icon](https://github.com/nuxt-modules/icon/) module, this module will not fetch any icon from the web and will only bundle the icons you use in your app thanks to [egoist/tailwindcss-icons](https://github.com/egoist/tailwindcss-icons). + +However, you will need to install the icon packages you want to use. + +```sh +yarn add --dev @iconify/json-{collection_name} +``` + +You can easily replace all the default icons of the components in your `app.config.ts`. + +```ts [app.config.ts] +export default defineAppConfig({ + ui: { + button: { + default: { + loadingIcon: 'i-octicon-sync-24' + } + }, + input: { + default: { + loadingIcon: 'i-octicon-sync-24' + } + }, + select: { + default: { + trailingIcon: 'i-octicon-chevron-down-24' + } + }, + selectMenu: { + default: { + selectedIcon: 'i-octicon-check-24' + } + }, + notification: { + default: { + close: { + icon: 'i-octicon-x-24' + } + } + }, + commandPalette: { + default: { + icon: 'i-octicon-search-24', + selectedIcon: 'i-octicon-check-24', + empty: { + icon: 'i-octicon-search-24' + } + } + } + } +}) +``` + +## Dark mode + +All the components are styled with dark mode in mind. + +Thanks to [TailwindCSS 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. diff --git a/docs/content/1.getting-started/4.shortcuts.md b/docs/content/1.getting-started/4.shortcuts.md new file mode 100644 index 00000000..b325b420 --- /dev/null +++ b/docs/content/1.getting-started/4.shortcuts.md @@ -0,0 +1,65 @@ +--- +description: 'Learn how to display and define keyboard shortcuts in your app.' +--- + +## Overview + +Some components like [Dropdown](/elements/dropdown), [Command Palette](/navigation/command-palette) and [Tooltip](/overlays/tooltip) support the display of keyboard shortcuts. + +```vue + +``` + +Shortcuts are displayed and styled through the [Kbd](/elements/kbd) component. + +```vue + +``` + +::alert{icon="i-heroicons-light-bulb"} +You will have a preview of how shortcuts are rendered in each component page. +:: + +## Composables + +### `defineShortcuts` + +This module provides a `defineShortcuts` composable that allows you to define keyboard shortcuts in your app really easily. + +```vue + + + +``` + +### `useShortcuts` + +To display shortcuts in your app according to the user's OS, you can use the `useShortcuts` composable. + +```vue + + + +``` diff --git a/docs/content/2.elements/3.button.md b/docs/content/2.elements/3.button.md index 9848fdf7..090d01c5 100644 --- a/docs/content/2.elements/3.button.md +++ b/docs/content/2.elements/3.button.md @@ -161,6 +161,8 @@ Button Use the `loading` prop to show a loading icon and disable the Button. +Use the `loadingIcon` prop to set a different icon or change it globally in `ui.button.default.loadingIcon`. Defaults to `i-heroicons-arrow-path-20-solid`. + ::component-card --- props: diff --git a/docs/content/2.elements/5.icon.md b/docs/content/2.elements/5.icon.md new file mode 100644 index 00000000..dfaa6fa2 --- /dev/null +++ b/docs/content/2.elements/5.icon.md @@ -0,0 +1,20 @@ +--- +github: true +--- + +## Usage + +::component-card +--- +props: + name: 'i-heroicons-light-bulb' +--- +:: + +::alert{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). +:: + +## Props + +:component-props diff --git a/docs/content/2.elements/5.kbd.md b/docs/content/2.elements/6.kbd.md similarity index 98% rename from docs/content/2.elements/5.kbd.md rename to docs/content/2.elements/6.kbd.md index ee4722a8..231ff3c7 100644 --- a/docs/content/2.elements/5.kbd.md +++ b/docs/content/2.elements/6.kbd.md @@ -34,6 +34,7 @@ Use the `size` prop to change the size of the Kbd. --- props: size: 'sm' +code: 'U' --- U diff --git a/docs/content/3.forms/1.input.md b/docs/content/3.forms/1.input.md index 8db6525d..aa363c80 100644 --- a/docs/content/3.forms/1.input.md +++ b/docs/content/3.forms/1.input.md @@ -24,6 +24,31 @@ props: --- :: +### Placeholder + +::component-card +--- +baseProps: + name: 'input' +props: + placeholder: 'Search...' +--- +:: + +### Appearance + +Use the `appearance` prop to change the style of the Input. + +::component-card +--- +baseProps: + name: 'input' + placeholder: 'Search...' +props: + appearance: 'white' +--- +:: + ### Icon Use any icon from [Iconify](https://icones.js.org) by setting the `icon` prop by using this pattern: `i-{collection_name}-{icon_name}`. @@ -67,6 +92,8 @@ excludedProps: Use the `loading` prop to show a loading icon and disable the Input. +Use the `loadingIcon` prop to set a different icon or change it globally in `ui.input.default.loadingIcon`. Defaults to `i-heroicons-arrow-path-20-solid`. + ::component-card --- baseProps: diff --git a/docs/content/3.forms/2.textarea.md b/docs/content/3.forms/2.textarea.md index 1bdd3df9..d65156e2 100644 --- a/docs/content/3.forms/2.textarea.md +++ b/docs/content/3.forms/2.textarea.md @@ -11,6 +11,61 @@ baseProps: --- :: +### Size + +Use the `size` prop to change the size of the Input. + +::component-card +--- +baseProps: + name: 'textarea' +props: + size: 'sm' +--- +:: + +### Placeholder + +::component-card +--- +baseProps: + name: 'textarea' +props: + placeholder: 'Search...' +--- +:: + +### Appearance + +Use the `appearance` prop to change the style of the Input. + +::component-card +--- +baseProps: + name: 'textarea' + placeholder: 'Search...' +props: + appearance: 'white' +--- +:: + +### Disabled + +Use the `disabled` prop to disable the Input. + +::component-card +--- +baseProps: + name: 'input' +props: + placeholder: 'Search...' + appearance: 'white' + disabled: true +excludedProps: + - placeholder +--- +:: + ## Props :component-props diff --git a/docs/content/3.forms/3.select.md b/docs/content/3.forms/3.select.md index f4a4f8c7..ff6e1d7d 100644 --- a/docs/content/3.forms/3.select.md +++ b/docs/content/3.forms/3.select.md @@ -8,11 +8,110 @@ github: true --- baseProps: name: 'select' - modelValue: 'Canada' + modelValue: 'United States' +props: options: - 'United States' - 'Canada' - 'Mexico' +excludedProps: + - options +--- +:: + +### Size + +Use the `size` prop to change the size of the Input. + +::component-card +--- +baseProps: + name: 'select' + options: + - 'United States' + - 'Canada' + - 'Mexico' +props: + size: 'sm' +--- +:: + +### Placeholder + +::component-card +--- +baseProps: + name: 'select' + options: + - 'United States' + - 'Canada' + - 'Mexico' +props: + placeholder: 'Search...' +--- +:: + +### Appearance + +Use the `appearance` prop to change the style of the Select. + +::component-card +--- +baseProps: + name: 'select' + options: + - 'United States' + - 'Canada' + - 'Mexico' + placeholder: 'Search...' +props: + appearance: 'white' +--- +:: + +### Icon + +Use any icon from [Iconify](https://icones.js.org) by setting the `icon` prop by using this pattern: `i-{collection_name}-{icon_name}`. + +Use the `trailingIcon` prop to set a different icon or change it globally in `ui.select.default.trailingIcon`. Defaults to `i-heroicons-chevron-down-20-solid`. + +::component-card +--- +baseProps: + name: 'select' + options: + - 'United States' + - 'Canada' + - 'Mexico' +props: + icon: 'i-heroicons-magnifying-glass-20-solid' + appearance: 'white' + size: 'sm' + placeholder: 'Search...' +excludedProps: + - icon + - placeholder +--- +:: + +### Disabled + +Use the `disabled` prop to disable the Input. + +::component-card +--- +baseProps: + name: 'select' + options: + - 'United States' + - 'Canada' + - 'Mexico' +props: + placeholder: 'Search...' + appearance: 'white' + disabled: true +excludedProps: + - placeholder --- :: diff --git a/docs/content/3.forms/4.select-menu.md b/docs/content/3.forms/4.select-menu.md index 9a727419..32ae9734 100644 --- a/docs/content/3.forms/4.select-menu.md +++ b/docs/content/3.forms/4.select-menu.md @@ -7,6 +7,10 @@ headlessui: ## Usage +The SelectMenu component renders by default a [Select](/forms/select) component and is based on the `ui.select` preset. You can use most of the Select props to configure the display if you don't want to override the default slot such as [size](/forms/select#size), [placeholder](/forms/select#placeholder), [appearance](/forms/select#appearance), [icon](/forms/select#icon), [disabled](/forms/select#disabled), etc. + +Like the Select component, you can use the `options` prop to pass an array of strings or objects. + ::component-example #default :select-menu-example-basic{class="max-w-[12rem] w-full"} @@ -25,7 +29,7 @@ const selected = ref(people[0]) ``` :: -You can use multiple values but you have to override the `#label` slot and handle the display yourself. +You can use the `multiple` prop to select multiple values but you have to override the `#label` slot and handle the display yourself. ::component-example #default @@ -76,7 +80,7 @@ const selected = ref(people[3]) ``` :: -You can pass an array of objects to `options` and either compare on the whole object or use the `by` prop to compare on a specific key. +You can pass an array of objects to `options` and either compare on the whole object or use the `by` prop to compare on a specific key. You can configure which field will be used to display the label through the `optionAttribute` prop that defaults to `label`. ::component-example #default @@ -131,6 +135,10 @@ const selected = ref(people[0]) Use any icon from [Iconify](https://icones.js.org) by setting the `icon` prop by using this pattern: `i-{collection_name}-{icon_name}`. +Use the `trailingIcon` prop to set a different icon or change it globally in `ui.select.default.trailingIcon`. Defaults to `i-heroicons-chevron-down-20-solid`. + +Use the `selectedIcon` prop to set a different icon or change it globally in `ui.selectMenu.default.selectedIcon`. Defaults to `i-heroicons-check-20-solid`. + ::component-card --- baseProps: @@ -161,21 +169,6 @@ props: --- :: -### Disabled - -Use the `disabled` prop to disable the SelectMenu. - -::component-card ---- -baseProps: - class: 'max-w-[12rem] w-full' - placeholder: 'Select a person' - options: ['Wade Cooper', 'Arlene Mccoy', 'Devon Webb', 'Tom Cook', 'Tanya Fox', 'Hellen Schmidt', 'Caroline Schultz', 'Mason Heaney', 'Claudie Smitham', 'Emil Schaefer'] -props: - disabled: true ---- -:: - ## Props :component-props diff --git a/docs/content/3.forms/5.checkbox.md b/docs/content/3.forms/5.checkbox.md index f4cdd031..81a5dc68 100644 --- a/docs/content/3.forms/5.checkbox.md +++ b/docs/content/3.forms/5.checkbox.md @@ -5,6 +5,65 @@ github: true ## Usage ::component-card +--- +baseProps: + name: 'checkbox' +--- +:: + +### Label + +Use the `label` prop to display a label on the right. + +::component-card +--- +baseProps: + name: 'checkbox1' +props: + label: 'Label' +--- +:: + +### Required + +Use the `required` prop to display a red star next to the label. + +::component-card +--- +baseProps: + name: 'checkbox2' +props: + label: 'Label' + required: true +--- +:: + +### Help + +Use the `help` prop to display some text under the Checkbox. + +::component-card +--- +baseProps: + name: 'checkbox3' +props: + label: 'Label' + help: 'Please check this box' +--- +:: + +### Disabled + +Use the `disabled` prop to disable the Checkbox. + +::component-card +--- +baseProps: + name: 'checkbox4' + modelValue: true +props: + disabled: true +--- :: ## Props diff --git a/docs/content/3.forms/6.radio.md b/docs/content/3.forms/6.radio.md index f4cdd031..13ec7927 100644 --- a/docs/content/3.forms/6.radio.md +++ b/docs/content/3.forms/6.radio.md @@ -5,6 +5,65 @@ github: true ## Usage ::component-card +--- +baseProps: + name: 'radio' +--- +:: + +### Label + +Use the `label` prop to display a label on the right. + +::component-card +--- +baseProps: + name: 'radio1' +props: + label: 'Label' +--- +:: + +### Required + +Use the `required` prop to display a red star next to the label. + +::component-card +--- +baseProps: + name: 'radio2' +props: + label: 'Label' + required: true +--- +:: + +### Help + +Use the `help` prop to display some text under the Radio. + +::component-card +--- +baseProps: + name: 'radio3' +props: + label: 'Label' + help: 'Please choose one' +--- +:: + +### Disabled + +Use the `disabled` prop to disable the Radio. + +::component-card +--- +baseProps: + name: 'radio4' + value: true +props: + disabled: true +--- :: ## Props diff --git a/docs/content/4.navigation/2.command-palette.md b/docs/content/4.navigation/2.command-palette.md index b97b4370..65ac2ef6 100644 --- a/docs/content/4.navigation/2.command-palette.md +++ b/docs/content/4.navigation/2.command-palette.md @@ -159,6 +159,8 @@ function onSelect (option) { Use any icon from [Iconify](https://icones.js.org) by setting the `icon` prop by using this pattern: `i-{collection_name}-{icon_name}`. +Use the `selectedIcon` prop to set a different icon or change it globally in `ui.commandPalette.default.selectedIcon`. Defaults to `i-heroicons-check-20-solid`. + ::component-card --- padding: false diff --git a/docs/tailwind.config.ts b/docs/tailwind.config.ts index 836b5a84..21f9a3d3 100644 --- a/docs/tailwind.config.ts +++ b/docs/tailwind.config.ts @@ -2,7 +2,6 @@ import type { Config } from 'tailwindcss' import defaultTheme from 'tailwindcss/defaultTheme' export default > { - darkMode: 'class', content: [ 'docs/content/**/*.md' ],