nuxt-ui-formwerk 0.1.1

package/README.md

@@ -0,0 +1,254 @@
+# Nuxt UI Formwerk
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+Enhanced form components for Nuxt UI with [@formwerk/core](https://formwerk.dev/) integration. This module bridges the gap between Formwerk's powerful form validation and state management with Nuxt UI's beautiful form components.
+
+- [✨  Release Notes](/CHANGELOG.md)
+
+## Features
+
+- 🎯 **Formwerk Integration** - Seamless integration with [@formwerk/core](https://formwerk.dev/) for advanced form validation
+- 📝 **Enhanced Form Components** - Wraps Nuxt UI components with formwerk capabilities
+- ✅ **Field-level Validation** - Granular validation control with error message handling
+- 🔄 **State Tracking** - Track touched, blurred, and dirty states per field
+- ⚙️ **Flexible Validation Strategies** - Configure when validation occurs (on blur, on input, etc.)
+- 📦 **Auto-import** - Components are automatically available in your app
+- 🎯 **TypeScript** - Full type safety out of the box
+
+## Quick Setup
+
+Install the module and its peer dependencies:
+
+```bash
+pnpm add nuxt-ui-formwerk
+```
+
+Add the module to your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui', 'nuxt-ui-formwerk']
+})
+```
+
+That's it! You can now use enhanced form components in your Nuxt app ✨
+
+## Usage
+
+This module provides three main components that wrap Nuxt UI form components with formwerk functionality:
+
+### FormwerkForm
+
+The root form component that provides validation context and tracks form state.
+
+```vue
+<script setup lang="ts">
+import { z } from 'zod'
+
+const schema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8)
+})
+
+const state = reactive({
+  email: '',
+  password: ''
+})
+</script>
+
+<template>
+  <FormwerkForm :schema="schema" :state="state" validate-on="blur" #="{ blurredFields, touchedFields, dirtyFields }">
+    <!-- Form content here -->
+    <p>Blurred fields: {{ blurredFields.size }}</p>
+  </FormwerkForm>
+</template>
+```
+
+#### Props
+
+| Prop         | Type                           | Default  | Description                                     |
+| ------------ | ------------------------------ | -------- | ----------------------------------------------- |
+| `validateOn` | `'touched' \| 'blur' \| 'dirty'` | `'blur'` | When to trigger validation                      |
+| `disabled`   | `boolean`                      | `false`  | Disable all form fields                         |
+
+#### Slot Props
+
+- `blurredFields` - Set of field names that have been blurred
+- `touchedFields` - Set of field names that have been touched
+- `dirtyFields` - Set of field names with modified values
+
+### FormwerkField
+
+Enhanced field component that wraps `UFormField` with formwerk validation.
+
+```vue
+<template>
+  <FormwerkForm :schema="schema" :state="state">
+    <FormwerkField name="email" label="Email" required #="{ setValue, value }">
+      <UInput
+        :model-value="value"
+        @update:model-value="setValue"
+        type="email"
+      />
+    </FormwerkField>
+  </FormwerkForm>
+</template>
+```
+
+#### Props
+
+Accepts all `UFormField` props except `validateOnInputDelay`, `errorPattern`, `eagerValidation`, and `error` (these are managed by formwerk).
+
+#### Slot Props
+
+- `setValue` - Function to update field value
+- `value` - Current field value (fieldValue)
+
+### FormwerkGroup
+
+Groups related form fields together for nested validation.
+
+```vue
+<template>
+  <FormwerkForm :schema="schema" :state="state">
+    <FormwerkGroup name="address">
+      <FormwerkField name="street" label="Street" #="{ setValue, value }">
+        <UInput :model-value="value" @update:model-value="setValue" />
+      </FormwerkField>
+      <FormwerkField name="city" label="City" #="{ setValue, value }">
+        <UInput :model-value="value" @update:model-value="setValue" />
+      </FormwerkField>
+    </FormwerkGroup>
+  </FormwerkForm>
+</template>
+```
+
+#### Props
+
+| Prop   | Type     | Required | Description      |
+| ------ | -------- | -------- | ---------------- |
+| `name` | `string` | Yes      | Group identifier |
+
+## Complete Example
+
+```vue
+<script setup lang="ts">
+import { z } from 'zod'
+
+const schema = z.object({
+  name: z.string().min(2, 'Name must be at least 2 characters'),
+  email: z.string().email('Invalid email address'),
+  password: z.string().min(8, 'Password must be at least 8 characters')
+})
+
+const state = reactive({
+  name: '',
+  email: '',
+  password: ''
+})
+
+const onSubmit = () => {
+  console.log('Form submitted:', state)
+}
+</script>
+
+<template>
+  <FormwerkForm :schema="schema" :state="state" validate-on="blur" #="{ blurredFields }">
+    <div class="space-y-4">
+      <FormwerkField name="name" label="Name" required #="{ setValue, value }">
+        <UInput :model-value="value" @update:model-value="setValue" />
+      </FormwerkField>
+
+      <FormwerkField name="email" label="Email" required #="{ setValue, value }">
+        <UInput :model-value="value" @update:model-value="setValue" type="email" />
+      </FormwerkField>
+
+      <FormwerkField name="password" label="Password" required #="{ setValue, value }">
+        <UInput :model-value="value" @update:model-value="setValue" type="password" />
+      </FormwerkField>
+
+      <UButton type="submit" @click="onSubmit">
+        Submit
+      </UButton>
+
+      <p class="text-sm text-gray-500">
+        Fields blurred: {{ blurredFields.size }}
+      </p>
+    </div>
+  </FormwerkForm>
+</template>
+```
+
+## Components
+
+All components are auto-imported with the `Formwerk` prefix:
+
+- `FormwerkForm` - Root form component
+- `FormwerkField` - Field wrapper component
+- `FormwerkGroup` - Field grouping component
+
+## How It Works
+
+This module bridges [@formwerk/core](https://formwerk.dev/) with [@nuxt/ui](https://ui.nuxt.com/) by:
+
+1. **FormwerkForm** creates a formwerk form context and manages dual event buses (one for Nuxt UI, one for formwerk)
+2. **FormwerkField** uses formwerk's `useCustomControl` composable to register fields and handle validation
+3. Event coordination between both systems ensures validation triggers work as expected
+4. Field state (touched, blurred, dirty) is tracked and exposed to the parent form
+
+The integration allows you to use Nuxt UI's beautiful form components while leveraging formwerk's powerful validation and state management capabilities.
+
+## Contribution
+
+<details>
+  <summary>Local development</summary>
+
+  ```bash
+  # Install dependencies
+  pnpm install
+
+  # Generate type stubs and prepare playground
+  pnpm dev:prepare
+
+  # Develop with the playground
+  pnpm dev
+
+  # Build the playground
+  pnpm dev:build
+
+  # Run linter (oxlint)
+  pnpm lint
+
+  # Fix linting issues
+  pnpm lint:fix
+
+  # Format code (oxfmt)
+  pnpm format
+
+  # Run tests
+  pnpm test
+  pnpm test:watch
+
+  # Type check
+  pnpm test:types
+
+  # Release new version
+  pnpm release
+  ```
+
+</details>
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/nuxt-ui-formwerk/latest.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-version-href]: https://npmjs.com/package/nuxt-ui-formwerk
+[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-ui-formwerk.svg?style=flat&colorA=020420&colorB=00DC82
+[npm-downloads-href]: https://npm.chart.dev/nuxt-ui-formwerk
+[license-src]: https://img.shields.io/npm/l/nuxt-ui-formwerk.svg?style=flat&colorA=020420&colorB=00DC82
+[license-href]: https://npmjs.com/package/nuxt-ui-formwerk
+[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

package/dist/module.d.mts

@@ -0,0 +1,8 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxt-ui-formwerk",
+  "configKey": "uiElements",
+  "version": "0.1.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,23 @@
+import { defineNuxtModule, createResolver, useLogger, hasNuxtModule, addComponentsDir } from '@nuxt/kit';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-ui-formwerk",
+    configKey: "uiElements"
+  },
+  defaults: {},
+  setup(_options, _nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const logger = useLogger("nuxt-ui-formwerk");
+    if (!hasNuxtModule("@nuxt/ui")) {
+      logger.error("[nuxt-ui-formwerk] @nuxt/ui is required. Please install it");
+    }
+    addComponentsDir({
+      path: resolver.resolve("./runtime/components"),
+      pathPrefix: false,
+      prefix: "Formwerk"
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/components/Field.d.vue.ts

@@ -0,0 +1,18 @@
+import type { FormFieldProps } from "@nuxt/ui";
+type __VLS_Props = Omit<FormFieldProps, "validateOnInputDelay" | "errorPattern" | "eagerValidation" | "error">;
+declare var __VLS_8: {
+    setValue: (value: any) => void;
+    value: any;
+};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_8) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/Field.vue

@@ -0,0 +1,57 @@
+<script setup>
+import { useCustomControl } from "@formwerk/core";
+import { formwerkOptionsInjectionKey, formwerkBusInjectionKey } from "./Form.vue";
+const props = defineProps({
+  as: { type: null, required: false },
+  name: { type: String, required: false },
+  label: { type: String, required: false },
+  description: { type: String, required: false },
+  help: { type: String, required: false },
+  hint: { type: String, required: false },
+  size: { type: null, required: false },
+  required: { type: Boolean, required: false },
+  class: { type: null, required: false },
+  ui: { type: null, required: false }
+});
+const formBus = inject(formBusInjectionKey, void 0);
+const formwerkBus = inject(formwerkBusInjectionKey, void 0);
+const formwerkOptions = inject(formwerkOptionsInjectionKey, void 0);
+const {
+  field: { errorMessage, fieldValue, setValue, setBlurred, setTouched, isTouched, isBlurred, isDirty }
+} = useCustomControl({ name: props.name, required: props.required, disabled: formwerkOptions?.value?.disabled });
+const emitFormEvent = (type, name, payload) => {
+  if (formwerkBus && name) formwerkBus.emit(type, { name, payload });
+};
+watch(isTouched, (newValue) => emitFormEvent("touched", props.name, newValue));
+watch(isBlurred, (newValue) => emitFormEvent("blur", props.name, newValue));
+watch(isDirty, (newValue) => emitFormEvent("dirty", props.name, newValue));
+const error = computed(() => {
+  if (!formwerkOptions || !formwerkOptions.value) return errorMessage.value ? errorMessage.value : void 0;
+  switch (formwerkOptions.value.validateOn) {
+    case "blur":
+      return isBlurred.value && errorMessage.value ? errorMessage.value : void 0;
+    default:
+      return errorMessage.value ? errorMessage.value : void 0;
+  }
+});
+if (formBus) {
+  formBus.on(async (event) => {
+    switch (event.type) {
+      case "blur":
+        setBlurred(true);
+        break;
+      case "change":
+      case "input":
+      case "focus":
+        setTouched(true);
+        break;
+    }
+  });
+}
+</script>
+
+<template>
+  <UFormField v-bind="props" :error="error">
+    <slot :set-value="setValue" :value="fieldValue" />
+  </UFormField>
+</template>

package/dist/runtime/components/Field.vue.d.ts

@@ -0,0 +1,18 @@
+import type { FormFieldProps } from "@nuxt/ui";
+type __VLS_Props = Omit<FormFieldProps, "validateOnInputDelay" | "errorPattern" | "eagerValidation" | "error">;
+declare var __VLS_8: {
+    setValue: (value: any) => void;
+    value: any;
+};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_8) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/Form.vue

@@ -0,0 +1,60 @@
+<script>
+import { useFormContext } from "@formwerk/core";
+export const formwerkOptionsInjectionKey = /* @__PURE__ */ Symbol("nuxt-ui-formwerk.form-options");
+export const formwerkBusInjectionKey = /* @__PURE__ */ Symbol("nuxt-ui-formwerk.form-events");
+</script>
+
+<script setup>
+const { context } = useFormContext();
+const { validateOn = "blur", disabled = false } = defineProps({
+  validateOn: { type: String, required: false },
+  disabled: { type: Boolean, required: false }
+});
+const formwerkBus = useEventBus(`formwerk-form-${context.id}`);
+const NuxtUiFormBus = useEventBus(`form-${context.id}`);
+const dirtyFields = reactive(/* @__PURE__ */ new Set());
+const touchedFields = reactive(/* @__PURE__ */ new Set());
+const blurredFields = reactive(/* @__PURE__ */ new Set());
+provide(formwerkBusInjectionKey, formwerkBus);
+provide(formBusInjectionKey, NuxtUiFormBus);
+provide(
+  formwerkOptionsInjectionKey,
+  computed(() => ({
+    validateOn
+  }))
+);
+provide(
+  formOptionsInjectionKey,
+  computed(() => ({
+    disabled
+  }))
+);
+const toggleState = (set, payload) => {
+  if (!payload) return;
+  const { name, payload: isSet } = payload;
+  if (isSet) {
+    set.add(name);
+  } else {
+    set.delete(name);
+  }
+};
+formwerkBus.on(async (event, payload) => {
+  switch (event) {
+    case "touched":
+      toggleState(touchedFields, payload);
+      break;
+    case "blur":
+      toggleState(blurredFields, payload);
+      break;
+    case "dirty":
+      toggleState(dirtyFields, payload);
+      break;
+  }
+});
+</script>
+
+<template>
+  <div>
+    <slot :blurred-fields="blurredFields" :touched-fields="touchedFields" :dirty-fields="dirtyFields" />
+  </div>
+</template>

package/dist/runtime/components/Group.d.vue.ts

@@ -0,0 +1,16 @@
+interface Props {
+    name: string;
+}
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/runtime/components/Group.vue

@@ -0,0 +1,15 @@
+<script setup>
+import { useFormGroup } from "@formwerk/core";
+defineProps({
+  name: { type: String, required: true }
+});
+useFormGroup({
+  name: "options"
+});
+</script>
+
+<template>
+  <div>
+    <slot />
+  </div>
+</template>

package/dist/runtime/components/Group.vue.d.ts

@@ -0,0 +1,16 @@
+interface Props {
+    name: string;
+}
+declare var __VLS_1: {};
+type __VLS_Slots = {} & {
+    default?: (props: typeof __VLS_1) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "nuxt-ui-formwerk",
+  "version": "0.1.1",
+  "description": "A collection of beautiful, animated UI components for Nuxt applications",
+  "license": "MIT",
+  "repository": "https://github.com/genu/nuxt-ui-formwerk.git",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "dependencies": {
+    "@nuxt/kit": "^4.2.2"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.1.1",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.2.2",
+    "@nuxt/test-utils": "^3.21.0",
+    "@types/culori": "^4.0.1",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "nuxt": "^4.2.2",
+    "oxfmt": "^0.20.0",
+    "oxlint": "^1.35.0",
+    "oxlint-tsgolint": "^0.10.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.16",
+    "vue-tsc": "^3.2.1"
+  },
+  "peerDependencies": {
+    "@nuxt/ui": "^4.0.0",
+    "@formwerk/core": "^0.14.4"
+  },
+  "scripts": {
+    "dev": "pnpm dev:prepare && nuxi dev playground",
+    "dev:build": "nuxi build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground",
+    "lint": "oxlint --type-aware",
+    "lint:fix": "oxlint --fix --type-aware",
+    "format": "oxfmt --write",
+    "format:check": "oxfmt --check",
+    "release": "pnpm lint && pnpm test && pnpm prepack && changelogen --release && pnpm publish && git push --follow-tags",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  }
+}