Skip to content

Beautiful Open-Source Form Builder

6.1 KB
Raw Blame
---
description: Vue and Nuxt guidelines
globs: client/**.*
alwaysApply: false
---

You are an expert in Nuxt, Vue.js, Vue Router, Pinia, VueUse, NuxtUI v4 library and Tailwind, with a deep understanding of best practices and performance optimization techniques in these technologies.

## Code Style and Structure

-   Write concise, maintainable, and technically accurate code with relevant examples.
-   Use functional and declarative programming patterns; avoid classes.
-   Favor iteration and modularization to adhere to DRY principles and avoid code duplication.
-   Use descriptive variable names with auxiliary verbs (e.g., isLoading, hasError).
-   Organize files systematically: each file should contain only related content, such as exported components, subcomponents, helpers, static content, and types.
-   No need to import Vue Reactivity APIs like ref or computed, as well as lifecycle hooks and helpers in .vue components, as they are auto-imported by Nuxt
-   For promises and async, always use ().then().error().finally() syntax over try/catch/await

## Naming Conventions

-   Use lowercase with dashes for directories (e.g., components/auth-wizard).
-   Favor named exports for functions.

We don't use typescript, javascript only (except when really required for config file for instance).

## Syntax and Formatting

-   Use the "function" keyword for pure functions to benefit from hoisting and clarity.
-   Always use the Vue Composition API script setup style. If a legacy file still using options API, it it's short then directly update the script section. If it's longer and a bit more complex, make the requried change using the existing options API and at the end ask if you should migrate to composition API.

## UI and Styling

-   Use Nuxt UI v4 components (https://ui.nuxt.com/components) and Tailwind for components and styling. Ex: <UModal>, <UPopover>, <UToolTip>, <UBadge> etc... Essentially use NuxtUI for everything but for form components.
-   Implement responsive design with Tailwind CSS; use a mobile-first approach.
-   Build UI components using atomic design principles, organizing them from smallest to largest (e.g., atoms, molecules, organisms, pages).
-   Icons: use the <Icon> component, and for icon names always use `i-library-icon` syntax.
-   **Color naming**: Never use Tailwind color "gray" - always use "neutral" instead (e.g., `text-neutral-500`, `bg-neutral-100`, `border-neutral-300`). This also applies to Nuxt UI component color props and any other component color props - use "neutral" instead of "gray" (e.g., `<UBadge color="neutral">`, not `color="gray"`).

## Form Component Theming

Form components use the **tailwind-variants (tv)** library with a standardized pattern for styling:

### Theme Structure

Each form component has a corresponding theme file in `lib/forms/themes/`:

-   Theme files export a `themeObject` (e.g., `textInputTheme`, `focusedSelectorInputTheme`)
-   Themes define `slots` (HTML elements) with base Tailwind classes
-   Themes define `variants` (size, theme, borderRadius, hasError, disabled, etc.)
-   Themes define `defaultVariants` (fallback values)

Example theme structure:

```javascript
// lib/forms/themes/text-input.theme.js
export const textInputTheme = {
  slots: {
    input: 'flex-1 w-full border bg-white text-neutral-700 focus:outline-hidden',
    help: 'text-neutral-500'
  },
  variants: {
    theme: { default: { input: 'border-neutral-300' }, ... },
    size: { md: { input: 'px-4 py-2 text-base' }, ... },
    hasError: { true: { input: '!ring-red-500 !border-transparent' } }
  },
  defaultVariants: { theme: 'default', size: 'md', hasError: false }
}
```

### Composable Integration

The `useFormInput` composable sets up tv with the theme:

```javascript
// In composable: simple, no ui merging here
return tv(composableOptions.variants, { twMerge: true })({
    theme: resolvedTheme.value,
    size: resolvedSize.value,
    // ... variant values
});
```

### UI Overrides in Components

**In templates**, pass `props.ui?.slots?.slotName` via the `class` parameter to every slot function call:

```vue
<!-- CORRECT: Pass ui overrides via class parameter -->
<input :class="ui.input({ class: props.ui?.slots?.input })" />
<div :class="ui.container({ class: props.ui?.slots?.container })" />
```

**NOT like this:**

```vue
<!-- WRONG: Don't pass ui separately -->
<input :class="ui.input()" />
<!-- Missing ui override -->
```

### How It Works

1. **Composable** calls `tv(theme, { twMerge: true })` - simple setup
2. **Theme** defines base classes for each slot
3. **Component template** calls slot functions with `{ class: props.ui?.slots?.slotName }`
4. **tv slot function** automatically merges:
    - Base classes from theme
    - Custom classes from `class` parameter
    - Result via twMerge (handles conflicts intelligently)

### Example: FocusedToggleInput

```javascript
// Parent passes ui override
ui: { slots: { container: 'max-w-xs' } }

// FocusedSelectorInput template uses it
<div :class="ui.container({ class: props.ui?.slots?.container })">
  <!-- Result: 'space-y-2 focus:outline-hidden max-w-xs' ✅ -->
</div>
```

### Key Rules

-   ✅ **Always pass ui overrides** via `class` parameter in templates
-   ✅ **Call tv() once** per slot function (don't pre-merge in composable)
-   ✅ **Enable twMerge** in tv config: `tv(theme, { twMerge: true })`
-   ✅ **One theme file** per component type (textInputTheme, focusedSelectorInputTheme, etc.)
-   ❌ **Don't merge props.ui in composable** - let tv slot functions handle it

Forms

-   For forms inputs, use the components in client/components/forms such as <TextInput> etc.
-   Wrap then in @VForm.vue
-   All form components must support the theme + ui override pattern above

Performance Optimization

-   Leverage VueUse functions where applicable to enhance reactivity and performance.
-   Wrap asynchronous components in Suspense with a fallback UI made with <USkeleton/> components.
-   Use dynamic loading for non-critical components.

Key Conventions

-   Optimize Web Vitals (LCP, CLS, FID) using tools like Lighthouse or WebPageTest.
-   Implement proper error boundaries or try-catch mechanisms to handle errors gracefully, especially in asynchronous operations.