symfonia-ai-tools 1.0.0

package/templates/packs/vue3/_ai/instructions/forms.instructions.md

@@ -0,0 +1,227 @@
+---
+applyTo: "**/*Form*.vue,**/*form*.ts,**/validation*"
+---
+
+# Forms & Validation - Instrukcje
+
+## Walidacja - funkcje bazowe
+
+Trzymaj funkcje walidacji w `utils/validation.ts`:
+
+```typescript
+// utils/validation.ts
+export function isNotEmpty(value: unknown): boolean {
+  if (value === null || value === undefined) return false;
+  if (typeof value === 'string') return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  return true;
+}
+
+export function isValidEmail(value: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+
+export function isValidPhone(value: string): boolean {
+  return /^\+?[\d\s-()]{7,15}$/.test(value);
+}
+
+export function isValidUrl(value: string): boolean {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function isValidLength(value: string, min: number, max?: number): boolean {
+  const len = value.trim().length;
+  if (len < min) return false;
+  if (max !== undefined && len > max) return false;
+  return true;
+}
+
+export function isValidZipCode(value: string): boolean {
+  return /^\d{2}-\d{3}$/.test(value);
+}
+```
+
+## ValidationBuilder (fluent API)
+
+Do walidacji zlozonych obiektow:
+
+```typescript
+// utils/validation-builder.ts
+interface IValidationResult {
+  isValid: boolean;
+  errors: string[];
+}
+
+class ValidationBuilder<T> {
+  private entity: T;
+  private errors: string[] = [];
+
+  constructor(entity: T) {
+    this.entity = entity;
+  }
+
+  validateString(getValue: (e: T) => string, fieldName: string, min = 1, max?: number): this {
+    const val = getValue(this.entity);
+    if (!val || val.trim().length < min) {
+      this.errors.push(`${fieldName} jest wymagane (min. ${min} znakow)`);
+    } else if (max && val.trim().length > max) {
+      this.errors.push(`${fieldName} max ${max} znakow`);
+    }
+    return this;
+  }
+
+  validatePositiveInteger(getValue: (e: T) => number, fieldName: string): this {
+    const val = getValue(this.entity);
+    if (!Number.isInteger(val) || val <= 0) {
+      this.errors.push(`${fieldName} musi byc liczba dodatnia`);
+    }
+    return this;
+  }
+
+  validateEnum<E>(getValue: (e: T) => E, allowed: E[], fieldName: string): this {
+    if (!allowed.includes(getValue(this.entity))) {
+      this.errors.push(`${fieldName} ma niedozwolona wartosc`);
+    }
+    return this;
+  }
+
+  validateCustom(condition: (e: T) => boolean, errorMessage: string): this {
+    if (!condition(this.entity)) {
+      this.errors.push(errorMessage);
+    }
+    return this;
+  }
+
+  validateNested(result: IValidationResult): this {
+    this.errors.push(...result.errors);
+    return this;
+  }
+
+  build(): IValidationResult {
+    return { isValid: this.errors.length === 0, errors: this.errors };
+  }
+}
+
+export function createValidator<T>(entity: T): ValidationBuilder<T> {
+  return new ValidationBuilder(entity);
+}
+```
+
+### Uzycie
+
+```typescript
+const result = createValidator(user)
+  .validatePositiveInteger(u => u.id, 'ID')
+  .validateString(u => u.name, 'Imie', 2, 50)
+  .validateString(u => u.email, 'Email', 5, 255)
+  .validateCustom(u => isValidEmail(u.email), 'Nieprawidlowy format email')
+  .validateEnum(u => u.role, ['admin', 'user', 'guest'], 'Rola')
+  .build();
+
+if (!result.isValid) {
+  // result.errors: ['Email: Nieprawidlowy format email', ...]
+}
+```
+
+## Walidacja w komponencie Vue
+
+```vue
+<script setup lang="ts">
+import { reactive, computed } from 'vue';
+import { isNotEmpty, isValidEmail, isValidLength } from '@/utils/validation';
+
+interface IFormData {
+  name: string;
+  email: string;
+  description: string;
+}
+
+const form = reactive<IFormData>({
+  name: '',
+  email: '',
+  description: '',
+});
+
+const validationErrors = computed(() => {
+  const errors: Record<string, string> = {};
+
+  if (!isNotEmpty(form.name)) errors.name = 'Nazwa jest wymagana';
+  else if (!isValidLength(form.name, 2, 100)) errors.name = 'Nazwa: 2-100 znakow';
+
+  if (!isNotEmpty(form.email)) errors.email = 'Email jest wymagany';
+  else if (!isValidEmail(form.email)) errors.email = 'Nieprawidlowy email';
+
+  if (form.description && !isValidLength(form.description, 0, 1000)) {
+    errors.description = 'Opis: max 1000 znakow';
+  }
+
+  return errors;
+});
+
+const isFormValid = computed(() => Object.keys(validationErrors.value).length === 0);
+</script>
+
+<template>
+  <form @submit.prevent="onSubmit">
+    <div class="form-field" :class="{ 'has-error': validationErrors.name }">
+      <label>Nazwa</label>
+      <input v-model="form.name" data-testid="formNameInput" />
+      <span v-if="validationErrors.name" class="error">{{ validationErrors.name }}</span>
+    </div>
+
+    <div class="form-field" :class="{ 'has-error': validationErrors.email }">
+      <label>Email</label>
+      <input v-model="form.email" type="email" data-testid="formEmailInput" />
+      <span v-if="validationErrors.email" class="error">{{ validationErrors.email }}</span>
+    </div>
+
+    <button type="submit" :disabled="!isFormValid" data-testid="formSubmitButton">
+      Zapisz
+    </button>
+  </form>
+</template>
+```
+
+## Obsluga bledow z API (422)
+
+```typescript
+const serverErrors = ref<Record<string, string[]>>({});
+
+async function onSubmit() {
+  serverErrors.value = {};
+  try {
+    await FeatureService.create(form);
+    notify('success', 'Zapisano');
+  } catch (error) {
+    if (error instanceof AxiosError && error.response?.status === 422) {
+      serverErrors.value = error.response.data.errors;
+    } else {
+      printError(error);
+    }
+  }
+}
+```
+
+## Composable do formularzy
+
+Wydziel logike formularza do composable (patrz: `composables.instructions.md`):
+
+```typescript
+const { form, errors, submitting, submitForm, resetForm } = useFeatureForm(itemId);
+```
+
+## Zasady
+
+1. **Walidacja client-side** - computed `validationErrors`, nie metody
+2. **Walidacja server-side** - obsluz 422 i pokaz bledy przy polach
+3. **Funkcje walidacji** - reuzywalne, w `utils/validation.ts`
+4. **ValidationBuilder** - dla zlozonych obiektow (nie dla formularzy UI)
+5. **`data-testid`** - na kazdym input i button formularza
+6. **Disable submit** - gdy `!isFormValid` lub `submitting`
+7. **Reset** - czysc formularz po sukcesie lub przy anulowaniu
+8. **Nie waliduj pustych opcjonalnych pol** - sprawdzaj tylko jesli wartosc istnieje