@maltjoy/mcp-server 0.4.0 → 0.6.0-beta.0

package/dist/doc/VJoyDropzone/guideline.md

@@ -0,0 +1,390 @@
+---
+component: VJoyDropzone
+status: draft
+language: en
+dsds: JoyDropzone.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Dropzone
+
+Use **`VJoyDropzone`** when the user needs to upload one or more files by dragging them into a target area or browsing the file system.
+
+It supports single or multiple selection, MIME-type and size validation, per-file update/delete actions, and slots for helper text and custom file rows. Bind with `v-model` to an array of `File` instances or objects with at least a `name` property (for already-uploaded files).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyDropzone` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyDropzone docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoydropzone--docs) |
+| **DSDS (machine)** | [`JoyDropzone.dsds.json`](./JoyDropzone.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyDropzone")` |
+
+---
+
+## When to use this component
+
+Use a dropzone when someone must attach a document or image — résumé, invoice, identity proof, portfolio asset — and drag-and-drop or browse is the right interaction.
+
+Pair it with a visible label (`label` prop or external `VJoyLabel`), constraints in `dropzone-subtitle` or `dropzone-legend` (accepted formats, max size), and form-level validation via the `invalid` prop when the field is required.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A single compact file picker without drag-and-drop chrome | Native `<input type="file">` styled inside a form — only when design explicitly allows; prefer `VJoyDropzone` for consistency |
+| Upload progress / async server upload UI with cancel buttons | Compose upload logic in the app; `VJoyDropzone` manages selection and validation, not network transfer |
+| Image cropping or in-place editing before upload | A dedicated cropper/editor flow — then pass the result into `v-model` |
+| Choosing from files already stored in the product | A file browser / document picker — not a local filesystem dropzone |
+| Custom-styled drag area / ad-hoc file list | Still use `VJoyDropzone` + Joy tokens and slots — don’t reinvent chrome |
+
+> **Legacy Stencil (`joy-dropzone`):** do not port deprecated props (`loading`, `buttonText`, `buttonCancelText`, `uploadingText`, `descriptionText`, …). The Vue component uses slots and `v-model` instead.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `.joy-dropzone` wrapper; state classes (`--empty`, `--dragover`, `--invalid`, `--disabled`) |
+| Label | No | `VJoyLabel` from the `label` prop, associated with the hidden file input via `name` / `id` |
+| Drop area | Yes | `.joy-dropzone__area` — dashed border (empty) or solid border (filled) |
+| Hidden file `<input>` | Yes | `type="file"`; visually hidden; `tabindex="-1"`; opened programmatically on browse / update |
+| File list | When `v-model` has items | `VJoyDropzoneFileItem` rows (name, optional info, update/delete actions) |
+| Instruction block | When empty, or multiple with no invalid files | Icon, description (`dropzone-description`), subtitle (`dropzone-subtitle`) |
+| Browse link | In default description | `VJoyLink` inside default copy — “browse” opens the file picker |
+| Legend | No | `dropzone-legend` slot below the area (helper / requirements) |
+| Form error | When validation fails (single-file mode) | `VJoyFormError` below the area — replaces legend while error is shown |
+| Per-file error | Multiple mode only | Inline message on the offending `VJoyDropzoneFileItem` |
+
+### Default values
+
+- `multiple` defaults to **`false`**
+- `accept` defaults to **`[]`** (all MIME types allowed)
+- `maxSize` defaults to **`32`** (megabytes per file)
+- `deleteLabel` defaults to **`"Delete this file"`**
+- `updateLabel` defaults to **`"Update this file"`**
+- `errorTextFormat` defaults to **`"This format is not supported"`**
+- `errorTextMaxSize` defaults to a message including `maxSize` (e.g. “The file is over 32MB…”)
+- `errorTextFormatAndMaxSize` defaults to a combined format + size message
+- `canDelete` defaults to **`true`**
+- `disabled` defaults to **`false`**
+- `invalid` defaults to **`false`**
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+---
+
+## Variants
+
+`VJoyDropzone` has no visual `variant` prop. Behavior splits into **upload mode** and **surface state**.
+
+### Single file (`multiple` false, default)
+
+Use when exactly one attachment is expected — profile document, signed contract, single receipt.
+
+Replacing a file updates the sole item in `v-model`. Format/size errors show in `VJoyFormError` below the zone; `dropzone-legend` is hidden while that error is visible.
+
+### Multiple files (`multiple` true)
+
+Use when several attachments are allowed — supporting documents, gallery uploads, batch imports.
+
+New files append to `v-model`. Format/size errors appear on each invalid row; the instruction block stays visible so users can add more files (unless every file is valid). `dropzone-legend` remains visible alongside per-file errors.
+
+### Not in the API: upload progress / CTA buttons
+
+ZeroHeight and the legacy Stencil `joy-dropzone` describe **Upload** / **Cancel** buttons and a **loading** state. **`VJoyDropzone` does not expose these.** Handle server upload, progress, and cancellation in application code after files are in `v-model`.
+
+### Not in the API: file extension strings in `accept`
+
+Validation compares `file.type` (MIME) against `accept` entries. Do not pass bare extensions like `".pdf"` — use MIME types such as `application/pdf`, `image/jpeg`.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Empty (default) | Dashed neutral border; cloud icon; “Drag and drop…” + browse link; click or drop adds files |
+| Drag over | Secondary border and tinted background while a file hovers (not when `disabled`) |
+| Filled | Solid border, neutral background; file row(s) with name; update/delete icon buttons |
+| Invalid (file rules) | Error border and icon color; single mode → `VJoyFormError`; multiple → per-file error text |
+| Invalid (`invalid` prop) | Same error styling for parent form feedback (e.g. required empty field) — does not replace MIME/size checks |
+| Disabled | Muted chrome; no drag, browse, update, or delete; explain why nearby |
+| With legend | Helper text in `dropzone-legend` below the area (hidden in single-file mode when a file validation error is shown) |
+
+The exposed `invalid` ref reflects **file validation** (`accept`, `maxSize`) only. The `invalid` **prop** is for **external** form state. Either or both can apply the invalid appearance.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Labels and forms
+
+- **MUST** provide a visible label (`label`, `VJoyLabel`, or equivalent) for every dropzone in a form.
+- **MUST** set `name` uniquely on the page — it wires `id`, label `for`, and the native file input.
+- **SHOULD** wrap label + dropzone + errors in `VJoyFormGroup` for consistent spacing.
+- **SHOULD** state accepted formats and max size in `dropzone-subtitle` or `dropzone-legend`.
+
+### Implementation
+
+- **MUST** bind `v-model` to an array (`File[]` or `{ name: string }[]` for pre-existing files).
+- **MUST** use MIME types in `accept` (e.g. `['application/pdf', 'image/jpeg']`).
+- **MUST** style with Joy tokens — no custom `.joy-dropzone` border, radius, or padding overrides.
+- **MUST NOT** invent props (`loading`, `buttonText`, `legend` as a prop, …).
+- **MUST** override `deleteLabel` / `updateLabel` when the default strings are too generic for context.
+- **SHOULD** use `canDelete={false}` when files must not be removable (audit trail) while keeping update available.
+- **SHOULD** read exposed `invalid` (template ref) or validate `v-model` before submit when `accept` / `maxSize` matter.
+
+### Validation and errors
+
+- **MUST** set `invalid` when the parent form marks the field required and empty.
+- **MUST** show file rule failures via built-in messages (`errorText*` props) — not only red borders.
+- **MUST NOT** rely on border color alone for required-field errors — use `invalid` + helper copy or `VJoyFormError` from the parent when appropriate.
+- **SHOULD** customize `errorTextFormat`, `errorTextMaxSize`, and `errorTextFormatAndMaxSize` when defaults are too vague.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `v-model` + unique `name` | Orphan dropzone with no label |
+| MIME types in `accept` | Extension strings like `.pdf` |
+| `dropzone-subtitle` for “PDF, 10 MB max” | Requirements only in error messages after failure |
+| `invalid` for required empty field | Expect `invalid` prop to validate file type/size |
+| App-level upload after selection | Built-in Upload/Cancel buttons from Stencil |
+| Joy dropzone tokens | Hardcoded dashed borders or custom file rows |
+
+---
+
+## Content
+
+The dropzone exposes description, subtitle, legend, and error copy. All must help users pick a **valid** file the **first** time.
+
+### Label formula
+
+**Noun phrase** describing what to upload:
+
+- ✅ Supporting documents
+- ✅ Profile photo
+- ✅ Signed contract
+
+Use sentence case. Match terminology used elsewhere on the form.
+
+### Description formula (default slot)
+
+**Drag instruction + browse action** — the default is “Drag and drop a document, or **browse**”. Override with `dropzone-description` when the asset type is specific:
+
+- ✅ Drag and drop your CV, or **browse**
+- ✅ Drag and drop an invoice, or **browse**
+
+Keep the browse affordance as a link (`VJoyLink` in the slot) so keyboard and screen-reader users can open the picker.
+
+### Subtitle / legend formula
+
+**Constraints in one line** — formats and size:
+
+- ✅ PDF or JPEG. Maximum 10 MB per file.
+- ✅ One file only. PNG, max 5 MB.
+
+Use `dropzone-subtitle` inside the zone; use `dropzone-legend` for supplementary helper text below.
+
+### Error messages
+
+Explain **what failed** and **how to fix it**:
+
+- ✅ This format is not supported. Upload a PDF or JPEG file.
+- ✅ The file is over 10 MB. Upload a file smaller than 10 MB.
+- ❌ Invalid file
+- ❌ Upload failed
+
+Override via `errorTextFormat`, `errorTextMaxSize`, and `errorTextFormatAndMaxSize` when defaults need product-specific wording.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every dropzone has a visible label — not description-only |
+| **MUST** | Error messages state the problem and the fix |
+| **MUST** | `deleteLabel` / `updateLabel` describe the action on **this** file |
+| **MUST NOT** | Use “please,” “thank you,” or Latinisms (per Joy content guidelines) |
+| **SHOULD** | Use present tense and active voice |
+| **SHOULD** | Use sentence case and terminal punctuation in helper lines |
+| **SHOULD** | Keep subtitle/legend to one short line when possible |
+| **SHOULD** (FR) | Follow French grammar for labels and error strings when the UI is localized |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `input[type="file"]` for selection; visible label via `VJoyLabel` or external label with matching `for` |
+| Name | From `label` prop or associated `VJoyLabel`; file actions named via `updateLabel` / `deleteLabel` on `VJoyIconButton` |
+| Keyboard | Browse via label/link activation; hidden input is not tab-stopped (`tabindex="-1"`) — ensure the instruction area / link is reachable |
+| Focus | Update and delete are real buttons (`VJoyIconButton`); custom `file-actions` must be focusable and named |
+| Drag and drop | Supplementary to browse — never the only path; click/tap must open the file picker |
+| Invalid | Error border + `VJoyFormError` (single) or per-file error text (multiple); `role="alert"` via `VJoyFormError` |
+| Disabled | No interaction; muted styles; **explain why** in nearby text — do not rely on color alone |
+| Custom slots | `file-actions` icons need `label` / accessible names; decorative icons `aria-hidden` |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoyDropzone,
+  VJoyFormGroup,
+  VJoyLabel,
+} from '@maltjoy/core-vue'
+
+const files = ref<File[]>([])
+const documents = ref<{ name: string }[]>([])
+const showRequiredError = ref(false)
+</script>
+
+<template>
+  <!-- Single file, default copy -->
+  <VJoyDropzone name="cv-upload" v-model="files" label="CV" />
+
+  <!-- Constrained upload with helper text -->
+  <VJoyDropzone
+    name="invoice"
+    v-model="files"
+    label="Invoice"
+    :accept="['application/pdf', 'image/jpeg']"
+    :max-size="10"
+  >
+    <template #dropzone-subtitle>PDF or JPEG. Maximum 10 MB.</template>
+    <template #dropzone-legend>We use this document for billing verification only.</template>
+  </VJoyDropzone>
+
+  <!-- Multiple files with existing server-side names -->
+  <VJoyDropzone name="attachments" v-model="documents" multiple>
+    <template #file-information="{ file }">
+      Uploaded on {{ (file as { uploadedDate?: string }).uploadedDate }}
+    </template>
+  </VJoyDropzone>
+
+  <!-- External label + required validation -->
+  <VJoyFormGroup>
+    <VJoyLabel for="contract-upload" required>Signed contract</VJoyLabel>
+    <VJoyDropzone
+      id="contract-upload"
+      name="contract-upload"
+      v-model="files"
+      :invalid="showRequiredError && files.length === 0"
+      :accept="['application/pdf']"
+    >
+      <template #dropzone-subtitle>PDF only. Maximum 32 MB.</template>
+    </VJoyDropzone>
+  </VJoyFormGroup>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyDropzone` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyLabel` | Rich labels (legend, tooltip, required) above the dropzone |
+| `VJoyFormGroup` | Group label, dropzone, and errors with consistent gap |
+| `VJoyFormError` | Additional form-level errors outside built-in file validation |
+| `VJoyIconButton` | Custom per-file actions in `file-actions` |
+| `VJoyLink` | Browse affordance inside `dropzone-description` |
+| `VJoyWrapper` | Layout around multiple form fields |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyDropzone.dsds.json`](./JoyDropzone.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Local file upload with drag-and-drop | `VJoyDropzone` | Custom dashed `div` + hidden input |
+| Single attachment | `VJoyDropzone` (default `multiple`) | `multiple` with only one slot |
+| Several attachments | `VJoyDropzone` + `multiple` | Repeated single dropzones |
+| Show already-uploaded file names | `v-model` with `{ name: string }[]` | Fake rows outside the component |
+| Required empty field on submit | `invalid` prop + parent validation | Only red border, no message |
+| PDF/JPEG only | `accept` with MIME types | `accept=".pdf,.jpg"` |
+| Upload progress / cancel | App logic after `v-model` update | `loading`, `buttonText`, Stencil-only props |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyDropzone")` before generating props.
+2. **MUST** bind `v-model` to an array (`File` or `{ name: string }` items).
+3. **MUST** set unique `name` on every instance.
+4. **MUST** use MIME strings in `accept` (e.g. `application/pdf`, not `.pdf`).
+5. **MUST** set `invalid` for parent-required validation; use `errorText*` for format/size copy.
+6. **MUST NOT** emit Stencil-only props (`loading`, `buttonText`, `buttonCancelText`, `uploadingText`, `legend` as prop, …).
+7. **MUST NOT** override `.joy-dropzone` border, radius, background, or padding.
+8. **SHOULD** populate `dropzone-subtitle` with format and size limits when `accept` or `maxSize` is restricted.
+9. **SHOULD** set contextual `deleteLabel` / `updateLabel` (e.g. “Remove invoice”, “Replace invoice”).
+10. **SHOULD** use `VJoyFormGroup` + `VJoyLabel` when the label needs required/optional markers.
+
+### Valid props (from Joy MCP)
+
+| Prop | Notes |
+| --- | --- |
+| `name` | Required string, unique per page |
+| `modelValue` / `v-model` | Required `(File \| { name: string })[]` |
+| `multiple` | Boolean, default `false` |
+| `accept` | `string[]` MIME types, default `[]` |
+| `maxSize` | Number (MB), default `32` |
+| `label` | Optional top label |
+| `canDelete` | Boolean, default `true` |
+| `disabled` | Boolean, default `false` |
+| `invalid` | Boolean, external form state |
+| `deleteLabel`, `updateLabel` | Accessible names for file actions |
+| `errorTextFormat`, `errorTextMaxSize`, `errorTextFormatAndMaxSize` | Validation copy |
+
+Slots: `dropzone-description`, `dropzone-subtitle`, `dropzone-legend`, `file-information`, `file-actions` (slot prop `file`).
+
+### Checklist
+
+- [ ] Correct component (`VJoyDropzone` or named alternative)
+- [ ] Props from MCP only — no Stencil-only API
+- [ ] `v-model` array + unique `name`
+- [ ] Visible label (prop or `VJoyLabel`)
+- [ ] MIME types in `accept` when restricted
+- [ ] `dropzone-subtitle` / `dropzone-legend` for constraints
+- [ ] `invalid` for required-empty; built-in errors for format/size
+- [ ] No custom dropzone chrome CSS
+- [ ] `deleteLabel` / `updateLabel` contextual when needed
+- [ ] Disabled state explained if user-visible
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyDropzone.dsds.json`](./JoyDropzone.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants (modes) | `variants` |
+| States | `states` |
+| Best practices / content rules | `guidelines` (+ `content`) |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |
+| Imports | `imports` in JSON |
+| Token sizing | `design-specifications` in JSON (`--joy-core-radius-4`, `--joy-form-border-width`, form-field height on file rows) |

package/dist/doc/VJoyDropzone/metadata.json

@@ -1,7 +1,7 @@
 {
   "name": "JoyDropzone",
   "displayName": "VJoyDropzone",
-  "description": "A file upload component with drag-and-drop functionality for handling file selection and management.\nSupports single or multiple file uploads, file validation and customizable file displays.\nFeatures visual feedback for drag states, error handling, and flexible content slots for file information and actions.\n\nThe dropzone required as `v-model` an array containing objects with at least the \"name\" property.",
+  "description": "A file upload component with drag-and-drop functionality for handling file selection and management.\nSupports single or multiple file uploads, file validation and customizable file displays.\nFeatures visual feedback for disabled, invalid, and drag states, error handling, and flexible content slots for file information and actions.\n\nThe dropzone requires a `v-model` bound to an array containing objects with at least the `name` property (or `File` instances).\n\nUse `label` to display a label above the dropzone. Use `canDelete` (default `true`) to hide the delete button on file items while keeping update available. Set `disabled` to block uploads, drag-and-drop, and file actions. Set `invalid` for parent form feedback (e.g. required empty field); it adds invalid styling but does not replace format/size validation. The exposed `invalid` ref only reflects file validation (`accept`, `maxSize`); the `invalid` prop is for external form state—both can apply the invalid appearance.\n\nSlots: `dropzone-description` for the main instruction (default text with browse link), `dropzone-subtitle` for an optional hint line (empty by default), `dropzone-legend` for helper text below the zone, `file-information` and `file-actions` for per-file content (slot prop `file`). In single-file mode, `dropzone-legend` is hidden when a format or size error is shown (`VJoyFormError` instead); in multiple mode, errors appear on each file item and the legend stays visible.",
   "category": "Forms",
   "props": [
     {
@@ -18,6 +18,15 @@
       "description": "Dropzone input name. Must be unique on the page.",
       "possibleValues": null
     },
+    {
+      "name": "label",
+      "type": "string | undefined",
+      "required": false,
+      "description": "Display a label on top of the dropzone.",
+      "possibleValues": [
+        "string"
+      ]
+    },
     {
       "name": "multiple",
       "type": "boolean | undefined",
@@ -115,6 +124,28 @@
         "false",
         "true"
       ]
+    },
+    {
+      "name": "disabled",
+      "type": "boolean | undefined",
+      "required": false,
+      "default": "false",
+      "description": "Disable the dropzone.",
+      "possibleValues": [
+        "false",
+        "true"
+      ]
+    },
+    {
+      "name": "invalid",
+      "type": "boolean | undefined",
+      "required": false,
+      "default": "false",
+      "description": "When true, applies invalid styling (e.g. parent form required + dirty). Does not replace file format/size validation.",
+      "possibleValues": [
+        "false",
+        "true"
+      ]
     }
   ],
   "events": [],
@@ -127,6 +158,10 @@
       "name": "dropzone-description",
       "description": "Block description of the dropzone"
     },
+    {
+      "name": "dropzone-subtitle",
+      "description": "Block subtitle of the dropzone"
+    },
     {
       "name": "file-information",
       "description": "Add information under the file name"