Merge pull request #31 from QuickFlo/quasar-tags-field

quasar tags field

Author: zeejers

docs/guide/components.md

@@ -863,6 +863,183 @@ import type {
 
 ---
 
+## TagsField (Quasar)
+
+A chip-based tags input for arrays of free-form strings. Ideal for email addresses, keywords, labels, or any list where users type and add values.
+
+### Handles
+
+- `type: 'array'` with `'x-render': 'tags'`
+
+### Example Schema
+
+**Email recipients:**
+```typescript
+{
+  type: 'array',
+  title: 'Recipients',
+  description: 'Email addresses to send to',
+  'x-render': 'tags',
+  items: {
+    type: 'string',
+    format: 'email'
+  },
+  minItems: 1
+}
+```
+
+**Keywords:**
+```typescript
+{
+  type: 'array',
+  title: 'Keywords',
+  'x-render': 'tags',
+  'x-placeholder': 'Add keywords...',
+  items: {
+    type: 'string',
+    minLength: 2
+  }
+}
+```
+
+### Features
+
+- **Type and press Enter** to add a new tag
+- **Paste multiple values** - comma/semicolon/newline separated values are parsed automatically
+- **Click X to remove** tags
+- **Per-item validation** - invalid items show as red chips with error icon
+- **Duplicate prevention** - same value won't be added twice
+- **Smart placeholder** - auto-detects email format for contextual placeholder
+- **Full QChip customization** - color, icon, outline, size, etc.
+
+### Per-Item Validation
+
+The TagsField validates each item against the `items` schema:
+
+- `format: 'email'` - validates email format
+- `format: 'url'` - validates URL format
+- `minLength` / `maxLength` - validates string length
+- `pattern` - validates against regex pattern
+- `enum` - validates against allowed values
+
+Invalid items are displayed as **red chips with an error icon** and trigger validation errors that block form submission.
+
+### Schema Extensions
+
+| Extension | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `x-render` | `'tags'` | - | Required. Enables tags input mode |
+| `x-placeholder` | `string` | Auto-detected | Custom placeholder text |
+
+### QuickForms Features (`x-quickforms-quasar`)
+
+**Chip customization:**
+```typescript
+{
+  type: 'array',
+  title: 'Tags',
+  'x-render': 'tags',
+  items: { type: 'string' },
+  'x-quickforms-quasar': {
+    chip: {
+      color: 'secondary',      // Quasar color
+      textColor: 'white',      // Text color
+      icon: 'label',           // Icon inside chip
+      outline: true,           // Outline style
+      dense: true,             // Dense mode
+      square: true             // Square corners
+    }
+  }
+}
+```
+
+**Custom separator pattern:**
+```typescript
+{
+  type: 'array',
+  title: 'Emails',
+  'x-render': 'tags',
+  items: { type: 'string', format: 'email' },
+  'x-quickforms-quasar': {
+    separator: /[,;\n]+/  // Only split on comma, semicolon, newline (not spaces)
+  }
+}
+```
+
+**Default chip props:**
+```typescript
+// Default styling applied to all chips
+{
+  removable: true,
+  dense: true,
+  color: 'primary',
+  textColor: 'white'
+}
+```
+
+### Global Defaults
+
+```typescript
+const options: QuasarFormOptions = {
+  registry: createQuasarRegistry(),
+  quickformsDefaults: {
+    tags: {
+      chip: {
+        color: 'accent',
+        textColor: 'white',
+        dense: true
+      },
+      separator: /[,;\s]+/  // Default: comma, semicolon, or whitespace
+    }
+  }
+}
+```
+
+### Native Quasar Props
+
+The underlying QSelect accepts native props via `x-quasar-props`:
+
+```typescript
+{
+  type: 'array',
+  title: 'Tags',
+  'x-render': 'tags',
+  items: { type: 'string' },
+  'x-quasar-props': {
+    outlined: true,
+    filled: false,
+    color: 'secondary',
+    dense: true
+  }
+}
+```
+
+### Comparison: TagsField vs ArrayField vs MultiEnumField
+
+| Feature | TagsField | ArrayField | MultiEnumField |
+|---------|-----------|------------|----------------|
+| Use case | Free-form input | Structured items | Fixed options |
+| Input method | Type + Enter | Add button | Select from list |
+| Display | Chips inline | Expandable items | Chips |
+| Validation | Per-item | Per-item | Enum only |
+| Schema | `x-render: 'tags'` | `type: 'array'` | `items.enum` |
+
+**When to use TagsField:**
+- Email addresses (to, cc, bcc)
+- Keywords or labels
+- Any free-form list where users type values
+
+**When to use ArrayField:**
+- Complex item objects
+- Items with multiple fields
+- Items that need individual editing
+
+**When to use MultiEnumField:**
+- Fixed set of allowed values
+- Selecting from predefined options
+
+---
+
 ## ArrayField
 
 Renders dynamic array fields with add/remove buttons.

docs/guide/quasar.md

@@ -76,6 +76,7 @@ The Quasar package provides pre-built Quasar-wrapped components:
 - **QuasarDateTimeField** - `QInput` with `QDate` and `QTime` popups
 - **QuasarObjectField** - `QExpansionItem` for nested objects
 - **QuasarArrayField** - `QCard` with add/remove buttons
+- **QuasarTagsField** - `QSelect` chips input for free-form arrays (emails, keywords)
 - **QuasarOneOfField** - `QSelect` for conditional schemas
 
 ## Configuration Options
@@ -193,6 +194,35 @@ Customize array field buttons with native QBtn props:
 - `addButton` - Native QBtn props (label, icon, color, size, push, fab, etc.)
 - `removeButton` - Native QBtn props
 
+#### Tags/Chips Input
+
+For free-form arrays like email addresses or keywords, use `x-render: 'tags'`:
+
+```typescript
+{
+  type: 'array',
+  title: 'Email Recipients',
+  'x-render': 'tags',
+  items: {
+    type: 'string',
+    format: 'email'
+  },
+  'x-quickforms-quasar': {
+    chip: {
+      color: 'primary',
+      icon: 'email'
+    },
+    separator: /[,;\n]+/  // Custom paste separator
+  }
+}
+```
+
+**Tags Properties:**
+- `chip` - Native QChip props (color, textColor, icon, outline, dense, etc.)
+- `separator` - RegExp or string pattern for parsing pasted values (default: `/[,;\s]+/`)
+
+See [TagsField documentation](/guide/components#tagsfield-quasar) for full details.
+
 ## Supported Formats
 
 QuickForms Quasar supports all standard JSON Schema formats:
@@ -303,6 +333,10 @@ interface QuasarFormOptions extends FormOptions {
       addButton?: Record<string, any>
       removeButton?: Record<string, any>
     }
+    tags?: {
+      chip?: Record<string, any>        // QChip props for tag chips
+      separator?: RegExp | string       // Paste separator pattern
+    }
     jsoneditor?: {
       height?: string             // Editor height (default: '300px')
       darkTheme?: boolean         // Use dark theme (default: false, auto-detects from Quasar Dark)

docs/guide/schema-extensions.md

@@ -281,7 +281,11 @@ All `x-*` attributes are optional. QuickForms works perfectly with standard JSON
 - `addButton` - Native QBtn props
 - `removeButton` - Native QBtn props
 
-**Related:** [Quasar Package Docs](/guide/quasar#quickforms-convenience-features)
+**For Tags (arrays with `x-render: 'tags'`):**
+- `chip` - Native QChip props (color, textColor, icon, outline, dense, etc.)
+- `separator` - RegExp or string pattern for parsing pasted values (default: `/[,;\s]+/`)
+
+**Related:** [Quasar Package Docs](/guide/quasar#quickforms-convenience-features), [TagsField](/guide/components#tagsfield-quasar)
 
 ---
 
@@ -542,8 +546,10 @@ All `x-*` attributes are optional. QuickForms works perfectly with standard JSON
 - `'datetime'` - Date/time picker field (Quasar only)
 - `'object'` - Object field with nested properties
 - `'array'` - Array field with add/remove items
+- `'tags'` - Chip-based tags input for arrays (Quasar only) - ideal for emails, keywords
 - `'keyvalue'` - Key-value pair editor
 - `'json'` or `'jsoneditor'` - JSON code editor with syntax highlighting, linting, and formatting
+- `'condition-builder'` or `'jsonlogic-builder'` - Visual JSONLogic condition builder (Quasar only)
 
 **Use Cases:**
 - **Override default renderers**: Force a string field even when a custom renderer would normally match

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quickflo/quickforms",
-  "version": "1.14.8",
+  "version": "1.15.0",
   "description": "Framework-agnostic core for QuickForms - JSON Schema form generator",
   "type": "module",
   "main": "./dist/index.js",

packages/quasar/dev/App.vue

@@ -196,6 +196,47 @@ const schema: JSONSchema = {
       },
     },
 
+    // === TAGS INPUT (CHIPS) ===
+    emailRecipients: {
+      type: "array",
+      title: "Email Recipients",
+      description:
+        "Chip-based tags input for emails. Type and press Enter, or paste multiple comma-separated values.",
+      "x-render": "tags",
+      items: {
+        type: "string",
+        format: "email",
+      },
+      minItems: 1,
+      "x-quickforms-quasar": {
+        chip: {
+          color: "primary",
+          textColor: "white",
+          icon: "email",
+        },
+      },
+    },
+
+    // === TAGS INPUT (CUSTOM STYLING) ===
+    keywords: {
+      type: "array",
+      title: "Keywords",
+      description: "Tags with custom chip styling - try pasting: vue, react, angular",
+      "x-render": "tags",
+      items: {
+        type: "string",
+      },
+      "x-placeholder": "Add keywords...",
+      "x-quickforms-quasar": {
+        chip: {
+          color: "secondary",
+          outline: true,
+          dense: true,
+        },
+        separator: /[,;\n]+/, // Only split on comma, semicolon, newline (not spaces)
+      },
+    },
+
     // === ARRAY OF OBJECTS ===
     teamMembers: {
       type: "array",

packages/quasar/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quickflo/quickforms-quasar",
-  "version": "1.14.8",
+  "version": "1.15.0",
   "description": "Quasar UI components for QuickForms - JSON Schema form generator",
   "type": "module",
   "main": "./dist/index.js",