@hotmeshio/long-tail 0.9.5 → 0.10.0

package/docs/hitl/x-lt-validation.md

@@ -0,0 +1,168 @@
+# Pre-Submission Validation
+
+The form runs a full validation pass before any submit is accepted. Every visible field is checked in sequence; the first failure displays an inline error and the submit is blocked. The right-side panel opens automatically with a tabular breakdown of all errors; clicking any error item scrolls to and focuses the corresponding field.
+
+---
+
+## Required
+
+Fields listed in the schema's `required` array block submission when empty. A red asterisk marks required fields. Required validation is skipped for fields hidden by `x-lt-showIf` at submission time.
+
+```json
+{
+  "required": ["approved", "reference_code"],
+  "properties": {
+    "approved":       { "type": "boolean" },
+    "reference_code": { "type": "string" }
+  }
+}
+```
+
+---
+
+## Format Guards
+
+`"format": "email"` and `"format": "uri"` are enforced before submission:
+
+| Format | Guard |
+|--------|-------|
+| `"email"` | Must match `user@host.tld` |
+| `"uri"` | Must start with `https://` or `http://` |
+
+Format errors appear inline beneath the field as soon as the field is blurred.
+
+---
+
+## String Length Bounds
+
+| Keyword | Source | Type |
+|---------|--------|------|
+| `minLength` | JSON Schema standard | Static integer |
+| `maxLength` | JSON Schema standard | Static integer |
+| `x-lt-min-length` | Long-tail extension | `"domain.path"` resolved at submission time |
+| `x-lt-max-length` | Long-tail extension | `"domain.path"` resolved at submission time |
+
+Static and dynamic bounds compose: if both `minLength` and `x-lt-min-length` are present, the static value is used (the dynamic path is a fallback only when no static value is set).
+
+```json
+{
+  "properties": {
+    "reference_code": {
+      "type": "string",
+      "minLength": 3
+    },
+    "notes": {
+      "type": "string",
+      "format": "textarea",
+      "x-lt-max-length": "envelope.max_notes_length"
+    }
+  }
+}
+```
+
+When `envelope.max_notes_length` is `500`, the notes field blocks submission once the input exceeds 500 characters. The error reads `Maximum 500 characters (534 entered)`. Textarea fields with a `maxLength` or `x-lt-max-length` bound also show a live `X / N` character counter as you type — the counter turns red when the limit is exceeded, before the form is submitted.
+
+---
+
+## Numeric Bounds
+
+| Keyword | Source | Type |
+|---------|--------|------|
+| `minimum` | JSON Schema standard | Static number |
+| `maximum` | JSON Schema standard | Static number |
+| `exclusiveMinimum` | JSON Schema standard | Static number |
+| `exclusiveMaximum` | JSON Schema standard | Static number |
+| `x-lt-minimum` | Long-tail extension | `"domain.path"` resolved at submission time |
+| `x-lt-maximum` | Long-tail extension | `"domain.path"` resolved at submission time |
+
+Static and dynamic bounds compose: if both `minimum` and `x-lt-minimum` are present, the static value is used.
+
+```json
+{
+  "properties": {
+    "score": {
+      "type": "number",
+      "maximum": 100,
+      "x-lt-minimum": "envelope.min_score"
+    }
+  }
+}
+```
+
+When `envelope.min_score` is `60`, submitting a score of `45` blocks with "Minimum value is 60".
+
+---
+
+## Pattern Guard
+
+Apply a regular expression guard with `pattern`. If the input does not match, the field blocks submission. Provide `x-lt-pattern-error` for a human-readable error message; otherwise the generic "Invalid format" is shown.
+
+```json
+{
+  "properties": {
+    "reference_code": {
+      "type": "string",
+      "pattern": "^[A-Z0-9][A-Z0-9-]*[A-Z0-9]$|^[A-Z0-9]$",
+      "x-lt-pattern-error": "Use uppercase letters, digits, and dashes (e.g. QA-2024-001)"
+    }
+  }
+}
+```
+
+---
+
+## Dynamic Bounds — `"domain.path"` Resolution
+
+`x-lt-minimum`, `x-lt-maximum`, `x-lt-min-length`, and `x-lt-max-length` all accept a `"domain.path"` string. The value is resolved from the escalation context at the moment of submission — the same domain/path convention as `x-lt-showIf` and `x-lt-help` tokens.
+
+| Domain | Resolves against |
+|--------|-----------------|
+| `envelope` | The workflow-sent input envelope |
+| `metadata` | The row's metadata dict |
+| `payload` | The escalation context payload |
+| `escalation` | Top-level escalation row fields |
+
+The path is dot-separated, with optional `[n]` array indices. A missing or non-numeric value at the path means the bound is not enforced for that submission.
+
+**Workflow side — passing the bound in the envelope:**
+
+```typescript
+const decision = await conditionLT<{ score: number; notes: string }>(signalId, {
+  role: 'quality-reviewer',
+  envelope: {
+    min_score: 60,
+    max_notes_length: 500,
+  },
+  metadata: {
+    form_schema: {
+      properties: {
+        score: { type: 'number', maximum: 100, 'x-lt-minimum': 'envelope.min_score' },
+        notes: { type: 'string', 'x-lt-max-length': 'envelope.max_notes_length' },
+      },
+    },
+  },
+});
+```
+
+---
+
+## Error Panel
+
+When the pre-submission pass finds errors, the right-side panel opens automatically on the Errors view. The panel shows a numbered list of issues — field name and message — and each entry is a button: clicking it scrolls the form to the field and focuses it. The panel icon shows a `!` badge when errors are active.
+
+The error panel updates in real-time as fields are corrected — fixing a field removes its entry from the panel immediately, without requiring another submit attempt. The panel clears entirely once all issues are resolved.
+
+---
+
+## Reference Example
+
+`examples/workflows/constraint-form/` is the canonical reference for all constraint guards:
+
+- `approved` — boolean toggle
+- `rejection_reason` — hidden required field (`x-lt-showIf: '!resolver.approved'`)
+- `reference_code` — `pattern` + `minLength` + `x-lt-pattern-error`
+- `score` — `maximum: 100` + `x-lt-minimum: 'envelope.min_score'`
+- `notes` — `x-lt-max-length: 'envelope.max_notes_length'`
+- `checks` — checklist widget with `x-lt-source: 'envelope.checklist_items'`
+
+The `quality-reviewer` role is seeded with two test escalations that carry different `min_score` and `max_notes_length` values so every dynamic bound is exercisable without code changes.

package/docs/hitl/x-lt-widget.md

@@ -0,0 +1,152 @@
+# Custom Widgets (`x-lt-widget`)
+
+For rich inputs beyond standard HTML types, set `x-lt-widget` on any field:
+
+| Widget | Description |
+|--------|------------|
+| `"file-upload"` | File picker with drag-and-drop. Stores a base64 data URL. Use `accept` to filter file types. |
+| `"code-editor"` | Monospace textarea with tab-key support. Use `x-lt-language` for the syntax hint. |
+| `"signature"` | HTML5 Canvas drawing pad. Outputs a PNG data URL. |
+| `"rich-text"` | Tall textarea for formatted text input. |
+| `"markdown"` | Markdown source rendered with headings, tables, lists, code blocks. Editable by default; set `readOnly: true` for a pure content block. |
+| `"checklist"` | Dynamic labeled checkboxes driven by runtime data. Items come from a `"domain.path"` declared in `x-lt-source`. |
+
+---
+
+## File Upload
+
+```json
+{
+  "properties": {
+    "screenshot": {
+      "type": "string",
+      "x-lt-widget": "file-upload",
+      "accept": "image/*",
+      "description": "Upload a screenshot of the issue"
+    },
+    "signed_form": {
+      "type": "string",
+      "x-lt-widget": "file-upload",
+      "accept": ".pdf",
+      "description": "Signed authorization form (PDF)"
+    }
+  }
+}
+```
+
+The submitted value is a base64 data URL (`data:image/png;base64,...`). `accept` follows the HTML `<input accept>` syntax.
+
+---
+
+## Code Editor
+
+```json
+{
+  "properties": {
+    "fix_script": {
+      "type": "string",
+      "x-lt-widget": "code-editor",
+      "x-lt-language": "sql",
+      "description": "SQL migration to apply"
+    }
+  }
+}
+```
+
+`x-lt-language` is a display hint only — the editor does not enforce syntax.
+
+---
+
+## Signature
+
+```json
+{
+  "properties": {
+    "signature": {
+      "type": "string",
+      "x-lt-widget": "signature",
+      "description": "Sign to confirm"
+    }
+  }
+}
+```
+
+The submitted value is a PNG data URL of the canvas drawing.
+
+---
+
+## Markdown
+
+Without `readOnly`, the field is a markdown editor — the resolver writes source in a Write/Preview toggle and the submitted value is the markdown text.
+
+With `readOnly: true`, the field is a rendered content block. The markdown in its `default` displays as HTML inside the form — headings, tables, checklists, callouts. The versioned schema carries the page source itself, so review instructions and SOPs version with the form they belong to.
+
+```json
+{
+  "properties": {
+    "review_guide": {
+      "type": "string",
+      "readOnly": true,
+      "x-lt-widget": "markdown",
+      "x-lt-span": 2,
+      "default": "### Review checklist\n\n1. Confirm the **legal name** matches.\n2. Send a test message before approving.\n\n> Escalate non-standard contract language to legal."
+    }
+  }
+}
+```
+
+---
+
+## Checklist (`x-lt-source`)
+
+A dynamic list of labeled checkboxes driven by runtime data in the escalation context. The item definitions come from a domain path declared in `x-lt-source` — the form schema itself never changes as item count or labels vary across escalations.
+
+The field type must be `"object"`. The submitted value is `Record<string, boolean>` keyed by item id (e.g. `{ "step_0": true, "step_1": false }`).
+
+```json
+{
+  "properties": {
+    "checks": {
+      "type": "object",
+      "description": "Work through each step and check it off.",
+      "x-lt-widget": "checklist",
+      "x-lt-source": "envelope.checklist_items"
+    }
+  },
+  "required": ["checks"]
+}
+```
+
+`x-lt-source` uses the `"domain.path"` convention (same as `x-lt-showIf` and `x-lt-help` tokens). The renderer expects an array of `{ id: string; label: string; required?: boolean }` objects at that path.
+
+- `"envelope"` — for item definitions that are render data only (no query cost). The workflow puts them in `conditionLT`'s `envelope` parameter.
+- `"metadata"` — only when items need to be GIN-indexed and searchable as facets. Adds index cost.
+
+Marking an item `required: true` flags it with an asterisk in the UI. A `required` checklist field is blocked from submission until at least one item is checked. When no items are checked after a submission attempt, every unchecked item that is individually required (or all unchecked items when the field itself is required) highlights in red. Once any item is checked — satisfying the group requirement — all per-item highlights clear.
+
+**Workflow side:**
+
+```typescript
+const checklistItems = [
+  { id: 'doc',     label: 'All supporting documentation is attached', required: true },
+  { id: 'contact', label: 'Contact details have been verified',        required: true },
+  { id: 'photos',  label: 'Before/after photos are present',           required: false },
+];
+
+const decision = await conditionLT<{ checks: Record<string, boolean> }>(signalId, {
+  role: 'checklist-operator',
+  envelope: {
+    checklist_items: checklistItems,
+    formDefaults: {
+      // Pre-populate all checkboxes as unchecked
+      checks: Object.fromEntries(checklistItems.map((i) => [i.id, false])),
+    },
+  },
+});
+
+const allConfirmed = Object.values(decision.checks).every(Boolean);
+```
+
+Pre-populating `formDefaults.checks` opens the form with every checkbox unchecked rather than indeterminate.
+
+The `examples/workflows/checklist-confirmation/` and `examples/workflows/constraint-form/` workflows are complete references.