@appinternalleads/ui 0.2.0

package/spec/question.schema.json

@@ -0,0 +1,549 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "question/1",
+  "title": "Question block",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "slug", "question", "fields"],
+  "properties": {
+    "schema": { "const": "question/1" },
+    "slug": { "$ref": "#/$defs/slug" },
+    "provenance": {
+      "enum": ["declared", "inferred", "derived"],
+      "default": "declared",
+      "description": "declared: the plan named this input. inferred: guessed from context. derived: computed from the run's own output - a ranking, a distribution, a duplicate it found. The three differ in what it costs to be wrong."
+    },
+    "blocking": { "type": "boolean", "default": true },
+    "reason": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Why the run stopped. Blocking only. `question` is what is being asked; this is what went wrong."
+    },
+    "step": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["index", "label"],
+      "properties": {
+        "index": { "type": "integer", "minimum": 1 },
+        "label": { "type": "string", "minLength": 1 }
+      }
+    },
+    "question": { "type": "string", "minLength": 1 },
+    "fields": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/field" }
+    }
+  },
+
+  "$defs": {
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "Kebab-case. Block slugs and field keys share this rule."
+    },
+
+    "option": {
+      "description": "Bare or rich. Rich exists because score and reason must travel to every option shape - a card face showing only a name has hidden the run's work.",
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["value", "label"],
+          "properties": {
+            "value": { "type": "string", "minLength": 1 },
+            "label": { "type": "string", "minLength": 1 },
+            "rank": { "type": "integer", "minimum": 1 },
+            "score": { "type": "number" },
+            "note": { "type": "string" },
+            "pct": { "type": "number", "minimum": 0, "maximum": 100 },
+            "escape": {
+              "type": "boolean",
+              "description": "The way out - an option that admits the gap rather than answering. Rendered muted until picked."
+            }
+          }
+        }
+      ]
+    },
+
+    "submit": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["label"],
+      "properties": {
+        "label": { "type": "string", "minLength": 1 },
+        "empty": { "type": "string", "minLength": 1 }
+      },
+      "description": "At zero the label states the consequence and the button is NOT disabled. {n} interpolates the count."
+    },
+
+    "widgetName": {
+      "enum": ["text-input-field", "text-field", "text-area", "dropdown", "button", "container",
+               "file-upload", "voice-recorder", "date-time-picker", "slider", "range-picker",
+               "radio-button", "checkboxes", "numerical-holder", "horizontal-list-picker",
+               "pie-chart-picker", "card-picker", "arc-picker", "counter-group",
+               "aggregated-input-card"],
+      "description": "A hint, honoured when legal for the field's type and DROPPED when not. Never an error - that is what makes it safe to store."
+    },
+
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tool", "labelPath", "valuePath"],
+      "properties": {
+        "tool": { "type": "string", "minLength": 1 },
+        "args": { "type": "object" },
+        "labelPath": { "type": "string", "minLength": 1 },
+        "valuePath": { "type": "string", "minLength": 1 }
+      },
+      "description": "Runtime options from a sibling LIST_* tool. Carried forward from Field v2 unchanged."
+    },
+
+    "field": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "type", "label"],
+      "properties": {
+        "key": { "$ref": "#/$defs/slug" },
+        "type": {
+          "enum": ["text", "email", "number", "toggle", "date", "datetime",
+                   "enum", "list", "group", "variant", "json",
+                   "range", "counters", "share", "file", "media", "action"]
+        },
+        "control": { "type": "string" },
+        "label": { "type": "string", "minLength": 1 },
+        "required": { "type": "boolean", "default": false },
+        "default": true,
+        "example": { "type": "string" },
+        "hint": { "type": "string" },
+        "constraints": { "type": "object" },
+        "options": { "type": "array" },
+        "itemType": { "type": "string" },
+        "source": { "$ref": "#/$defs/source" },
+        "children": { "type": "array", "items": { "$ref": "#/$defs/field" } },
+        "showIf": { "type": "object", "minProperties": 1 },
+        "preferred": { "$ref": "#/$defs/widgetName" },
+        "multiple": { "type": "boolean", "default": false },
+        "submit": { "$ref": "#/$defs/submit" },
+        "rows": { "type": "array" },
+        "counter": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["text"],
+          "properties": {
+            "text": { "type": "string", "minLength": 1 },
+            "empty": { "type": "string", "minLength": 1 }
+          }
+        },
+        "unit": { "type": "string" },
+        "derived": { "type": "boolean" },
+        "consequence": { "type": "string" },
+        "confirm": { "type": "string" },
+        "done": { "type": "string" },
+        "dismiss": { "type": "string" },
+        "count": { "type": "integer", "minimum": 0 }
+      },
+
+      "allOf": [
+        {
+          "if": { "properties": { "type": { "const": "text" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "enum": ["single", "multi"], "default": "single" },
+              "default": { "type": "string" },
+              "constraints": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "minLength": { "type": "integer", "minimum": 0 },
+                  "maxLength": { "type": "integer", "minimum": 1 },
+                  "pattern": { "type": "string", "format": "regex" }
+                }
+              },
+              "options": false, "itemType": false, "source": false, "children": false
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "email" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "const": "single", "default": "single" },
+              "default": { "type": "string", "format": "email" },
+              "constraints": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": { "maxLength": { "type": "integer", "minimum": 1 } }
+              },
+              "options": false, "itemType": false, "source": false, "children": false
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "number" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "enum": ["single", "stepper", "slider"], "default": "single" },
+              "default": { "type": "number" },
+              "constraints": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "min": { "type": "number" },
+                  "max": { "type": "number" },
+                  "step": { "type": "number", "exclusiveMinimum": 0 },
+                  "precision": { "type": "integer", "minimum": 0 }
+                }
+              },
+              "options": false, "itemType": false, "source": false, "children": false
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "toggle" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "enum": ["switch", "checkbox"], "default": "switch" },
+              "default": { "type": "boolean" },
+              "constraints": false, "example": false,
+              "options": false, "itemType": false, "source": false, "children": false
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "enum": ["date", "datetime"] } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "enum": ["picker", "presets"], "default": "picker" },
+              "default": { "type": "string" },
+              "constraints": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "min": { "type": "string" },
+                  "max": { "type": "string" }
+                }
+              },
+              "options": {
+                "type": "array",
+                "items": { "$ref": "#/$defs/option" },
+                "minItems": 1,
+                "description": "presets only. The value is the RULE (next-monday), never a resolved date - a resolved date is how a run resumed on Thursday books last week."
+              },
+              "itemType": false, "source": false, "children": false
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "enum" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": {
+                "enum": ["select", "radio", "segmented", "chips", "cards", "arc", "checkboxes"],
+                "default": "select"
+              },
+              "default": {
+                "oneOf": [
+                  { "type": "string" },
+                  { "type": "array", "items": { "type": "string" } }
+                ]
+              },
+              "constraints": false,
+              "options": {
+                "type": "array",
+                "items": { "$ref": "#/$defs/option" },
+                "minItems": 1
+              },
+              "itemType": false, "children": false
+            },
+            "anyOf": [
+              { "required": ["options"] },
+              { "required": ["source"] }
+            ],
+            "allOf": [
+              {
+                "description": "A single-select default is a string; a multiple one is an array. Getting this wrong silently seeds the wrong shape into the answer object.",
+                "if": { "properties": { "multiple": { "const": true } }, "required": ["multiple"] },
+                "then": { "properties": { "default": { "type": "array" } } },
+                "else": { "properties": { "default": { "type": "string" } } }
+              },
+              {
+                "description": "checkboxes is the multi-select drawing; cards and chips serve both.",
+                "if": { "properties": { "control": { "const": "checkboxes" } }, "required": ["control"] },
+                "then": { "required": ["multiple"], "properties": { "multiple": { "const": true } } }
+              },
+              {
+                "description": "A dial and a menu are single-select drawings. Multi-select needs a control that can show more than one mark.",
+                "if": { "properties": { "multiple": { "const": true } }, "required": ["multiple"] },
+                "then": { "properties": { "control": { "enum": ["checkboxes", "chips", "cards"] } } }
+              }
+            ]
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "list" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "enum": ["tags", "repeater"], "default": "tags" },
+              "default": { "type": "array" },
+              "constraints": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "minItems": { "type": "integer", "minimum": 0 },
+                  "maxItems": { "type": "integer", "minimum": 1 }
+                }
+              },
+              "itemType": {
+                "enum": ["text", "email", "number", "toggle", "date", "datetime", "enum", "json"]
+              },
+              "children": false
+            }
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "group" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "enum": ["section", "card"], "default": "section" },
+              "default": { "type": "object" },
+              "constraints": false, "example": false,
+              "options": false, "itemType": false, "source": false,
+              "children": { "type": "array", "minItems": 1 }
+            },
+            "required": ["children"]
+          }
+        },
+        {
+          "if": { "properties": { "type": { "const": "variant" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "enum": ["tabs", "select"], "default": "tabs" },
+              "default": { "type": "object" },
+              "constraints": false, "example": false,
+              "options": false, "itemType": false, "source": false,
+              "children": { "type": "array", "minItems": 2 }
+            },
+            "required": ["children"]
+          }
+        },
+        {
+          "description": "range - one field, not two numbers with a convention between them.",
+          "if": { "properties": { "type": { "const": "range" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "const": "track", "default": "track" },
+              "default": {
+                "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "number" }
+              },
+              "constraints": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "min": { "type": "number" },
+                  "max": { "type": "number" },
+                  "step": { "type": "number", "exclusiveMinimum": 0 }
+                }
+              },
+              "options": false, "itemType": false, "source": false, "children": false
+            }
+          }
+        },
+        {
+          "description": "counters - several numbers under ONE submit. A group of number fields validates the same and draws wrongly.",
+          "if": { "properties": { "type": { "const": "counters" } }, "required": ["type"] },
+          "then": {
+            "required": ["rows"],
+            "properties": {
+              "control": { "const": "rows", "default": "rows" },
+              "default": { "type": "object", "additionalProperties": { "type": "integer" } },
+              "rows": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["key", "label"],
+                  "properties": {
+                    "key": { "$ref": "#/$defs/slug" },
+                    "label": { "type": "string", "minLength": 1 },
+                    "note": { "type": "string" },
+                    "default": { "type": "integer", "minimum": 0 }
+                  }
+                }
+              },
+              "counter": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["text"],
+                "properties": {
+                  "text": { "type": "string", "minLength": 1 },
+                  "empty": { "type": "string", "minLength": 1 }
+                },
+                "description": "{total} interpolates. At zero, `empty` states the consequence rather than showing a 0."
+              },
+              "constraints": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "min": { "type": "integer", "minimum": 0 },
+                  "max": { "type": "integer", "minimum": 1 }
+                }
+              },
+              "options": false, "itemType": false, "source": false, "children": false
+            }
+          }
+        },
+        {
+          "description": "share - ONLY legal when the options really are parts of one whole. The percentages must sum to 100, which JSON Schema cannot check; lintQuestion does.",
+          "if": { "properties": { "type": { "const": "share" } }, "required": ["type"] },
+          "then": {
+            "required": ["options"],
+            "properties": {
+              "control": { "const": "donut", "default": "donut" },
+              "default": { "type": "string" },
+              "constraints": false,
+              "options": {
+                "type": "array",
+                "minItems": 2,
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["value", "label", "pct"],
+                  "properties": {
+                    "value": { "type": "string", "minLength": 1 },
+                    "label": { "type": "string", "minLength": 1 },
+                    "pct": { "type": "number", "minimum": 0, "maximum": 100 },
+                    "note": { "type": "string" }
+                  }
+                }
+              },
+              "itemType": false, "source": false, "children": false
+            }
+          }
+        },
+        {
+          "description": "file - the library renders state only. It takes refs and reports add/remove; the app runs the picker and the upload.",
+          "if": { "properties": { "type": { "const": "file" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "const": "dropzone", "default": "dropzone" },
+              "default": false,
+              "constraints": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "maxItems": { "type": "integer", "minimum": 1 },
+                  "maxBytes": { "type": "integer", "minimum": 1 },
+                  "accept": {
+                    "type": "array",
+                    "minItems": 1,
+                    "items": { "type": "string", "pattern": "^[A-Z0-9]+$" },
+                    "description": "Extensions, uppercase, as the copy shows them."
+                  }
+                }
+              },
+              "options": false, "itemType": false, "source": false, "children": false
+            }
+          }
+        },
+        {
+          "description": "media - an audio FILE, not dictation. This widget produces no transcript.",
+          "if": { "properties": { "type": { "const": "media" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "const": "audio", "default": "audio" },
+              "default": false, "example": false,
+              "constraints": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": { "maxSeconds": { "type": "integer", "minimum": 1 } }
+              },
+              "options": false, "itemType": false, "source": false, "children": false
+            }
+          }
+        },
+        {
+          "description": "action - firing it IS the answer. The value lives in the envelope's outcome, not in answers.",
+          "if": { "properties": { "type": { "const": "action" } }, "required": ["type"] },
+          "then": {
+            "required": ["consequence", "confirm"],
+            "properties": {
+              "control": { "const": "buttons", "default": "buttons" },
+              "default": false, "example": false, "constraints": false,
+              "consequence": {
+                "type": "string",
+                "minLength": 1,
+                "description": "What pressing does, and that nothing has happened yet. A row of verbs with no sentence above it asks the user to guess the blast radius."
+              },
+              "confirm": { "type": "string", "minLength": 1 },
+              "done": { "type": "string", "minLength": 1 },
+              "dismiss": { "type": "string", "minLength": 1 },
+              "options": false, "itemType": false, "source": false, "children": false
+            }
+          }
+        },
+        {
+          "description": "Type-owned keys, refused everywhere else. additionalProperties cannot express this - the properties are legal on the field, just not on every type.",
+          "allOf": [
+            {
+              "if": { "properties": { "type": { "not": { "const": "enum" } } }, "required": ["type"] },
+              "then": { "properties": { "multiple": false } }
+            },
+            {
+              "if": {
+                "properties": { "type": { "not": { "enum": ["enum", "counters"] } } },
+                "required": ["type"]
+              },
+              "then": { "properties": { "submit": false } }
+            },
+            {
+              "if": { "properties": { "type": { "not": { "const": "counters" } } }, "required": ["type"] },
+              "then": { "properties": { "rows": false } }
+            },
+            {
+              "description": "A counter line reconciles with what is visible. It belongs to any widget that shows one, which is more than just `counters`.",
+              "if": {
+                "properties": { "type": { "not": { "enum": ["enum", "counters"] } } },
+                "required": ["type"]
+              },
+              "then": { "properties": { "counter": false } }
+            },
+            {
+              "if": { "properties": { "type": { "not": { "const": "range" } } }, "required": ["type"] },
+              "then": { "properties": { "unit": false } }
+            },
+            {
+              "if": { "properties": { "type": { "not": { "const": "share" } } }, "required": ["type"] },
+              "then": { "properties": { "derived": false } }
+            },
+            {
+              "if": { "properties": { "type": { "not": { "const": "action" } } }, "required": ["type"] },
+              "then": {
+                "properties": {
+                  "consequence": false, "confirm": false, "done": false,
+                  "dismiss": false, "count": false
+                }
+              }
+            }
+          ]
+        },
+        {
+          "if": { "properties": { "type": { "const": "json" } }, "required": ["type"] },
+          "then": {
+            "properties": {
+              "control": { "const": "code", "default": "code" },
+              "constraints": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": { "maxBytes": { "type": "integer", "minimum": 1 } }
+              },
+              "options": false, "itemType": false, "source": false, "children": false
+            }
+          }
+        }
+      ]
+    }
+  }
+}