@ciwergrp/nuxid 1.6.1 → 1.6.3

package/docs/.docs/form-validation/rules.md

@@ -0,0 +1,418 @@
+---
+title: Validation Rules
+outline: [2, 3]
+---
+
+# Validation Rules
+
+This page documents all client-side validation rules supported by `src/runtime/validator.ts`.
+Use these rules with `createValidationRules` by passing an array of rule strings per field.
+
+Common usage:
+
+```typescript
+const rules = createValidationRules(
+  {
+    name: ['required', 'string', 'min:2'],
+    email: ['required', 'email'],
+  },
+  formState,
+)
+```
+
+Notes:
+- Empty means `null`, `undefined`, or `''`.
+- Many rules skip validation on empty values unless the rule itself implies required behavior.
+- If a field has both `required` and `nullable`, the validator throws a runtime error.
+
+## Rule Reference
+
+### required
+- Summary: Value must be present.
+- Technique: Element Plus `required: true`.
+- Use: `'required'`
+- Example: `['required']`
+
+### string
+- Summary: Value must be a string.
+- Technique: `typeof value === 'string'` (empty values pass).
+- Use: `'string'`
+- Example: `['string']`
+
+### nullable
+- Summary: Allows empty values and skips remaining rules when empty.
+- Technique: Early exit when empty and not `required`.
+- Use: `'nullable'`
+- Example: `['nullable', 'email']`
+
+### email
+- Summary: Must be a valid email address.
+- Technique: Element Plus `type: 'email'`.
+- Use: `'email'`
+- Example: `['email']`
+
+### accepted
+- Summary: Must be accepted (yes/on/1/true).
+- Technique: String/boolean normalization check.
+- Use: `'accepted'`
+- Example: `['accepted']`
+
+### accepted_if:field,value,...
+- Summary: Must be accepted if another field equals any value.
+- Technique: Compare other field then apply `accepted` check.
+- Use: `'accepted_if:newsletter,true'`
+- Example: `['accepted_if:newsletter,true']`
+
+### boolean
+- Summary: Must be boolean-like (true/false/0/1/'0'/'1').
+- Technique: Simple membership check.
+- Use: `'boolean'`
+- Example: `['boolean']`
+
+### filled
+- Summary: If field exists, it must not be empty.
+- Technique: Checks presence + non-empty value.
+- Use: `'filled'`
+- Example: `['filled']`
+
+### present
+- Summary: Field key must exist in the form state.
+- Technique: Path existence check (`hasNestedKey`).
+- Use: `'present'`
+- Example: `['present']`
+
+### required_if:field,value,...
+- Summary: Required when another field equals any value.
+- Technique: Compare other field then require non-empty.
+- Use: `'required_if:status,active'`
+- Example: `['required_if:status,active']`
+
+### required_unless:field,value,...
+- Summary: Required unless another field equals any value.
+- Technique: Compare other field then require non-empty.
+- Use: `'required_unless:role,admin'`
+- Example: `['required_unless:role,admin']`
+
+### required_with:field1,field2,...
+- Summary: Required if any listed field is filled.
+- Technique: `hasAnyFilled` then require non-empty.
+- Use: `'required_with:phone,email'`
+- Example: `['required_with:phone,email']`
+
+### required_with_all:field1,field2,...
+- Summary: Required if all listed fields are filled.
+- Technique: `hasAllFilled` then require non-empty.
+- Use: `'required_with_all:lat,lng'`
+- Example: `['required_with_all:lat,lng']`
+
+### required_without:field1,field2,...
+- Summary: Required if any listed field is empty.
+- Technique: Require non-empty unless any other is filled.
+- Use: `'required_without:email,phone'`
+- Example: `['required_without:email,phone']`
+
+### required_without_all:field1,field2,...
+- Summary: Required if all listed fields are empty.
+- Technique: Require non-empty unless all others are filled.
+- Use: `'required_without_all:email,phone'`
+- Example: `['required_without_all:email,phone']`
+
+### prohibited
+- Summary: Must be empty.
+- Technique: Fail if value is filled.
+- Use: `'prohibited'`
+- Example: `['prohibited']`
+
+### prohibited_if:field,value,...
+- Summary: Must be empty when another field equals any value.
+- Technique: Compare other field then fail if filled.
+- Use: `'prohibited_if:role,guest'`
+- Example: `['prohibited_if:role,guest']`
+
+### prohibited_unless:field,value,...
+- Summary: Must be empty unless another field equals any value.
+- Technique: Compare other field then fail if filled.
+- Use: `'prohibited_unless:role,admin'`
+- Example: `['prohibited_unless:role,admin']`
+
+### prohibits:field1,field2,...
+- Summary: If this field is filled, listed fields must be empty.
+- Technique: On filled value, check other fields for emptiness.
+- Use: `'prohibits:password'`
+- Example: `['prohibits:password']`
+
+### min:n
+- Summary: Minimum length (string) / count (array) / numeric min.
+- Technique: Element Plus `min` with trim.
+- Use: `'min:3'`
+- Example: `['min:3']`
+
+### max:n
+- Summary: Maximum length (string) / count (array) / numeric max.
+- Technique: Element Plus `max` with trim.
+- Use: `'max:255'`
+- Example: `['max:255']`
+
+### between:min,max
+- Summary: Size between min and max.
+- Technique: Size calculator (number, string length, array length, object keys).
+- Use: `'between:2,10'`
+- Example: `['between:2,10']`
+
+### size:n
+- Summary: Exact size.
+- Technique: Same size calculator as `between`.
+- Use: `'size:3'`
+- Example: `['size:3']`
+
+### same:field
+- Summary: Must match another field.
+- Technique: Compare with `getNestedValue`.
+- Use: `'same:password'`
+- Example: `['same:password']`
+
+### different:field
+- Summary: Must be different from another field.
+- Technique: Compare with `getNestedValue`.
+- Use: `'different:username'`
+- Example: `['different:username']`
+
+### alpha
+- Summary: Letters only.
+- Technique: Regex `/^[a-z]+$/i`.
+- Use: `'alpha'`
+- Example: `['alpha']`
+
+### alpha_num
+- Summary: Letters and numbers only.
+- Technique: Regex `/^[a-z0-9]+$/i`.
+- Use: `'alpha_num'`
+- Example: `['alpha_num']`
+
+### alpha_dash
+- Summary: Letters, numbers, dashes, underscores.
+- Technique: Regex `/^[\\w-]+$/`.
+- Use: `'alpha_dash'`
+- Example: `['alpha_dash']`
+
+### alphanumeric_space
+- Summary: Letters, numbers, spaces, dashes, underscores.
+- Technique: Regex `/^[\\w -]+$/`.
+- Use: `'alphanumeric_space'`
+- Example: `['alphanumeric_space']`
+
+### alpha_space
+- Summary: Letters, spaces, dashes, underscores.
+- Technique: Regex `/^[a-z _-]+$/i`.
+- Use: `'alpha_space'`
+- Example: `['alpha_space']`
+
+### numeric
+- Summary: Must be numeric.
+- Technique: `Number(value)` and `isNaN` check.
+- Use: `'numeric'`
+- Example: `['numeric']`
+
+### integer
+- Summary: Must be an integer.
+- Technique: `Number.isInteger(Number(value))`.
+- Use: `'integer'`
+- Example: `['integer']`
+
+### confirmed
+- Summary: Must match `<field>_confirmation`.
+- Technique: Compare with confirmation field path.
+- Use: `'confirmed'`
+- Example: `['confirmed']`
+
+### digits:n
+- Summary: Must be numeric string with exact length.
+- Technique: Regex + length check.
+- Use: `'digits:6'`
+- Example: `['digits:6']`
+
+### digits_between:min,max
+- Summary: Must be numeric string with length in range.
+- Technique: Regex + length range check.
+- Use: `'digits_between:6,8'`
+- Example: `['digits_between:6,8']`
+
+### bail
+- Summary: Placeholder (no-op).
+- Technique: No behavior; included for parity.
+- Use: `'bail'`
+- Example: `['bail', 'required']`
+
+### gt:field
+- Summary: Must be greater than another field.
+- Technique: Numeric comparison via `Number`.
+- Use: `'gt:other'`
+- Example: `['gt:other']`
+
+### gte:field
+- Summary: Must be greater than or equal to another field.
+- Technique: Numeric comparison via `Number`.
+- Use: `'gte:other'`
+- Example: `['gte:other']`
+
+### lt:field
+- Summary: Must be less than another field.
+- Technique: Numeric comparison via `Number`.
+- Use: `'lt:other'`
+- Example: `['lt:other']`
+
+### lte:field
+- Summary: Must be less than or equal to another field.
+- Technique: Numeric comparison via `Number`.
+- Use: `'lte:other'`
+- Example: `['lte:other']`
+
+### starts_with:a,b,c
+- Summary: Must start with any of the given prefixes.
+- Technique: Regex with alternation.
+- Use: `'starts_with:foo,bar'`
+- Example: `['starts_with:foo,bar']`
+
+### ends_with:a,b,c
+- Summary: Must end with any of the given suffixes.
+- Technique: Regex with alternation.
+- Use: `'ends_with:foo,bar'`
+- Example: `['ends_with:foo,bar']`
+
+### regex:pattern
+- Summary: Must match a regex.
+- Technique: `new RegExp(pattern)`.
+- Use: `'regex:^\\d{4}$'`
+- Example: `['regex:^\\d{4}$']`
+
+### date_format:format
+- Summary: Must match a date format.
+- Technique: Format-to-regex (supports `Y m d H i s`).
+- Use: `'date_format:Y-m-d'`
+- Example: `['date_format:Y-m-d']`
+
+### date
+- Summary: Must be a valid `YYYY-MM-DD` date.
+- Technique: Regex + `Date` ISO validation.
+- Use: `'date'`
+- Example: `['date']`
+
+### before:date
+- Summary: Must be before given date.
+- Technique: `Date` comparison.
+- Use: `'before:2024-01-01'`
+- Example: `['before:2024-01-01']`
+
+### after:date
+- Summary: Must be after given date.
+- Technique: `Date` comparison.
+- Use: `'after:2024-01-01'`
+- Example: `['after:2024-01-01']`
+
+### before_or_equal:date
+- Summary: Must be before or equal to given date.
+- Technique: `Date` comparison.
+- Use: `'before_or_equal:2024-01-01'`
+- Example: `['before_or_equal:2024-01-01']`
+
+### after_or_equal:date
+- Summary: Must be after or equal to given date.
+- Technique: `Date` comparison.
+- Use: `'after_or_equal:2024-01-01'`
+- Example: `['after_or_equal:2024-01-01']`
+
+### array
+- Summary: Must be an array.
+- Technique: `Array.isArray`.
+- Use: `'array'`
+- Example: `['array']`
+
+### distinct
+- Summary: Array must not contain duplicates.
+- Technique: `Set(JSON.stringify(item))` comparison.
+- Use: `'distinct'`
+- Example: `['distinct']`
+
+### in_array:field
+- Summary: Value must be in another field's array.
+- Technique: `Array.includes` on referenced field.
+- Use: `'in_array:allowed'`
+- Example: `['in_array:allowed']`
+
+### required_array_keys:key1,key2
+- Summary: Object/array must contain required keys.
+- Technique: `hasOwnProperty` per key.
+- Use: `'required_array_keys:name,email'`
+- Example: `['required_array_keys:name,email']`
+
+### list
+- Summary: Must be a list with sequential indices.
+- Technique: Array and index presence check.
+- Use: `'list'`
+- Example: `['list']`
+
+### url
+- Summary: Must be a valid http/https URL.
+- Technique: `new URL` + protocol check.
+- Use: `'url'`
+- Example: `['url']`
+
+### ip
+- Summary: Must be a valid IPv4 or IPv6 address.
+- Technique: IPv4/IPv6 regex checks.
+- Use: `'ip'`
+- Example: `['ip']`
+
+### hex_color
+- Summary: Must be a valid hex color.
+- Technique: Regex for 3/6 hex digits.
+- Use: `'hex_color'`
+- Example: `['hex_color']`
+
+### lowercase
+- Summary: Must be lowercase.
+- Technique: `value === value.toLowerCase()`.
+- Use: `'lowercase'`
+- Example: `['lowercase']`
+
+### uppercase
+- Summary: Must be uppercase.
+- Technique: `value === value.toUpperCase()`.
+- Use: `'uppercase'`
+- Example: `['uppercase']`
+
+### uuid
+- Summary: Must be a valid UUID (v1-8).
+- Technique: Regex for UUID versions.
+- Use: `'uuid'`
+- Example: `['uuid']`
+
+### ulid
+- Summary: Must be a valid ULID.
+- Technique: Crockford-base32 regex.
+- Use: `'ulid'`
+- Example: `['ulid']`
+
+### timezone
+- Summary: Must be a valid IANA timezone.
+- Technique: `Intl.DateTimeFormat` with `timeZone`.
+- Use: `'timezone'` or `'timezone:region'` (same behavior).
+- Example: `['timezone']`
+
+### in:a,b,c
+- Summary: Value must be one of the listed values.
+- Technique: String set membership.
+- Use: `'in:small,medium,large'`
+- Example: `['in:small,medium,large']`
+
+### multiple_of:n
+- Summary: Numeric value must be a multiple of n.
+- Technique: `Number(value) % n === 0`.
+- Use: `'multiple_of:5'`
+- Example: `['multiple_of:5']`
+
+### decimal:min[,max]
+- Summary: Must be numeric with decimal places in range.
+- Technique: Numeric regex + decimal count.
+- Use: `'decimal:2'` or `'decimal:2,4'`
+- Example: `['decimal:2,4']`

package/docs/.docs/forms/use-form.md

@@ -0,0 +1,58 @@
+# useForm
+
+This helper is implemented in `src/runtime/form.ts` and exported as `useHttp`. The API below matches that implementation.
+
+`useForm` (aka `useHttp`) builds a reactive form object with submit helpers that use Nuxt `$fetch`. It normalizes strings and nested values, supports `FormData` when files are present, and tracks `processing`, `errors`, and `response`.
+
+## Signature
+
+```ts
+const form = useHttp(initialData, formOptions)
+```
+
+## Options
+
+- `alwaysFormData` (boolean): force `FormData` even when there are no files.
+- `fetcher` (function): custom fetcher. Defaults to Nuxt `$fetch`.
+- `fetchOptions` (object): shared options passed to `$fetch` (headers, onResponse, etc).
+
+## Returns
+
+The returned object includes your initial fields plus:
+
+- `submit(method, url, options?)`
+- `post(url, options?)`
+- `patch(url, options?)`
+- `put(url, options?)`
+- `delete(url, options?)`
+- `processing` (boolean)
+- `errors` (any)
+- `response` (object | null)
+
+## Examples
+
+Basic submit:
+
+```ts
+const form = useHttp({ name: '', avatar: null })
+
+await form.post('/api/users')
+```
+
+Send multipart data and attach hooks:
+
+```ts
+const form = useHttp(
+  { name: '', avatar: null, tags: [] },
+  {
+    alwaysFormData: true,
+    fetchOptions: {
+      onResponse({ response }) {
+        console.log('ok', response.ok)
+      },
+    },
+  },
+)
+
+await form.post('/api/users')
+```

package/docs/.docs/helpers/array.md

@@ -0,0 +1,169 @@
+---
+title: Array Helpers
+outline: [2, 3]
+---
+
+# Array Helpers
+
+Array helpers focus on collection utilities like filtering, sorting, grouping, and selection.
+
+Factory style:
+
+```ts
+const first = array().first(['a', 'b'])
+```
+
+Prefix style:
+
+```ts
+const first = First(['a', 'b'])
+```
+
+## Methods
+
+### collapse
+Summary: Flattens an array of arrays by one level using iteration and spreading.
+Parameters: `arrays` (Array<T[]>).
+- Returns: `T[]`.
+- Simple usage: `array().collapse([[1, 2], [3]])` = `[1, 2, 3]`
+- Advanced usage: `array().collapse([[1], null as any, [2, 3]])` = `[1, 2, 3]`
+
+### crossJoin
+Summary: Builds a cartesian product using reduce and nested loops.
+Parameters: `arrays` (T[][]) via rest arguments.
+- Returns: `T[][]`.
+- Simple usage: `array().crossJoin([1, 2], ['a', 'b'])` = `[[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]`
+- Advanced usage: `array().crossJoin([1, 2], ['a'], ['x', 'y'])` = `[[1, 'a', 'x'], [1, 'a', 'y'], [2, 'a', 'x'], [2, 'a', 'y']]`
+
+### every
+Summary: Tests whether all items satisfy a predicate via native `every`.
+Parameters: `array` (T[]), `predicate` ((item, index) => boolean).
+- Returns: `boolean`.
+- Simple usage: `array().every([1, 2], n => n > 0)` = `true`
+- Advanced usage: `array().every([{ role: 'admin', active: true }], u => u.active && u.role === 'admin')` = `true`
+
+### first
+Summary: Returns the first item or first matching item using a forward scan.
+Parameters: `array` (T[]), `callback` ((item, index) => boolean, optional), `defaultValue` (T | null, optional).
+- Returns: `T | null`.
+- Simple usage: `array().first([1, 2, 3])` = `1`
+- Advanced usage: `array().first([{ id: 1 }, { id: 2 }], u => u.id === 1, null)` = `{ id: 1 }`
+
+### flatten
+Summary: Flattens nested arrays to a given depth using recursion.
+Parameters: `input` (T[]), `depth` (number, optional; default: Infinity).
+- Returns: `any[]`.
+- Simple usage: `array().flatten([1, [2, [3]]], 1)` = `[1, 2, [3]]`
+- Advanced usage: `array().flatten([1, [2, [3]]])` = `[1, 2, 3]`
+
+### join
+Summary: Joins array items with optional final glue by splitting head/tail.
+Parameters: `array` (any[]), `glue` (string), `finalGlue` (string, optional).
+- Returns: `string`.
+- Simple usage: `array().join(['a', 'b', 'c'], ', ')` = `'a, b, c'`
+- Advanced usage: `array().join(['a', 'b', 'c'], ', ', ' and ')` = `'a, b and c'`
+
+### last
+Summary: Returns the last item or last matching item using a reverse scan.
+Parameters: `array` (T[]), `callback` ((item, index) => boolean, optional), `defaultValue` (T | null, optional).
+- Returns: `T | null`.
+- Simple usage: `array().last([1, 2, 3])` = `3`
+- Advanced usage: `array().last([{ id: 1 }, { id: 2 }], u => u.id === 2, null)` = `{ id: 2 }`
+
+### map
+Summary: Transforms items with native `map`.
+Parameters: `array` (T[]), `callback` ((item, index) => U).
+- Returns: `U[]`.
+- Simple usage: `array().map([1, 2], n => n * 2)` = `[2, 4]`
+- Advanced usage: `array().map([{ name: 'A' }, { name: 'B' }], (u, i) => ({ ...u, index: i }))` = `[{ name: 'A', index: 0 }, { name: 'B', index: 1 }]`
+
+### mapSpread
+Summary: Spreads tuple items into the callback during mapping.
+Parameters: `array` (T[] of tuples), `callback` ((...args) => U).
+- Returns: `U[]`.
+- Simple usage: `array().mapSpread([[1, 2], [3, 4]], (a, b) => a + b)` = `[3, 7]`
+- Advanced usage: `array().mapSpread([[1, 2], [3, 4]], (min, max) => ({ min, max }))` = `[{ min: 1, max: 2 }, { min: 3, max: 4 }]`
+
+### partition
+Summary: Splits into `[pass, fail]` with a single pass.
+Parameters: `array` (T[]), `predicate` ((item, index) => boolean).
+- Returns: `[T[], T[]]`.
+- Simple usage: `array().partition([1, 2, 3], n => n % 2 === 0)` = `[[2], [1, 3]]`
+- Advanced usage: `array().partition([{ id: 1 }, { id: 2 }], u => u.id === 1)` = `[[{ id: 1 }], [{ id: 2 }]]`
+
+### random
+Summary: Picks one or multiple random items using random indices and splicing.
+Parameters: `array` (T[]), `count` (number, optional).
+- Returns: `T | T[] | undefined`.
+- Simple usage: `array().random([1, 2, 3])` = `2 (random)`
+- Advanced usage: `array().random([1, 2, 3, 4], 2)` = `[3, 1] (random order)`
+
+### reject
+Summary: Filters out items matching a predicate by negating `filter`.
+Parameters: `array` (T[]), `predicate` ((item, index) => boolean).
+- Returns: `T[]`.
+- Simple usage: `array().reject([1, 2, 3], n => n > 2)` = `[1, 2]`
+- Advanced usage: `array().reject([{ id: 1, disabled: false }, { id: 2, disabled: true }], u => u.disabled)` = `[{ id: 1, disabled: false }]`
+
+### shuffle
+Summary: Randomizes order using Fisher-Yates shuffle.
+Parameters: `array` (T[]).
+- Returns: `T[]`.
+- Simple usage: `array().shuffle([1, 2, 3])` = `[2, 1, 3] (random order)`
+- Advanced usage: `array().shuffle([{ id: 1 }, { id: 2 }])` = `[{ id: 2 }, { id: 1 }] (random order)`
+
+### sole
+Summary: Returns the only match or throws if zero/multiple matches.
+Parameters: `array` (T[]), `predicate` ((item, index) => boolean, optional).
+- Returns: `T`.
+- Simple usage: `array().sole([1])` = `1`
+- Advanced usage: `array().sole([{ id: 42 }], u => u.id === 42)` = `{ id: 42 }`
+
+### some
+Summary: Tests whether any item matches a predicate using native `some`.
+Parameters: `array` (T[]), `predicate` ((item, index) => boolean).
+- Returns: `boolean`.
+- Simple usage: `array().some([1, 2], n => n > 1)` = `true`
+- Advanced usage: `array().some([{ role: 'admin' }], u => u.role === 'admin')` = `true`
+
+### sort
+Summary: Sorts ascending by copying and using native `sort`.
+Parameters: `array` (T[]), `comparator` ((a, b) => number, optional).
+- Returns: `T[]`.
+- Simple usage: `array().sort([3, 1, 2])` = `[1, 2, 3]`
+- Advanced usage: `array().sort([{ age: 30 }, { age: 18 }], (a, b) => a.age - b.age)` = `[{ age: 18 }, { age: 30 }]`
+
+### sortDesc
+Summary: Sorts descending by reversing the comparator logic.
+Parameters: `array` (T[]), `comparator` ((a, b) => number, optional).
+- Returns: `T[]`.
+- Simple usage: `array().sortDesc([3, 1, 2])` = `[3, 2, 1]`
+- Advanced usage: `array().sortDesc([{ age: 30 }, { age: 18 }], (a, b) => a.age - b.age)` = `[{ age: 30 }, { age: 18 }]`
+
+### take
+Summary: Takes N items from start or end via `slice`.
+Parameters: `array` (T[]), `limit` (number).
+- Returns: `T[]`.
+- Simple usage: `array().take([1, 2, 3], 2)` = `[1, 2]`
+- Advanced usage: `array().take([1, 2, 3], -1)` = `[3]`
+
+### where
+Summary: Filters items matching a predicate using native `filter`.
+Parameters: `array` (T[]), `predicate` ((item, index) => boolean).
+- Returns: `T[]`.
+- Simple usage: `array().where([1, 2, 3], n => n > 1)` = `[2, 3]`
+- Advanced usage: `array().where([{ id: 1, active: true }, { id: 4, active: true }], u => u.active)` = `[{ id: 1, active: true }, { id: 4, active: true }]`
+
+### whereNotNull
+Summary: Removes `null` and `undefined` values.
+Parameters: `array` (T[]).
+- Returns: `T[]`.
+- Simple usage: `array().whereNotNull([1, null, 2])` = `[1, 2]`
+- Advanced usage: `array().whereNotNull(['a', undefined, 'b'])` = `['a', 'b']`
+
+### wrap
+Summary: Normalizes a value into an array.
+Parameters: `value` (T | T[] | null | undefined).
+- Returns: `T[]`.
+- Simple usage: `array().wrap(1)` = `[1]`
+- Advanced usage: `array().wrap([1, 2])` = `[1, 2]`