diff --git a/.vscode/settings.json b/.vscode/settings.json index 47b2103f..c9442fbf 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -1,4 +1,5 @@ { + "vue.server.hybridMode": true, "eslint.experimental.useFlatConfig": true, "prettier.enable": false, "editor.formatOnSave": false, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 31bf7db9..8970fe1c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,7 @@ This repository is structured as follows: ``` apps └── www - ├── src + ├── src │ └── content └── registry ├── default @@ -32,12 +32,12 @@ packages └── cli ``` -| Path | Description | -| --------------------- | ---------------------------------------- | -| `apps/www/app` | The Next.js application for the website. | -| `apps/www/content` | The content for the website. | -| `apps/www/registry` | The registry for the components. | -| `packages/cli` | The `shadcn-vue` package. | +| Path | Description | +| ----------------------------| -------------------------------------------| +| `apps/www/.vitepress` | The Vitepress application for the website. | +| `apps/www/src/content` | The content for the website. | +| `apps/www/src/lib/registry` | The registry for the components. | +| `packages/cli` | The `shadcn-vue` package. | ## Development @@ -79,22 +79,24 @@ The documentation for this project is located in the `www` workspace. You can ru pnpm dev ``` -Documentation is written using [md](https://vitepress.dev/guide/markdown). You can find the documentation files in the `apps/www/content/docs` directory. +Documentation is written using [md](https://vitepress.dev/guide/markdown). You can find the documentation files in the `apps/www/src/content` directory. ## Components -We use a registry system for developing components. You can find the source code for the components under `apps/www/registry`. The components are organized by styles. +We use a registry system for developing components. You can find the source code for the components under `apps/www/src/lib/registry`. The components are organized by styles. ```bash apps └── www - └── registry - ├── default - │ ├── example - │ └── ui - └── new-york - ├── example - └── ui + └── src + └── lib + └── registry + ├── default + │ ├── example + │ └── ui + └── new-york + ├── example + └── ui ``` When adding or modifying components, please ensure that: @@ -130,13 +132,10 @@ the following categories: e.g. `feat(components): add new prop to the avatar component` - If you are interested in the detailed specification you can visit https://www.conventionalcommits.org/ or check out the [Angular Commit Message Guidelines](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines). - - ## Requests for new components If you have a request for a new component, please open a discussion on GitHub. We'll be happy to help you out. @@ -155,4 +154,4 @@ Tests are written using [Vitest](https://vitest.dev). You can run all the tests pnpm test ``` -Please ensure that the tests are passing when submitting a pull request. If you're adding new features, please include tests. \ No newline at end of file +Please ensure that the tests are passing when submitting a pull request. If you're adding new features, please include tests. diff --git a/apps/www/.vitepress/config.mts b/apps/www/.vitepress/config.mts index 69ffd5f9..d729444e 100644 --- a/apps/www/.vitepress/config.mts +++ b/apps/www/.vitepress/config.mts @@ -3,16 +3,12 @@ import { defineConfig } from 'vitepress' import Icons from 'unplugin-icons/vite' import tailwind from 'tailwindcss' import autoprefixer from 'autoprefixer' -import { createCssVariablesTheme } from 'shiki' +import { cssVariables } from './theme/config/shiki' // import { transformerMetaWordHighlight, transformerNotationWordHighlight } from '@shikijs/transformers' import { siteConfig } from './theme/config/site' import ComponentPreviewPlugin from './theme/plugins/previewer' - -const cssVariables = createCssVariablesTheme({ - variablePrefix: '--shiki-', - variableDefaults: {}, -}) +import CodeWrapperPlugin from './theme/plugins/codewrapper' // https://vitepress.dev/reference/site-config export default defineConfig({ @@ -65,6 +61,7 @@ export default defineConfig({ ], config(md) { md.use(ComponentPreviewPlugin) + md.use(CodeWrapperPlugin) }, }, rewrites: { diff --git a/apps/www/.vitepress/theme/components/CodeConfigCustomizer.vue b/apps/www/.vitepress/theme/components/CodeConfigCustomizer.vue new file mode 100644 index 00000000..fa85049a --- /dev/null +++ b/apps/www/.vitepress/theme/components/CodeConfigCustomizer.vue @@ -0,0 +1,98 @@ + + + diff --git a/apps/www/.vitepress/theme/components/CodeSandbox.vue b/apps/www/.vitepress/theme/components/CodeSandbox.vue index 8b55d399..56bfb25c 100644 --- a/apps/www/.vitepress/theme/components/CodeSandbox.vue +++ b/apps/www/.vitepress/theme/components/CodeSandbox.vue @@ -1,10 +1,10 @@ ``` - diff --git a/apps/www/src/content/docs/components/alert-dialog.md b/apps/www/src/content/docs/components/alert-dialog.md index 73ea6da1..c53aeab4 100644 --- a/apps/www/src/content/docs/components/alert-dialog.md +++ b/apps/www/src/content/docs/components/alert-dialog.md @@ -1,21 +1,18 @@ --- title: Alert Dialog description: A modal dialog that interrupts the user with important content and expects a response. -source: apps/www/src/lib/registry/default/ui/alert-dialog +source: apps/www/src/lib/registry/default/ui/alert-dialog primitive: https://www.radix-vue.com/components/alert-dialog.html --- - - - - -## Installation - + + +## Installation ```bash npx shadcn-vue@latest add alert-dialog ``` - + ## Usage ```vue @@ -51,4 +48,4 @@ import { -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/alert.md b/apps/www/src/content/docs/components/alert.md index 13d9d609..0e0c7ad6 100644 --- a/apps/www/src/content/docs/components/alert.md +++ b/apps/www/src/content/docs/components/alert.md @@ -3,16 +3,14 @@ title: Alert description: Displays a callout for user attention. --- - - + ## Installation - ```bash npx shadcn-vue@latest add alert ``` - + ## Usage ```vue @@ -34,11 +32,8 @@ import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert' ### Default - - + ### Destructive - - - + diff --git a/apps/www/src/content/docs/components/aspect-ratio.md b/apps/www/src/content/docs/components/aspect-ratio.md index ec6475d9..57ec62a7 100644 --- a/apps/www/src/content/docs/components/aspect-ratio.md +++ b/apps/www/src/content/docs/components/aspect-ratio.md @@ -1,11 +1,10 @@ --- title: Aspect Ratio description: Displays content within a desired ratio. -source: apps/www/src/lib/registry/default/ui/aspect-ratio +source: apps/www/src/lib/registry/default/ui/aspect-ratio primitive: https://www.radix-vue.com/components/aspect-ratio.html --- - ## Installation @@ -51,4 +50,4 @@ import { AspectRatio } from '@/components/ui/aspect-ratio' -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/avatar.md b/apps/www/src/content/docs/components/avatar.md index 0f1dbdef..ae7668fd 100644 --- a/apps/www/src/content/docs/components/avatar.md +++ b/apps/www/src/content/docs/components/avatar.md @@ -1,20 +1,17 @@ --- title: Avatar description: An image element with a fallback for representing the user. -source: apps/www/src/lib/registry/default/ui/avatar +source: apps/www/src/lib/registry/default/ui/avatar primitive: https://www.radix-vue.com/components/avatar.html --- - - - + ## Installation - ```bash npx shadcn-vue@latest add avatar -``` +``` ## Usage @@ -29,4 +26,4 @@ import { Avatar, AvatarFallback, AvatarImage } from '@/components/ui/avatar' CN -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/badge.md b/apps/www/src/content/docs/components/badge.md index 08b8b030..714ba2cb 100644 --- a/apps/www/src/content/docs/components/badge.md +++ b/apps/www/src/content/docs/components/badge.md @@ -3,8 +3,7 @@ title: Badge description: Displays a badge or a component that looks like a badge. --- - - + ## Installation @@ -80,13 +79,11 @@ import { Badge } from '@/components/ui/badge' ``` - ## Examples ### Default - - + ### Secondary @@ -98,4 +95,4 @@ import { Badge } from '@/components/ui/badge' ### Destructive - \ No newline at end of file + diff --git a/apps/www/src/content/docs/components/breadcrumb.md b/apps/www/src/content/docs/components/breadcrumb.md new file mode 100644 index 00000000..c4b0d534 --- /dev/null +++ b/apps/www/src/content/docs/components/breadcrumb.md @@ -0,0 +1,205 @@ +--- +title: Breadcrumb +description: Displays the path to the current resource using a hierarchy of links. +--- + + + +## Installation + +```bash +npx shadcn-vue@latest add breadcrumb +``` + +## Usage + +```vue + + + +``` + +## Examples + +### Custom separator + +Use a custom component as `slot` for `` to create a custom separator. + + + +```vue showLineNumbers {2,20-22} + + + +``` + +--- + +### Dropdown + +You can compose `` with a `` to create a dropdown in the breadcrumb. + + + +```vue showLineNumbers {2-7,16-26} + + + +``` + +--- + +### Collapsed + +We provide a `` component to show a collapsed state when the breadcrumb is too long. + + + +```vue showLineNumbers {3,15} + + + +``` + +--- + +### Link component + +To use a custom link component from your routing library, you can use the `asChild` prop on ``. + + + +```vue showLineNumbers {15-19} + + + +``` + +--- + +### Responsive + +Here's an example of a responsive breadcrumb that composes `` with ``, ``, and ``. + +It displays a dropdown on desktop and a drawer on mobile. + + diff --git a/apps/www/src/content/docs/components/button.md b/apps/www/src/content/docs/components/button.md index 3fb5d55e..d02a5357 100644 --- a/apps/www/src/content/docs/components/button.md +++ b/apps/www/src/content/docs/components/button.md @@ -3,8 +3,7 @@ title: Button description: Displays a button or a component that looks like a button. --- - - + ## Installation @@ -94,24 +93,20 @@ import { Button } from '@/components/ui/button' ``` - ## Examples ### Primary - - + ### Secondary - ### Destructive - ### Outline @@ -138,4 +133,4 @@ import { Button } from '@/components/ui/button' ### As Child - \ No newline at end of file + diff --git a/apps/www/src/content/docs/components/calendar.md b/apps/www/src/content/docs/components/calendar.md index ab0dff47..416aa0f8 100644 --- a/apps/www/src/content/docs/components/calendar.md +++ b/apps/www/src/content/docs/components/calendar.md @@ -1,12 +1,11 @@ --- title: Calendar description: A date field component that allows users to enter and edit date. -source: apps/www/src/lib/registry/default/ui/calendar +source: apps/www/src/lib/registry/default/ui/calendar primitive: https://vcalendar.io/ --- - - + ## About @@ -34,13 +33,10 @@ npm install v-calendar ### Copy and paste the following code into your project - <<< @/lib/registry/default/ui/calendar/Calendar.vue - - @@ -92,4 +88,4 @@ import { Calendar } from '@/components/ui/calendar' -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/card.md b/apps/www/src/content/docs/components/card.md index 512d1761..dd11d35c 100644 --- a/apps/www/src/content/docs/components/card.md +++ b/apps/www/src/content/docs/components/card.md @@ -3,16 +3,13 @@ title: Card description: Displays a card with header, content, and footer. --- - - + ## Installation - - ```bash npx shadcn-vue@latest add card -``` +``` ## Usage @@ -46,4 +43,4 @@ import { ## Examples - \ No newline at end of file + diff --git a/apps/www/src/content/docs/components/checkbox.md b/apps/www/src/content/docs/components/checkbox.md index 07697e6e..283d1fe4 100644 --- a/apps/www/src/content/docs/components/checkbox.md +++ b/apps/www/src/content/docs/components/checkbox.md @@ -1,20 +1,17 @@ --- title: Checkbox description: A control that allows the user to toggle between checked and not checked. -source: apps/www/src/lib/registry/default/ui/checkbox +source: apps/www/src/lib/registry/default/ui/checkbox primitive: https://www.radix-vue.com/components/checkbox.html --- - - - + ## Installation - ```bash npx shadcn-vue@latest add checkbox -``` +``` ## Usage diff --git a/apps/www/src/content/docs/components/collapsible.md b/apps/www/src/content/docs/components/collapsible.md index 19f32739..185601d4 100644 --- a/apps/www/src/content/docs/components/collapsible.md +++ b/apps/www/src/content/docs/components/collapsible.md @@ -1,23 +1,21 @@ ---- +--- title: Collapsible description: An interactive component which expands/collapses a panel. -source: apps/www/src/lib/registry/default/ui/collapsible +source: apps/www/src/lib/registry/default/ui/collapsible primitive: https://www.radix-vue.com/components/collapsible.html --- - - + ## Installation - ### Run the following command ```bash npx shadcn-vue@latest add collapsible -``` +``` ### Update `tailwind.config.js` @@ -46,9 +44,8 @@ module.exports = { }, } ``` - - + ## Usage @@ -73,4 +70,4 @@ const isOpen = ref(false) -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/command.md b/apps/www/src/content/docs/components/command.md index eb77f9b6..f059004d 100644 --- a/apps/www/src/content/docs/components/command.md +++ b/apps/www/src/content/docs/components/command.md @@ -1,21 +1,17 @@ --- title: Command description: Fast, composable, unstyled command menu. -source: apps/www/src/lib/registry/default/ui/command +source: apps/www/src/lib/registry/default/ui/command primitive: https://www.radix-vue.com/components/combobox.html --- - - - - + ## Installation - ```bash npx shadcn-vue@latest add command -``` +``` ## Usage ```vue @@ -66,9 +62,9 @@ import { ``` -## Examples +## Examples -### Dialog +### Dialog diff --git a/apps/www/src/content/docs/components/context-menu.md b/apps/www/src/content/docs/components/context-menu.md index 13bc11ec..cc718ce8 100644 --- a/apps/www/src/content/docs/components/context-menu.md +++ b/apps/www/src/content/docs/components/context-menu.md @@ -1,18 +1,17 @@ ---- +--- title: Context Menu description: Displays a menu to the user — such as a set of actions or functions — triggered by a button. -source: apps/www/src/lib/registry/default/ui/context-menu +source: apps/www/src/lib/registry/default/ui/context-menu primitive: https://www.radix-vue.com/components/context-menu.html --- - - + ## Installation - + ```bash npx shadcn-vue@latest add context-menu -``` +``` ## Usage @@ -46,4 +45,4 @@ import { -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/date-picker.md b/apps/www/src/content/docs/components/date-picker.md index 3fbdc563..7416c51c 100644 --- a/apps/www/src/content/docs/components/date-picker.md +++ b/apps/www/src/content/docs/components/date-picker.md @@ -3,8 +3,7 @@ title: Date Picker description: A date picker component with range and presets. --- - - + ## Installation @@ -53,7 +52,6 @@ const date = ref() ``` - ## Examples ### Date Picker diff --git a/apps/www/src/content/docs/components/dialog.md b/apps/www/src/content/docs/components/dialog.md index 5c407e19..de448dbb 100644 --- a/apps/www/src/content/docs/components/dialog.md +++ b/apps/www/src/content/docs/components/dialog.md @@ -1,13 +1,12 @@ --- title: Dialog description: A window overlaid on either the primary window or another dialog window, rendering the content underneath inert. -source: apps/www/src/lib/registry/default/ui/dialog +source: apps/www/src/lib/registry/default/ui/dialog primitive: https://www.radix-vue.com/components/dialog.html --- + - - ## Installation ```bash npx shadcn-vue@latest add dialog @@ -49,11 +48,11 @@ import { ``` -## Examples +## Examples ### Custom close button - + ### Scroll body @@ -67,7 +66,6 @@ import { To activate the `Dialog` component from within a `Context Menu` or `Dropdown Menu`, you must encase the `Context Menu` or `Dropdown Menu` component in the `Dialog` component. For more information, refer to the linked issue [here](https://github.com/radix-ui/primitives/issues/1836). - ```js:line-numbers showLineNumber{14-25} diff --git a/apps/www/src/content/docs/components/hover-card.md b/apps/www/src/content/docs/components/hover-card.md index 6d58163d..0b45e115 100644 --- a/apps/www/src/content/docs/components/hover-card.md +++ b/apps/www/src/content/docs/components/hover-card.md @@ -1,18 +1,17 @@ --- title: Hover Card description: For sighted users to preview content available behind a link. -source: apps/www/src/lib/registry/default/ui/hover-card +source: apps/www/src/lib/registry/default/ui/hover-card primitive: https://www.radix-vue.com/components/hover-card.html --- - - + ## Installation ```bash npx shadcn-vue@latest add hover-card -``` +``` ## Usage ```vue @@ -32,4 +31,4 @@ import { -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/label.md b/apps/www/src/content/docs/components/label.md index 9d2535c2..31d1b89a 100644 --- a/apps/www/src/content/docs/components/label.md +++ b/apps/www/src/content/docs/components/label.md @@ -1,12 +1,11 @@ --- title: Label description: Renders an accessible label associated with controls. -source: apps/www/src/lib/registry/default/ui/label +source: apps/www/src/lib/registry/default/ui/label primitive: https://www.radix-vue.com/components/label.html --- - - + ## Installation @@ -47,4 +46,4 @@ import { Label } from '@/components/ui/label' -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/menubar.md b/apps/www/src/content/docs/components/menubar.md index 8c856d82..0ecd6876 100644 --- a/apps/www/src/content/docs/components/menubar.md +++ b/apps/www/src/content/docs/components/menubar.md @@ -1,14 +1,13 @@ --- title: Menubar description: A visually persistent menu common in desktop applications that provides quick access to a consistent set of commands. -source: apps/www/src/lib/registry/default/ui/menubar +source: apps/www/src/lib/registry/default/ui/menubar primitive: https://www.radix-vue.com/components/menubar.html --- - + ## Installation - ```bash npx shadcn-vue@latest add menubar @@ -46,4 +45,4 @@ import { -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/navigation-menu.md b/apps/www/src/content/docs/components/navigation-menu.md index e8530cf6..f1748f57 100644 --- a/apps/www/src/content/docs/components/navigation-menu.md +++ b/apps/www/src/content/docs/components/navigation-menu.md @@ -1,13 +1,13 @@ --- title: Navigation Menu description: A collection of links for navigating websites. -source: apps/www/src/lib/registry/default/ui/navigation-menu +source: apps/www/src/lib/registry/default/ui/navigation-menu primitive: https://www.radix-vue.com/components/navigation-menu.html --- - + -## Installation +## Installation ```bash npx shadcn-vue@latest add navigation-menu @@ -43,7 +43,7 @@ import { ``` -## Examples +## Examples ### Link Component @@ -64,4 +64,3 @@ import { navigationMenuTriggerStyle } from '@/components/ui/navigation-menu' ``` - diff --git a/apps/www/src/content/docs/components/pagination.md b/apps/www/src/content/docs/components/pagination.md index 16d1429f..cdc75bce 100644 --- a/apps/www/src/content/docs/components/pagination.md +++ b/apps/www/src/content/docs/components/pagination.md @@ -5,15 +5,14 @@ source: apps/www/src/lib/registry/default/ui/pagination primitive: https://www.radix-vue.com/components/pagination.html --- - + ## Installation - ```bash npx shadcn-vue@latest add pagination ``` - + ## Usage ```vue diff --git a/apps/www/src/content/docs/components/popover.md b/apps/www/src/content/docs/components/popover.md index 4a19b82e..78263750 100644 --- a/apps/www/src/content/docs/components/popover.md +++ b/apps/www/src/content/docs/components/popover.md @@ -1,16 +1,14 @@ --- title: Popover description: Displays rich content in a portal, triggered by a button. -source: apps/www/src/lib/registry/default/ui/popover +source: apps/www/src/lib/registry/default/ui/popover primitive: https://www.radix-vue.com/components/popover.html --- - - + ## Installation - ```bash npx shadcn-vue@latest add popover ``` @@ -34,4 +32,4 @@ import { -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/progress.md b/apps/www/src/content/docs/components/progress.md index bb1515a6..98afe907 100644 --- a/apps/www/src/content/docs/components/progress.md +++ b/apps/www/src/content/docs/components/progress.md @@ -1,13 +1,11 @@ --- title: Progress description: Displays an indicator showing the completion progress of a task, typically displayed as a progress bar. -source: apps/www/src/lib/registry/default/ui/progress +source: apps/www/src/lib/registry/default/ui/progress primitive: https://www.radix-vue.com/components/progress.html --- - - - + ## Installation @@ -48,4 +46,4 @@ import { Progress } from '@/components/ui/progress' -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/radio-group.md b/apps/www/src/content/docs/components/radio-group.md index 9dbbabbf..dc6b3a2c 100644 --- a/apps/www/src/content/docs/components/radio-group.md +++ b/apps/www/src/content/docs/components/radio-group.md @@ -1,15 +1,14 @@ --- title: Radio Group description: A set of checkable buttons—known as radio buttons—where no more than one of the buttons can be checked at a time. -source: apps/www/src/lib/registry/default/ui/radio-group +source: apps/www/src/lib/registry/default/ui/radio-group primitive: https://www.radix-vue.com/components/radio-group.html --- - + ## Installation - ```bash npx shadcn-vue@latest add radio-group ``` diff --git a/apps/www/src/content/docs/components/resizable.md b/apps/www/src/content/docs/components/resizable.md index bfed171f..b2f4c357 100644 --- a/apps/www/src/content/docs/components/resizable.md +++ b/apps/www/src/content/docs/components/resizable.md @@ -84,7 +84,7 @@ import { @@ -48,4 +46,4 @@ import { Separator } from '@/components/ui/separator' -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/sheet.md b/apps/www/src/content/docs/components/sheet.md index 6d2e90ac..4447d310 100644 --- a/apps/www/src/content/docs/components/sheet.md +++ b/apps/www/src/content/docs/components/sheet.md @@ -1,15 +1,14 @@ --- title: Sheet description: Extends the Dialog component to display content that complements the main content of the screen. -source: apps/www/src/lib/registry/default/ui/sheet +source: apps/www/src/lib/registry/default/ui/sheet primitive: https://www.radix-vue.com/components/dialog.html --- - - + ## Installation - + ```bash npx shadcn-vue@latest add sheet ``` @@ -50,8 +49,7 @@ import { Use the `side` property to `` to indicate the edge of the screen where the component will appear. The values can be `top`, `right`, `bottom` or `left`. - - + ### Size diff --git a/apps/www/src/content/docs/components/sonner.md b/apps/www/src/content/docs/components/sonner.md index 792b4352..733276b0 100644 --- a/apps/www/src/content/docs/components/sonner.md +++ b/apps/www/src/content/docs/components/sonner.md @@ -2,7 +2,7 @@ title: Sonner description: An opinionated toast component for Vue. docs: https://vue-sonner.vercel.app -source: apps/www/src/lib/registry/default/ui/sonner +source: apps/www/src/lib/registry/default/ui/sonner --- @@ -34,7 +34,7 @@ import { Toaster } from '@/components/ui/sonner' ``` - + ## Usage diff --git a/apps/www/src/content/docs/components/switch.md b/apps/www/src/content/docs/components/switch.md index a359a4df..d1dbfd08 100644 --- a/apps/www/src/content/docs/components/switch.md +++ b/apps/www/src/content/docs/components/switch.md @@ -1,12 +1,11 @@ --- title: Switch description: A control that allows the user to toggle between checked and not checked. -source: apps/www/src/lib/registry/default/ui/switch +source: apps/www/src/lib/registry/default/ui/switch primitive: https://www.radix-vue.com/components/switch.html --- - - + ## Installation @@ -29,7 +28,7 @@ npm install radix-vue ``` ### Copy and paste the following code into your project - + <<< @/lib/registry/default/ui/switch/Switch.vue diff --git a/apps/www/src/content/docs/components/table.md b/apps/www/src/content/docs/components/table.md index e0701b58..8646b855 100644 --- a/apps/www/src/content/docs/components/table.md +++ b/apps/www/src/content/docs/components/table.md @@ -3,8 +3,7 @@ title: Table description: A responsive table component. --- - - + ## Installation @@ -64,4 +63,4 @@ You can use the `` component to build more complex data tables. Combine See the [Data Table](/docs/components/data-table) documentation for more information. -You can also see an example of a data table in the [Tasks](/examples/tasks) demo. \ No newline at end of file +You can also see an example of a data table in the [Tasks](/examples/tasks) demo. diff --git a/apps/www/src/content/docs/components/tabs.md b/apps/www/src/content/docs/components/tabs.md index 317836e7..416aee80 100644 --- a/apps/www/src/content/docs/components/tabs.md +++ b/apps/www/src/content/docs/components/tabs.md @@ -1,17 +1,14 @@ --- title: Tabs description: A set of layered sections of content—known as tab panels—that are displayed one at a time. -source: apps/www/src/lib/registry/default/ui/tabs +source: apps/www/src/lib/registry/default/ui/tabs primitive: https://www.radix-vue.com/components/tabs.html --- - - + ## Installation - - ```bash npx shadcn-vue@latest add tabs ``` @@ -41,4 +38,4 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs' -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/components/tags-input.md b/apps/www/src/content/docs/components/tags-input.md index 4833e967..97071831 100644 --- a/apps/www/src/content/docs/components/tags-input.md +++ b/apps/www/src/content/docs/components/tags-input.md @@ -5,7 +5,7 @@ source: apps/www/src/lib/registry/default/ui/tags-input primitive: https://www.radix-vue.com/components/tags-input.html --- - + ## Installation @@ -13,9 +13,8 @@ primitive: https://www.radix-vue.com/components/tags-input.html npx shadcn-vue@latest add tags-input ``` - ## Usage ### Tags with Combobox - + diff --git a/apps/www/src/content/docs/components/textarea.md b/apps/www/src/content/docs/components/textarea.md index 930a7762..f82873ea 100644 --- a/apps/www/src/content/docs/components/textarea.md +++ b/apps/www/src/content/docs/components/textarea.md @@ -3,8 +3,7 @@ title: Textarea description: Displays a form textarea or a component that looks like a textarea. --- - - + ## Installation diff --git a/apps/www/src/content/docs/components/toast.md b/apps/www/src/content/docs/components/toast.md index b2cc424e..1514472b 100644 --- a/apps/www/src/content/docs/components/toast.md +++ b/apps/www/src/content/docs/components/toast.md @@ -1,15 +1,13 @@ --- title: Toast description: A succinct message that is displayed temporarily. -source: apps/www/src/lib/registry/default/ui/toast +source: apps/www/src/lib/registry/default/ui/toast primitive: https://www.radix-vue.com/components/toast.html --- - ## Installation - @@ -32,9 +30,8 @@ import Toaster from '@/components/ui/toast/Toaster.vue' ``` - + - ## Usage diff --git a/apps/www/src/content/docs/components/toggle-group.md b/apps/www/src/content/docs/components/toggle-group.md index f622f630..96a8f463 100644 --- a/apps/www/src/content/docs/components/toggle-group.md +++ b/apps/www/src/content/docs/components/toggle-group.md @@ -5,7 +5,7 @@ source: apps/www/src/lib/registry/default/ui/toggle-group primitive: https://www.radix-vue.com/components/toggle-group.html --- - + ## Installation @@ -60,34 +60,26 @@ import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group' ## Examples -### Default - - +### Default + ### Outline - - + ### Single - ### Small - ### Large - ### Disabled - - - diff --git a/apps/www/src/content/docs/components/toggle.md b/apps/www/src/content/docs/components/toggle.md index c720bb3e..5bd4ec11 100644 --- a/apps/www/src/content/docs/components/toggle.md +++ b/apps/www/src/content/docs/components/toggle.md @@ -1,13 +1,11 @@ --- title: Toggle description: A two-state button that can be either on or off. -source: apps/www/src/lib/registry/default/ui/toggle +source: apps/www/src/lib/registry/default/ui/toggle primitive: https://www.radix-vue.com/components/toggle.html --- - - - + ## Installation @@ -52,34 +50,26 @@ import { Toggle } from '@/components/ui/toggle' ## Examples -### Default - - +### Default + ### Outline - - + ### With Text - ### Small - ### Large - ### Disabled - - - diff --git a/apps/www/src/content/docs/components/tooltip.md b/apps/www/src/content/docs/components/tooltip.md index 14108ed3..ab2a4d8b 100644 --- a/apps/www/src/content/docs/components/tooltip.md +++ b/apps/www/src/content/docs/components/tooltip.md @@ -1,12 +1,11 @@ --- title: Tooltip description: A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it. -source: apps/www/src/lib/registry/default/ui/tooltip +source: apps/www/src/lib/registry/default/ui/tooltip primitive: https://www.radix-vue.com/components/tooltip.html --- - - + ## Installation @@ -36,4 +35,4 @@ import { -``` \ No newline at end of file +``` diff --git a/apps/www/src/content/docs/contribution.md b/apps/www/src/content/docs/contribution.md new file mode 100644 index 00000000..1ca556a2 --- /dev/null +++ b/apps/www/src/content/docs/contribution.md @@ -0,0 +1,341 @@ +--- +title: Contribution +description: Learn on how to contribute to shadcn/vue. +--- +## Introduction + +Thanks for your interest in contributing to shadcn-vue.com. We're happy to have you here. + +Please take a moment to review this document before submitting your first pull request. We also strongly recommend that you check for open issues and pull requests to see if someone else is working on something similar. + +If you need any help, feel free to reach out to the core team on [Discord](https://chat.radix-vue.com/). + +This guide provides detailed information to help new contributors. + +## About this repository + +This repository is a monorepo. + +- We use [pnpm](https://pnpm.io) and [`workspaces`](https://pnpm.io/workspaces) for development. + +## Project Structure + +The GitHub repository consists of the several folders. here's a quick view. + + + +1. **packages** - +Contains source code for supporting `nuxt` as a module and the `cli` to add new components. + +2. **apps/www** - +The main folder that holds the source code for the website and every `shadcn/vue` component. This folder contains important sub-folders and is a subproject with its own `package.json`. + +3. **.vitepress** - +Contains the configuration and source code for `vitepress` and the `shadcn/vue` website. + +4. **src** - +Hosts the main source code for every `shadcn/vue` component or demo and their documentation on the website. + +5. **\_\_registry\_\_** - +Holds the registry file generated by `scripts/build-registry.ts` to serve components for the `cli`. This folder's content is auto-generated and should not be edited manually. + +6. **scripts** - +Contains various helper scripts, such as `build-registry.ts`, which automatically generates the `__registry__` folder. + +7. **content** - +This folder holds all the documentation for the `/docs` route. Each component has one `.md` file documenting the installation and usage of the component. + +8. **examples** - +Holds all examples not part of `/docs`, like the [main page](/). + +9. **lib/registry** - +The main folder hosts the source code for different styles of every component. This is likely the main folder you'll be changing. + +We support two different styles for every component in `shadcn/vue`: + +1. Default +2. New York + +Every component added to the repository must support both versions, including the main source code and associated demos. + +When adding or modifying components, please ensure that: + +1. You make the changes for every style. +2. You update the documentation. +3. You run `pnpm build:registry` to update the registry. + +## Development + +Start by cloning the repository: + +```bash +git clone git@github.com:radix-vue/shadcn-vue.git +``` + +### Install dependencies + +```bash +pnpm install +``` + +### Run a workspace + +You can use the `pnpm --filter=[WORKSPACE]` command to start the development process for a workspace or some of the shortcut command that we have setup. + +#### Examples + +1. To run the `shadcn-vue.com` website: + +``` +pnpm dev +``` + +2. To run the `shadcn-vue` cli package: + +``` +pnpm dev:cli +``` + +## Documentation + +The documentation for this project is located in the `www` workspace. You can run the documentation locally by running the following command: + +```bash +pnpm dev +``` + +Documentation is written using [md](https://vitepress.dev/guide/markdown). You can find the documentation files in the `apps/www/src/content` directory. + +## CLI + +The `shadcn-vue` package is a CLI for adding components to your project. You can find the documentation for the CLI [here](https://shadcn-vue.com/docs/cli). + +Any changes to the CLI should be made in the `packages/cli` directory. If you can, it would be great if you could add tests for your changes. + +## Testing + +Tests are written using [Vitest](https://vitest.dev). You can run all the tests from the root of the repository. + +```bash +pnpm test +``` + +Please ensure that the tests are passing when submitting a pull request. If you're adding new features, please include tests. + +## Commit Convention + +Before you create a Pull Request, please check whether your commits comply with +the commit conventions used in this repository. + +When you create a commit we kindly ask you to follow the convention +`category(scope or module): message` in your commit message while using one of +the following categories: + +- `feat / feature`: all changes that introduce completely new code or new + features +- `fix`: changes that fix a bug (ideally you will additionally reference an + issue if present) +- `refactor`: any code related change that is not a fix nor a feature +- `docs`: changing existing or creating new documentation (i.e. README, docs for + usage of a lib or cli usage) +- `build`: all changes regarding the build of the software, changes to + dependencies or the addition of new dependencies +- `test`: all changes regarding tests (adding new tests or changing existing + ones) +- `ci`: all changes regarding the configuration of continuous integration (i.e. + github actions, ci system) +- `chore`: all changes to the repository that do not fit into any of the above + categories + + e.g. `feat(components): add new prop to the avatar component` + +If you are interested in the detailed specification you can visit [Conventional Commits](https://www.conventionalcommits.org/). + +## SFC - Single File Components + +Multiple components are integrated into one file in `shadcn/ui` - the React version of `shadcn` - while Vue only supports one component per file, hence the name Single File Component (SFC). In such cases, you need to create separate files for each component part and then export them all in an `index.ts` file. + +See the [`Accordion`](https://github.com/radix-vue/shadcn-vue/tree/v0.10.2/apps/www/src/lib/registry/default/ui/accordion) source code as an example. + +## Wrapping Radix-Vue Components + +[Radix-Vue](https://www.radix-vue.com) hosts many low-level UI components that are used to build reusable components. +There are many cases that you need to wrap `Radix-Vue` components. + +### Props & Events +All of the `Radix-Vue` compoennts expose their prop and emit types. We need to forward any props/events that are coming from outside to the `Radix-Vue` component. + +To do so, we have a helper function named [`useForwardPropsEmits`](https://www.radix-vue.com/utilities/use-forward-props-emits.html) that combines props and events that must be binded to the child radix component. + +To be more clear, the function `useForwardPropsEmits` takes in props and an optional emit function, and returns a +computed object that combines the parsed props and emits as props. + +Here's an example from `Accordian` root component. + +```vue + + + +``` + +As you can see, `AccordionRootEmits` and `AccordionRootProps` types are imported from radix, combined with `useForwardPropsEmits` and then are binded using `v-bind` syntaxt. + +### CSS Classes +There are cases when we want to accept `class` as a prop in our `shadcn/vue` component and then combine it with a default tailwind class on our `radix-vue` component via `cn` utility function. + +In these cases, we can not use `v-bind`, because this would lead in [double class binding](https://github.com/radix-vue/shadcn-vue/pull/241). + +Take a look at `DrawerDescription.vue`. + +```vue + + + +``` + +As you can see, we have created a computed property named `delegatedProps` to remove `class` from props, and only then bind +the returned value to our radix component (`DrawerDescription` in this case). + +As for our class, we first declared it as type of `HtmlHTMLAttributes['class']` and used `cn` to merge tailwind classes from `class` prop and our own classes. + +This pattern only needs to be applied when the `cn` utility is required. For instances where there are no default Tailwind classes that need to be merged with user-provided classes, this pattern is not necessary. A good example of this is the `SelectValue.vue` component. + +```vue + + + +``` + +### Boolean Props +When you are building a wrapper for a component, in some cases you want to ignore Vue [Props Boolean Casting](https://vuejs.org/guide/components/props.html#boolean-casting). +You can either set default value as undefined for all the boolean field, or you can use [`useForwardProps`](https://www.radix-vue.com/utilities/use-forward-props.html) composable. + +Take a look at `AccordionItem.vue` + +```vue + + + +``` + +Since `AccordionItemProps` type has atleast one boolean property, we need to use `useForwardProps` on the entire props object. + +Note that `useForwardPropsEmits` use `useForwardProps` under the hood. + +### Component as Root +Whenever your root component is a `Component` Primitive from vue, it's easier to use [`Primitive`](https://www.radix-vue.com/utilities/primitive.html) instead. + +Let's take a look at `Button.vue` + +```vue + + + +``` + +You'll need to extend `PrimitiveProps` in your props to support `Primitive` component. In most cases you would also need a default value for [`as`](https://www.radix-vue.com/utilities/primitive.html#changing-as-value) property. + +## Debugging +Here are some tools and techniques that can help you debug more effectively while contributing to `shadcn/vue` or developing your own projects. + +### Install Vue Dev Tools +To easily inspect component props, attributes, events, and more, you can leverage the [`Vue DevTools`](https://devtools.vuejs.org/) extension for browsers. This extension provides a user-friendly interface for debugging Vue components and can improve your development experience. + +### Enable Custom Formmaters +Vue wraps values stored in a `ref` in a way that, when logged, results in a nested object and requires manual inspection to access the value stored in the ref. + +You can enable Custom Formatters in your browser to automate this process. + +- [Firefox](https://firefox-source-docs.mozilla.org/devtools-user/custom_formatters/index.html) +- Chrome, Edge, Brave and other Chromium based [browsers](https://www.google.com/search?q=how+to+enable+custom++formatter+chrome) diff --git a/apps/www/src/content/docs/installation.md b/apps/www/src/content/docs/installation.md index 04a30608..567b225d 100644 --- a/apps/www/src/content/docs/installation.md +++ b/apps/www/src/content/docs/installation.md @@ -2,7 +2,7 @@ title: Installation description: How to install dependencies and structure your app. --- - + ## Frameworks
@@ -18,7 +18,7 @@ description: How to install dependencies and structure your app.

Vite

- + Nuxt @@ -53,11 +53,9 @@ description: How to install dependencies and structure your app.

Laravel

-
+
- - ## TypeScript This project and the components are written in TypeScript. We recommend using TypeScript for your project as well. @@ -97,11 +95,11 @@ To configure import aliases, you can use the following `jsconfig.json`: ## VSCode extension -Install the [shadcn-vue](https://marketplace.visualstudio.com/items?itemName=Selemondev.shadcn-vue) extension by [@selemondev](https://github.com/selemondev) in Visual Studio Code to easily add Shadcn Vue components to your project. +Install the [shadcn-vue](https://marketplace.visualstudio.com/items?itemName=Selemondev.shadcn-vue) extension by [@selemondev](https://github.com/selemondev) in Visual Studio Code to easily add Shadcn Vue components to your project. This extension offers a range of features: - Ability to initialize the Shadcn Vue CLI - Install components - Open documentation -- Navigate to a specific component's documentation page directly from your IDE. +- Navigate to a specific component's documentation page directly from your IDE. - Handy snippets for quick and straightforward component imports and markup. diff --git a/apps/www/src/content/docs/installation/astro.md b/apps/www/src/content/docs/installation/astro.md index 3f5efd57..b465dd45 100644 --- a/apps/www/src/content/docs/installation/astro.md +++ b/apps/www/src/content/docs/installation/astro.md @@ -126,7 +126,7 @@ import '@/styles/globals.css' To prevent serving the Tailwind base styles twice, we need to tell Astro not to apply the base styles, since we already include them in our own `globals.css` file. To do this, set the `applyBaseStyles` config option for the tailwind plugin in `astro.config.mjs` to `false`. -```ts:line-numbers {3-5} +```ts:line-numbers {3-5} export default defineConfig({ integrations: [ tailwind({ @@ -161,4 +161,4 @@ import { Button } from "@/components/ui/button" ``` - \ No newline at end of file + diff --git a/apps/www/src/content/docs/installation/laravel.md b/apps/www/src/content/docs/installation/laravel.md index 791a1f3d..9f83e77d 100644 --- a/apps/www/src/content/docs/installation/laravel.md +++ b/apps/www/src/content/docs/installation/laravel.md @@ -34,7 +34,7 @@ Where is your global CSS file? › resources/css/app.css Do you want to use CSS variables for colors? › no / yes Where is your tailwind.config.js located? › tailwind.config.js Configure the import alias for components: › @/Components -Configure the import alias for utils: › @/lib/utils +Configure the import alias for utils: › @/lib/utils ``` ### Update tailwind.config.js @@ -150,4 +150,4 @@ import { Button } from '@/Components/ui/button' ``` - \ No newline at end of file + diff --git a/apps/www/src/content/docs/installation/nuxt.md b/apps/www/src/content/docs/installation/nuxt.md index ff91808f..c5dc56ac 100644 --- a/apps/www/src/content/docs/installation/nuxt.md +++ b/apps/www/src/content/docs/installation/nuxt.md @@ -41,7 +41,6 @@ npm install -D @nuxtjs/tailwindcss - Add the following code to `modules/shadcn.ts`. @@ -148,7 +147,6 @@ declare module '@nuxt/schema' { - ### Configure `nuxt.config.ts` ```ts @@ -189,7 +187,7 @@ Where is your global CSS file? › › src/index.css Do you want to use CSS variables for colors? › no / yes Where is your tailwind.config.js located? › tailwind.config.js Configure the import alias for components: › @/components -Configure the import alias for utils: › @/lib/utils +Configure the import alias for utils: › @/lib/utils ``` ### App structure @@ -197,7 +195,7 @@ Configure the import alias for utils: › @/lib/utils Here's the default structure of Nuxt app. You can use this as a reference: ```txt {6-16,20-21} -. +. ├── pages │ ├── index.vue │ └── dashboard.vue diff --git a/apps/www/src/content/docs/introduction.md b/apps/www/src/content/docs/introduction.md index aa4a55c9..e5957005 100644 --- a/apps/www/src/content/docs/introduction.md +++ b/apps/www/src/content/docs/introduction.md @@ -21,7 +21,6 @@ _Use this as a reference to build your own component libraries._ ## FAQ - @@ -58,4 +57,4 @@ Yes. Free to use for personal and commercial projects. No attribution required. But let us know if you do use it. We'd love to see what you build with it. - \ No newline at end of file + diff --git a/apps/www/src/content/docs/theming.md b/apps/www/src/content/docs/theming.md index f4fcdd58..3e229e41 100644 --- a/apps/www/src/content/docs/theming.md +++ b/apps/www/src/content/docs/theming.md @@ -3,7 +3,6 @@ title: Theming description: Use CSS Variables to customize the look and feel of your application. --- - You can choose between using CSS variables or Tailwind CSS utility classes for theming. ## Utility classes @@ -37,7 +36,6 @@ To use utility classes for theming set `tailwind.cssVariables` to `false` in you ``` To use CSS variables for theming set `tailwind.cssVariables` to `true` in your `components.json` file. - ```json {7} title="components.json" { @@ -96,64 +94,64 @@ Here's the list of variables available for customization: --foreground: 222.2 47.4% 11.2%; ``` -```css +```css /* Muted backgrounds such as , and */ --muted: 210 40% 96.1%; --muted-foreground: 215.4 16.3% 46.9%; ``` -```css +```css /* Background color for */ --card: 0 0% 100%; --card-foreground: 222.2 47.4% 11.2%; ``` -```css +```css /* Background color for popovers such as , , */ --popover: 0 0% 100%; --popover-foreground: 222.2 47.4% 11.2%; ``` -```css +```css /* Default border color */ --border: 214.3 31.8% 91.4%; ``` -```css +```css /* Border color for inputs such as ,