@golemui/gui-mcp 1.2.0 → 1.2.1-rc.0

package/json.js

@@ -1,4 +1,4 @@
-import { G, J, a, b, c, g, d, e, f, v } from "./get-concept-DRFSt-XX.js";
+import { G, J, a, b, c, g, d, e, f, v } from "./get-concept-CnyfqgLF.js";
 export {
   G as GET_CONCEPT_TOOL,
   J as JSON_GENERATE_FROM_OPENAPI_TOOL,

package/lib.js

@@ -1,5 +1,5 @@
-import { G, J, a, b, c, g, d, e, f, v } from "./get-concept-DRFSt-XX.js";
-import { D, a as a2, b as b2, c as c2, d as d2, e as e2, g as g2, l, f as f2, t } from "./list-dx-factories-BLhvXI07.js";
+import { G, J, a, b, c, g, d, e, f, v } from "./get-concept-CnyfqgLF.js";
+import { D, a as a2, b as b2, c as c2, d as d2, e as e2, g as g2, l, f as f2, t } from "./list-dx-factories-Td5MhXfg.js";
 export {
   D as DX_CHECK_CODE_TOOL,
   a2 as DX_GET_SPEC_TOOL,

package/{list-dx-factories-BLhvXI07.js → list-dx-factories-Td5MhXfg.js}

@@ -1,4 +1,4 @@
-import { h as checkReactiveExpression } from "./get-concept-DRFSt-XX.js";
+import { h as checkReactiveExpression, i as checkBooleanValidatorRules } from "./get-concept-CnyfqgLF.js";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { resolve, join, dirname } from "node:path";
@@ -6,11 +6,13 @@ import { fileURLToPath } from "node:url";
 import { Decoder, err, ok, object, array, string, oneOf, boolean, optional, succeed, number, literal, lazy, discriminatedUnion, record } from "ts.data.json";
 import "subscript/justin";
 import { pipe, map, distinctUntilChanged, filter } from "rxjs";
+const BOOLEAN_FACTORIES = ["checkbox", "booleanInput"];
 const CONFIG_FIELDS = ["include", "exclude", "disabled", "readonly"];
 function lintDxSnippet(ts, sourceText, lineOffset) {
   const sf = ts.createSourceFile("__dx_lint__.ts", sourceText, ts.ScriptTarget.ES2020, true);
   const diagnostics = [];
   const expressionWarnings = [];
+  const validatorWarnings = [];
   const posOf = (node) => {
     const p = sf.getLineAndCharacterOfPosition(node.getStart(sf));
     return { line: p.line + 1 - lineOffset, column: p.character + 1 };
@@ -26,7 +28,29 @@ function lintDxSnippet(ts, sourceText, lineOffset) {
     while (ts.isPropertyAccessExpression(e)) e = e.expression;
     return ts.isIdentifier(e) && e.text === "gui";
   };
-  const visit = (node, inTemplate) => {
+  const guiFactoryName = (node) => {
+    if (!ts.isCallExpression(node) || !isGuiCall(node)) return void 0;
+    return ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text : void 0;
+  };
+  const checkBooleanValidator = (validatorObj) => {
+    const shape = {};
+    for (const p of validatorObj.properties) {
+      if (!ts.isPropertyAssignment(p)) return;
+      const name = nameOf(p.name);
+      if (name === "required") {
+        if (p.initializer.kind === ts.SyntaxKind.TrueKeyword) shape.required = true;
+        else if (p.initializer.kind === ts.SyntaxKind.FalseKeyword) shape.required = false;
+        else return;
+      }
+      if (name === "const") {
+        if (ts.isIdentifier(p.initializer) && p.initializer.text === "undefined") continue;
+        shape.const = true;
+      }
+    }
+    const { line, column } = posOf(validatorObj);
+    validatorWarnings.push(...checkBooleanValidatorRules(shape, `validator@${line}:${column}`));
+  };
+  const visit = (node, inTemplate, inBooleanFactory) => {
     if (ts.isObjectLiteralExpression(node)) {
       const spreadsGui = node.properties.some(
         (p) => ts.isSpreadAssignment(p) && isGuiCall(p.expression)
@@ -56,11 +80,16 @@ function lintDxSnippet(ts, sourceText, lineOffset) {
         expressionWarnings.push(f);
       }
     }
+    if (inBooleanFactory && ts.isPropertyAssignment(node) && (nameOf(node.name) === "validator" || nameOf(node.name)?.startsWith("validator.") === true) && ts.isObjectLiteralExpression(node.initializer)) {
+      checkBooleanValidator(node.initializer);
+    }
     const childInTemplate = inTemplate || ts.isPropertyAssignment(node) && nameOf(node.name) === "template";
-    ts.forEachChild(node, (child) => visit(child, childInTemplate));
+    const factory = guiFactoryName(node);
+    const childInBooleanFactory = factory !== void 0 ? BOOLEAN_FACTORIES.includes(factory) : inBooleanFactory;
+    ts.forEachChild(node, (child) => visit(child, childInTemplate, childInBooleanFactory));
   };
-  visit(sf, false);
-  return { diagnostics, expressionWarnings };
+  visit(sf, false, false);
+  return { diagnostics, expressionWarnings, validatorWarnings };
 }
 let cachedRequire;
 function getRequire() {
@@ -200,9 +229,13 @@ ${body}`;
       hint: hintFor(d, flat)
     };
   });
-  const { diagnostics: lintDiagnostics, expressionWarnings } = lintDxSnippet(ts, full, lineOffset);
+  const {
+    diagnostics: lintDiagnostics,
+    expressionWarnings,
+    validatorWarnings
+  } = lintDxSnippet(ts, full, lineOffset);
   const diagnostics = [...tscDiagnostics, ...lintDiagnostics];
-  return { ok: diagnostics.length === 0, diagnostics, expressionWarnings };
+  return { ok: diagnostics.length === 0, diagnostics, expressionWarnings, validatorWarnings };
 }
 async function checkDxCode(input) {
   if (typeof input?.code !== "string" || input.code.trim() === "") {
@@ -212,7 +245,7 @@ async function checkDxCode(input) {
 }
 const DX_CHECK_CODE_TOOL = {
   name: "dx_check_code",
-  description: "Type-check GolemUI **DX code** (the `gui.*` fluent builder, written in TypeScript) against the real `@golemui` type declarations, and return compiler diagnostics. This is for `gui.*` *code* — distinct from `json_validate_form_definition`, which validates a JSON form-definition *object*. GolemUI is not in any model's training data, so generated `gui.*` code is frequently a confident fabrication that does not compile; this is the only trustworthy check (inspection misses it). Beyond type errors it also catches two defects the compiler cannot see: a misplaced `include`/`exclude` attached as a sibling of a `gui.*` spread (`{ ...gui.inputs.x(...), include }` compiles but silently never hides the field — put `include`/`exclude` INSIDE the config argument), and reactive-expression mistakes in `when` strings (linted by the same engine as `json_validate_form_definition`). Pass the `gui.*` snippet as `code` (a bare array of `gui.inputs.*` items is fine — a `@golemui/gui-shared` import is added if missing). Returns `{ ok, diagnostics, expressionWarnings }`; each diagnostic has a TypeScript `code` (0 for the static lints), `message`, `line`/`column`, and — for recognized GolemUI mistakes — a `hint` with the fix. `expressionWarnings` are advisory and do not flip `ok`. Treat `ok: false` as blocking: apply the fixes and re-check until `ok` is true.",
+  description: "Type-check GolemUI **DX code** (the `gui.*` fluent builder, written in TypeScript) against the real `@golemui` type declarations, and return compiler diagnostics. This is for `gui.*` *code* — distinct from `json_validate_form_definition`, which validates a JSON form-definition *object*. GolemUI is not in any model's training data, so generated `gui.*` code is frequently a confident fabrication that does not compile; this is the only trustworthy check (inspection misses it). Beyond type errors it also catches defects the compiler cannot see: a misplaced `include`/`exclude` attached as a sibling of a `gui.*` spread (`{ ...gui.inputs.x(...), include }` compiles but silently never hides the field — put `include`/`exclude` INSIDE the config argument), reactive-expression mistakes in `when` strings, and the mandatory-checkbox trap (a `checkbox`/`booleanInput` validator with only half of the `required: true` + `const: true` pair — it will not force the box to be checked). Both lints share their rule engines with `json_validate_form_definition`. Pass the `gui.*` snippet as `code` (a bare array of `gui.inputs.*` items is fine — a `@golemui/gui-shared` import is added if missing). Returns `{ ok, diagnostics, expressionWarnings, validatorWarnings }`; each diagnostic has a TypeScript `code` (0 for the static lints), `message`, `line`/`column`, and — for recognized GolemUI mistakes — a `hint` with the fix. `expressionWarnings` and `validatorWarnings` are advisory and do not flip `ok` — surface them and apply their `suggestion`. Treat `ok: false` as blocking: apply the fixes and re-check until `ok` is true.",
   inputSchema: {
     type: "object",
     properties: {
@@ -480,7 +513,7 @@ const FRAMEWORK_SETUP = {
   vanilla: "RENDER (vanilla JS) — `import { gui } from '@golemui/gui-shared'; import '@golemui/gui-lit';` (registers `<gui-form>`), then `const el = document.querySelector('gui-form'); el.config = { formDef: form }; el.addEventListener('" + formEventNames.submit + "', (e) => { /* e.detail.data */ });`. In TypeScript, type the element — `import type { FormElement } from '@golemui/gui-lit'; const el = document.querySelector<FormElement>('gui-form');` — the published types do not register `gui-form` in `HTMLElementTagNameMap`, so an untyped `querySelector` yields `Element` and `el.config` fails to compile."
 };
 function commonNote(fw = "react") {
-  return "GolemUI builds FORMS — data collection and validation. It is NOT a general-purpose UI toolkit: it never renders documents, page content, or markdown for display. A form is just an array of these items: `export const form = [ /* items */ ];`. " + FRAMEWORK_SETUP[fw] + " Import the component stylesheet ONCE — `@golemui/gui-components/index.css` — or the form renders unstyled. To RECEIVE A SUBMIT: add a `gui.actions.button({ label, actionType: 'submit' })` to the form and listen for the submit on the host component (the RENDER line above shows how for your framework) — the handler gets a `FormSubmitEvent` whose `.data` is the collected form data. To DISABLE submit until the form is valid, add `disabled: { when: '$formIsInvalid' }` to that button (`$formIsInvalid` is a built-in validity flag) — see the conditional-and-state-props pattern. The SAME `formDef` renders in every framework (React/Angular/Vue/Lit/vanilla) — only the host wrapper changes. FORM-LEVEL CONFIG — `formDef` is ALWAYS the bare array. Anything form-wide (named `states`, `validateOn`) goes in a sibling `formConfig` on the config (`config={{ formDef: form, formConfig: { states, validateOn } }}`), NEVER inside `formDef`. Do NOT wrap the array as `{ states, form: [...] }` and pass THAT as `formDef` — `formDef` is typed `Record<string, any>` so it COMPILES, but the `gui.*` items are never resolved and the form renders BLANK with no error. See the form-level-states pattern. Common fields like `include`/`exclude` (conditional visibility) go INSIDE a factory’s config argument — never spread them onto the result (`{ ...gui.inputs.x(...), include }` compiles but silently does nothing). See the conditional-visibility pattern. STATIC CONTENT — a section heading or any non-input text/block is the HOST’s job, not GolemUI’s: use `gui.displays.display(() => <h2>…</h2>)` returning your framework’s own node (React JSX, Vue/Angular/Lit node) — it needs no dependency and always renders. MARKDOWN has exactly ONE use: `gui.inputs.markdown`, an INPUT where the user EDITS markdown (its value is their markdown string). There is NO markdown-for-display widget — never use markdown to render a heading or content; use `display` for that. VALIDATOR `type` — one rule, three cases (so you never have to guess): (1) choice widgets (`dropdown`, `radiogroup`, `select`) REQUIRE an explicit `type`: `validator: { type: 'string', required: true }`. (2) `repeater` (array) validators auto-supply `type: 'array'` — supply only the rules, e.g. `validator: { required: true, minItems: 1 }`, never `type`. (3) everything else (text, number, date) takes the loose validator with NO `type`: `validator: { required: true }`. EVENT HANDLERS — `onChange`/`onLoad`/`onFilter`/`onBlur` (inputs/layouts) and `onClick` (actions) are FUNCTIONS, never bare strings: return a string to dispatch a host event by that name (`onChange: () => 'languageChanged'`), or take the event to push live changes (`onChange: (event) => event.update({ path: 'city', options: [...] })`).";
+  return "GolemUI builds FORMS — data collection and validation. It is NOT a general-purpose UI toolkit: it never renders documents, page content, or markdown for display. A form is just an array of these items: `export const form = [ /* items */ ];`. " + FRAMEWORK_SETUP[fw] + " Import the component stylesheet ONCE — `@golemui/gui-components/index.css` — or the form renders unstyled. To RECEIVE A SUBMIT: add a `gui.actions.button({ label, actionType: 'submit' })` to the form and listen for the submit on the host component (the RENDER line above shows how for your framework) — the handler gets a `FormSubmitEvent` whose `.data` is the collected form data. To DISABLE submit until the form is valid, add `disabled: { when: '$formIsInvalid || $form.<requiredField> === undefined' }` to that button. `$formIsInvalid` is a built-in validity flag, but validation NEVER runs at mount, so on the pristine form it is `false` and `$formIsInvalid` ALONE leaves the button ENABLED while required fields are still empty — the extra data check covers that gap. See the conditional-and-state-props pattern. The SAME `formDef` renders in every framework (React/Angular/Vue/Lit/vanilla) — only the host wrapper changes. FORM-LEVEL CONFIG — `formDef` is ALWAYS the bare array. Anything form-wide (named `states`, `validateOn`) goes in a sibling `formConfig` on the config (`config={{ formDef: form, formConfig: { states, validateOn } }}`), NEVER inside `formDef`. Do NOT wrap the array as `{ states, form: [...] }` and pass THAT as `formDef` — `formDef` is typed `Record<string, any>` so it COMPILES, but the `gui.*` items are never resolved and the form renders BLANK with no error. See the form-level-states pattern. Common fields like `include`/`exclude` (conditional visibility) go INSIDE a factory’s config argument — never spread them onto the result (`{ ...gui.inputs.x(...), include }` compiles but silently does nothing). See the conditional-visibility pattern. STATIC CONTENT — a section heading or any non-input text/block is the HOST’s job, not GolemUI’s: use `gui.displays.display(() => <h2>…</h2>)` returning your framework’s own node (React JSX, Vue/Angular/Lit node) — it needs no dependency and always renders. MARKDOWN has exactly ONE use: `gui.inputs.markdown`, an INPUT where the user EDITS markdown (its value is their markdown string). There is NO markdown-for-display widget — never use markdown to render a heading or content; use `display` for that. VALIDATOR `type` — one rule, three cases (so you never have to guess): (1) choice widgets (`dropdown`, `radiogroup`, `select`) REQUIRE an explicit `type`: `validator: { type: 'string', required: true }`. (2) `repeater` (array) validators auto-supply `type: 'array'` — supply only the rules, e.g. `validator: { required: true, minItems: 1 }`, never `type`. (3) everything else (text, number, date) takes the loose validator with NO `type`: `validator: { required: true }`. EVENT HANDLERS — `onChange`/`onLoad`/`onFilter`/`onBlur` (inputs/layouts) and `onClick` (actions) are FUNCTIONS, never bare strings: return a string to dispatch a host event by that name (`onChange: () => 'languageChanged'`), or take the event to push live changes (`onChange: (event) => event.update({ path: 'city', options: [...] })`).";
 }
 const PATTERNS = [
   {
@@ -506,12 +539,24 @@ const PATTERNS = [
   {
     name: "conditionalAndStateProps",
     title: "Conditional & state-driven props (enable/disable, show/hide, readonly)",
-    example: "gui.actions.button({ label: 'Submit', actionType: 'submit', disabled: { when: '$formIsInvalid' } })",
+    example: "gui.actions.button({ label: 'Submit', actionType: 'submit', disabled: { when: '$formIsInvalid || $form.email === undefined' } })",
     notes: [
-      "ENABLE/DISABLE & READONLY: `disabled` and `readonly` are typed `boolean | { when: <expr> }`. To gate the submit button on validity: `gui.actions.button({ label, actionType: 'submit', disabled: { when: '$formIsInvalid' } })`. `$formIsInvalid` is a built-in validity flag — do not declare it as a state.",
+      "ENABLE/DISABLE & READONLY: `disabled` and `readonly` are typed `boolean | { when: <expr> }`. `$formIsInvalid` is a built-in validity flag — do not declare it as a state.",
+      "PRISTINE-FORM TRAP: validation never runs at mount, so `$formIsInvalid` starts `false` and `disabled: { when: '$formIsInvalid' }` leaves the submit button ENABLED while required fields are still empty (it disables only after the first validated interaction). Gate the button with a compound expression that also checks the data — the example above adds `|| $form.email === undefined` for a form whose required field is `email`. The runtime still blocks the actual submit while invalid, so this is a UX concern, not a data-integrity one.",
       "SHOW/HIDE: `include` / `exclude` are typed `{ in: ['stateName'] }` / `{ from: ['stateName'] }` (state lists) or `{ when: <expr> }`. Every state name in `in`/`from` MUST be declared in `formConfig.states`; an undeclared name leaves the widget hidden forever (the engine logs an error to the console).",
       "These are ALL typed config keys — pass them inside the factory’s config argument. NEVER reach a prop by casting the factory result and assigning a key (`(btn as any)['disabled.formValid'] = false`) or by spreading (`{ ...gui.actions.button(...), disabled }`): keys added that way are SILENTLY ignored and the behavior never fires. If a prop is not on the typed config, you are guessing — it is not a real field."
     ]
+  },
+  {
+    name: "validationMessages",
+    title: "Validation rules & custom error messages (required, const, messages)",
+    example: "gui.inputs.textInput('email', { label: 'Email', validator: { required: true, format: 'email', messages: { invalid: 'Email is required', required: 'Email is required', format: 'Enter a valid email address' } } })",
+    notes: [
+      'Every validator accepts a `messages` map from rule name to custom error text (string or i18n `{ key, params?, default? }`). Keys per type — string: `invalid`, `required`, `minLength`, `maxLength`, `pattern`, `format`, `enum`, `const`; number: `invalid`, `minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`, `enum`, `const`; boolean: `invalid`, `const`; array: `invalid`, `required`, `minItems`, `maxItems`. The special key `invalid` customizes the base type check. Set custom messages for every rule you use — the library defaults (e.g. "Invalid input: expected string, received undefined") are developer-facing, not user-facing.',
+      'ALWAYS pair `messages.required` with `messages.invalid` (same text): an `undefined`/`null` value — the pristine or cleared field, the most common empty state — fails the base TYPE check and shows the `invalid` message; the `required` rule only fires on present-but-empty values (`""`, `[]`). That is also why number/boolean validators have NO `required` message key — for them `messages.invalid` is the only way to word the missing-value error. `null` is never valid, even on non-required fields.',
+      "MANDATORY CHECKBOX: boolean `required: true` does NOT force it checked (`false` is a valid boolean) and `const: true` alone lets the pristine `undefined` pass. Use both plus paired messages — see the `gui.inputs.checkbox` entry for the full recipe.",
+      'WHEN VALIDATION RUNS: only on user interaction, per `formConfig.validateOn` — `"eager"` (default: first change or blur anywhere validates the whole form), `"change"`, `"blur"`, `"submit"`, or an array. NOTHING validates at mount, which is why `$formIsInvalid` starts `false` — see the conditional-and-state-props pattern for gating the submit button correctly. Submit clicks always re-validate everything and the runtime blocks the submit event while invalid.'
+    ]
   }
 ];
 const INPUTS = [
@@ -548,9 +593,13 @@ const INPUTS = [
     factory: "checkbox",
     namespace: "inputs",
     docSlug: "checkbox",
-    call: "gui.inputs.checkbox(path, { label, defaultValue? })",
-    example: "gui.inputs.checkbox('terms', { label: 'I accept the terms', defaultValue: false })",
-    notes: ["A single boolean rendered as a checkbox."]
+    call: "gui.inputs.checkbox(path, { label, defaultValue?, validator? })",
+    example: "gui.inputs.checkbox('terms', { label: 'I accept the terms', validator: { required: true, const: true, messages: { invalid: 'You must accept the terms', const: 'You must accept the terms' } } })",
+    notes: [
+      "A single boolean rendered as a checkbox.",
+      "MANDATORY CHECKBOX (terms acceptance): `required: true` alone is a silent trap — an unchecked box holding `false` is a valid boolean and PASSES; only `const: true` rejects `false`. And `const: true` alone lets the pristine `undefined` pass (non-required validators are optional). Use BOTH, as in the example.",
+      "Set BOTH `messages.invalid` and `messages.const` to the same text: a never-touched box fails the type check (`invalid` message), a checked-then-unchecked box fails the `const` rule (`const` message). See the validation-messages pattern."
+    ]
   },
   {
     factory: "textarea",
@@ -598,7 +647,8 @@ const INPUTS = [
     example: "gui.inputs.datePicker('startDate', { label: 'Coverage start', minDate: '2025-01-01', validator: { required: true } })",
     notes: [
       "THE DEFAULT single-date field: a text field with a popover calendar (click to open). Prefer this for most dates. (`calendar` = always-visible inline calendar; `dateInput` = typed entry, no calendar UI.) Accepts the loose `{ required: true }` validator.",
-      'Bound the selectable range with **`minDate`** / **`maxDate`** — ISO `YYYY-MM-DD` strings. For "today or later" set `minDate` to today’s date; for "not in the future" set `maxDate` to today. Same `minDate`/`maxDate` on `calendar`, `dateInput`, and the range date widgets.'
+      'Bound the selectable range with **`minDate`** / **`maxDate`** — ISO `YYYY-MM-DD` strings. For "today or later" set `minDate` to today’s date; for "not in the future" set `maxDate` to today. Same `minDate`/`maxDate` on `calendar`, `dateInput`, and the range date widgets.',
+      'A partially typed date abandoned on focus leave flips the value to null — flagging the field even when optional — and surfaces an "incomplete" error; **`incompleteMessage`** overrides its wording. The same prop exists on every typed date/time widget (the inputs, the pickers, the range inputs/pickers, and the inline `dateTimeCalendar`/`rangeDateTimeCalendar`), and an emptied widget clears the error on the next focus leave.'
     ]
   },
   {
@@ -625,10 +675,11 @@ const INPUTS = [
     namespace: "inputs",
     docSlug: "dateinput",
     call: "gui.inputs.dateInput(path, { label, minDate?, maxDate?, validator? })",
-    example: "gui.inputs.dateInput('startDate', { label: 'Start date', validator: { required: true } })",
+    example: "gui.inputs.dateInput('startDate', { label: 'Start date', incompleteMessage: 'Incomplete date!', validator: { required: true } })",
     notes: [
       "Typed date entry, NO calendar UI — use only when keyboard-first entry is wanted. For most dates use `datePicker` (popover calendar) instead. Accepts the loose `{ required: true }`.",
-      "`minDate` / `maxDate` (ISO `YYYY-MM-DD` strings) constrain the accepted range — see `datePicker`."
+      "`minDate` / `maxDate` (ISO `YYYY-MM-DD` strings) constrain the accepted range — see `datePicker`.",
+      '`incompleteMessage` overrides the "incomplete" error surfaced when focus leaves a partial entry — see `datePicker`.'
     ]
   },
   {
@@ -638,7 +689,8 @@ const INPUTS = [
     call: "gui.inputs.timeInput(path, { label, hourFormat?, minuteStep?, validator? })",
     example: "gui.inputs.timeInput('meetingTime', { label: 'Meeting time', minuteStep: 15 })",
     notes: [
-      "Typed time entry (hh:mm segments). Emits an ISO time string (`HH:mm:ss`) — pair with the `{ format: 'time' }` validator. `hourFormat` forces '12'/'24' (default: locale); `minuteStep` sets the arrow-key minute increment."
+      "Typed time entry (hh:mm segments). Emits an ISO time string (`HH:mm:ss`) — pair with the `{ format: 'time' }` validator. `hourFormat` forces '12'/'24' (default: locale); `minuteStep` sets the arrow-key minute increment.",
+      '`incompleteMessage` overrides the "incomplete" error surfaced when focus leaves a partial entry — see `datePicker`.'
     ]
   },
   {
@@ -648,7 +700,8 @@ const INPUTS = [
     call: "gui.inputs.timePicker(path, { label, minTime?, maxTime?, minuteStep?, disabledRanges?, allowCustomTime?, validator? })",
     example: "gui.inputs.timePicker('meetingTime', { label: 'Meeting time', minTime: '09:00', maxTime: '18:00', minuteStep: 30 })",
     notes: [
-      "Time field with a popover list of slots built from `minTime`..`maxTime` stepping `minuteStep` (default 30). `disabledRanges` (`{ start, end }[]`, inclusive) greys slots out. Typing is off unless `allowCustomTime: true`. Emits `HH:mm:ss` — pair with the `{ format: 'time' }` validator."
+      "Time field with a popover list of slots built from `minTime`..`maxTime` stepping `minuteStep` (default 30). `disabledRanges` (`{ start, end }[]`, inclusive) greys slots out. Typing is off unless `allowCustomTime: true`. Emits `HH:mm:ss` — pair with the `{ format: 'time' }` validator.",
+      '`incompleteMessage` overrides the "incomplete" error surfaced when focus leaves a partial typed entry — see `datePicker`.'
     ]
   },
   {
@@ -658,7 +711,8 @@ const INPUTS = [
     call: "gui.inputs.dateTimeInput(path, { label, hourFormat?, minuteStep?, validator? })",
     example: "gui.inputs.dateTimeInput('meetingAt', { label: 'Meeting at' })",
     notes: [
-      "Typed date+time entry in one locale-ordered row. Emits a local ISO date-time (`YYYY-MM-DDTHH:mm:ss`) — pair with the `{ format: 'date-time' }` validator. `hourFormat`/`minuteStep` as in `timeInput`."
+      "Typed date+time entry in one locale-ordered row. Emits a local ISO date-time (`YYYY-MM-DDTHH:mm:ss`) — pair with the `{ format: 'date-time' }` validator. `hourFormat`/`minuteStep` as in `timeInput`.",
+      '`incompleteMessage` overrides the "incomplete" error surfaced when focus leaves a partial entry — see `datePicker`.'
     ]
   },
   {
@@ -680,7 +734,8 @@ const INPUTS = [
     example: "gui.inputs.dateTimeCalendar('appointmentAt', { label: 'Appointment', minTime: '09:00', maxTime: '18:00' })",
     notes: [
       "An INLINE calendar with an embedded time picker: a segmented time input between the header and the days grid opens a time grid in place of the days (like the year selector).",
-      "Emits a local ISO date-time (`YYYY-MM-DDTHH:mm:ss`) only when BOTH day and time are selected — pair with a `{ type: 'string', format: 'date-time' }` validator. Picking a different day clears the time and resets the value to null.",
+      "Emits a local ISO date-time (`YYYY-MM-DDTHH:mm:ss`) only when BOTH day and time are selected — pair with a `{ type: 'string', format: 'date-time' }` validator. The time picker is usable before a day is picked, and picking a different day KEEPS the chosen time (re-emitting the full value), so the two halves can be chosen in either order.",
+      'Half-finished entries never emit: the value goes to null — flagging the field even when it is optional — only once focus leaves the widget with one half missing, which surfaces an "incomplete" message (`incompleteMessage` overrides its wording).',
       "`disabledTimeRanges` entries take `start`/`end` ISO times plus optional `date` (ISO date) and/or `weekdays` (getDay() numbering: 0=Sunday … 6=Saturday) to scope the range to specific days."
     ]
   },
@@ -693,7 +748,7 @@ const INPUTS = [
     notes: [
       "A compact date-time FIELD that opens a `dateTimeCalendar` POPOVER on focus — the space-saving counterpart to the inline `dateTimeCalendar`, like `datePicker` is to `calendar`.",
       "Emits a local ISO date-time (`YYYY-MM-DDTHH:mm:ss`); the popover closes only when BOTH day and time are selected. Pair with a `{ type: 'string', format: 'date-time' }` validator.",
-      "Takes the same time props as `dateTimeCalendar` (`minTime`/`maxTime`/`minuteStep`/`disabledTimeRanges` with per-date/weekday scoping/`allowCustomTime`) plus `icon` and `invalidDateMessage` for the typed input."
+      "Takes the same time props as `dateTimeCalendar` (`minTime`/`maxTime`/`minuteStep`/`disabledTimeRanges` with per-date/weekday scoping/`allowCustomTime`) plus `icon`, `invalidDateMessage` and `incompleteMessage` for the typed input."
     ]
   },
   {
@@ -753,7 +808,10 @@ const INPUTS = [
     docSlug: "range-date-input",
     call: "gui.inputs.rangeDateInput(path, { label? })",
     example: "gui.inputs.rangeDateInput('stayDates', { label: 'Stay dates' })",
-    notes: ["Typed start–end date **range** entry (the range sibling of `dateInput`)."]
+    notes: [
+      "Typed start–end date **range** entry (the range sibling of `dateInput`).",
+      '`incompleteMessage` overrides the "incomplete" error surfaced when focus leaves with only one endpoint filled — see `datePicker`.'
+    ]
   },
   {
     factory: "rangeTimeInput",
@@ -762,7 +820,8 @@ const INPUTS = [
     call: "gui.inputs.rangeTimeInput(path, { label?, minTime?, maxTime? })",
     example: "gui.inputs.rangeTimeInput('shift', { label: 'Shift', minTime: '06:00:00', maxTime: '22:00:00' })",
     notes: [
-      "Typed start–end time **range** entry (the range sibling of `timeInput`); value is `TimeRange[]`. End time must be after start time."
+      "Typed start–end time **range** entry (the range sibling of `timeInput`); value is `TimeRange[]`. End time must be after start time.",
+      '`incompleteMessage` overrides the "incomplete" error surfaced when focus leaves with only one endpoint filled — see `datePicker`.'
     ]
   },
   {
@@ -773,7 +832,8 @@ const INPUTS = [
     example: "gui.inputs.rangeDateTimeInput('window', { label: 'Window', minDateTime: '2026-03-01T06:00:00', maxDateTime: '2026-03-31T22:00:00' })",
     notes: [
       "Typed start–end date-time **range** entry (the range sibling of `dateTimeInput`); value is `DateTimeRange[]`. A backward selection reorders (swaps) instead of erroring.",
-      "Each endpoint is an instant, so it is bounded by instants: use **`minDateTime`** / **`maxDateTime`** (ISO `YYYY-MM-DDTHH:mm:ss`), not `minDate`/`maxDate`. There is no `minTime`/`maxTime` here — a per-day time window is a different constraint from an instant bound."
+      "Each endpoint is an instant, so it is bounded by instants: use **`minDateTime`** / **`maxDateTime`** (ISO `YYYY-MM-DDTHH:mm:ss`), not `minDate`/`maxDate`. There is no `minTime`/`maxTime` here — a per-day time window is a different constraint from an instant bound.",
+      '`incompleteMessage` overrides the "incomplete" error surfaced when focus leaves with only one endpoint filled — see `datePicker`.'
     ]
   },
   {
@@ -783,7 +843,7 @@ const INPUTS = [
     call: "gui.inputs.rangeDateTimeCalendar(path, { label?, minDateTime?, maxDateTime?, disabledRanges?, startTimeLabel?, endTimeLabel? })",
     example: "gui.inputs.rangeDateTimeCalendar('stay', { label: 'Stay', startTimeLabel: 'Check-in', endTimeLabel: 'Check-out' })",
     notes: [
-      "INLINE range calendar with TWO embedded time pickers (start/end); value is `DateTimeRange[]`, rendered as pills. Pick a date range, then a start time (enables the end time), then an end time to commit a pill. A day holding more than one range shows a count badge.",
+      'INLINE range calendar with TWO embedded time pickers (start/end); value is `DateTimeRange[]`, rendered as pills. A day span and the two times can be chosen in ANY order — both time pickers are usable from the start — and the pill is committed once all four pieces are present. Starting a new day span keeps the times already chosen. A day holding more than one range shows a count badge. Leaving the widget with a half-finished selection surfaces an "incomplete" error over the untouched pills (`incompleteMessage` overrides its wording); leaving it emptied clears the error.',
       "Everything is in instant-space: bounds are **`minDateTime`** / **`maxDateTime`** and **`disabledRanges`** are `DateTimeRange[]` instant spans (block a whole day with `00:00:00`–`23:59:59`). There is no `minDate`/`maxDate`/`minTime`/`maxTime`/`disabledTimeRanges` — a time-of-day constraint cannot bound a multi-day span."
     ]
   },
@@ -794,7 +854,7 @@ const INPUTS = [
     call: "gui.inputs.rangeDateTimePicker(path, { label?, minDateTime?, maxDateTime?, disabledRanges?, startTimeLabel?, endTimeLabel? })",
     example: "gui.inputs.rangeDateTimePicker('stay', { label: 'Stay', startTimeLabel: 'Check-in', endTimeLabel: 'Check-out' })",
     notes: [
-      "POPOVER date-time range picker: the typed `rangeDateTimeInput` as the trigger (pills live there) with the `rangeDateTimeCalendar` in a dropdown. Value is `DateTimeRange[]`. Committing a pill keeps the popover open so several ranges can be added; it closes on outside-click, blur or Escape.",
+      'POPOVER date-time range picker: the typed `rangeDateTimeInput` as the trigger (pills live there) with the `rangeDateTimeCalendar` in a dropdown. Value is `DateTimeRange[]`. Committing a pill keeps the popover open so several ranges can be added; it closes on outside-click, blur or Escape. A half-finished selection is held by the picker, so it survives closing and reopening the popover. Leaving it that way surfaces an "incomplete" error (`incompleteMessage` overrides its wording).',
       "Everything is in instant-space: bounds are **`minDateTime`** / **`maxDateTime`** and **`disabledRanges`** are `DateTimeRange[]` instant spans (block a whole day with `00:00:00`–`23:59:59`). There is no `minDate`/`maxDate`/`minTime`/`maxTime`/`disabledTimeRanges`."
     ]
   },
@@ -804,7 +864,9 @@ const INPUTS = [
     docSlug: "range-date-picker",
     call: "gui.inputs.rangeDatePicker(path, { label? })",
     example: "gui.inputs.rangeDatePicker('stayDates', { label: 'Stay dates' })",
-    notes: ["Popover calendar for a start–end date **range** (the range sibling of `datePicker`)."]
+    notes: [
+      'Popover calendar for a start–end date **range** (the range sibling of `datePicker`). A span with only its first day picked is held by the picker, so it survives closing and reopening the popover. Leaving it that way surfaces an "incomplete" error (`incompleteMessage` overrides its wording).'
+    ]
   },
   {
     factory: "rangeTimePicker",
@@ -813,7 +875,8 @@ const INPUTS = [
     call: "gui.inputs.rangeTimePicker(path, { label?, minTime?, maxTime? })",
     example: "gui.inputs.rangeTimePicker('shift', { label: 'Shift', minTime: '06:00:00', maxTime: '22:00:00' })",
     notes: [
-      "Two-list popover for a start–end time **range** (the range sibling of `timePicker`); value is `TimeRange[]`. The out list floors one slot after the chosen in so end is strictly after start."
+      "Two-list popover for a start–end time **range** (the range sibling of `timePicker`); value is `TimeRange[]`. Either list can be used first — an end picked before a start simply waits — and the range commits once both are set. Once an in is chosen the out list floors one slot after it so end is strictly after start.",
+      '`incompleteMessage` overrides the "incomplete" error surfaced when focus leaves with only one endpoint set — see `datePicker`.'
     ]
   }
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@golemui/gui-mcp",
-  "version": "1.2.0",
+  "version": "1.2.1-rc.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -43,10 +43,10 @@
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "typescript": "^5.9.2",
-    "@golemui/gui-schemas": "1.2.0",
-    "@golemui/gui-shared": "1.2.0",
-    "@golemui/gui-validators": "1.2.0",
-    "@golemui/core": "1.2.0",
+    "@golemui/gui-schemas": "1.2.1-rc.0",
+    "@golemui/gui-shared": "1.2.1-rc.0",
+    "@golemui/gui-validators": "1.2.1-rc.0",
+    "@golemui/core": "1.2.1-rc.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^4.0.0",
     "@standard-schema/spec": "^1.0.0"

package/shared/get-concept.d.ts

@@ -21,7 +21,7 @@ export declare const GET_CONCEPT_TOOL: {
         readonly properties: {
             readonly concept: {
                 readonly type: "string";
-                readonly description: "The concept to explain. Currently supported: `\"states\"`, `\"string-interpolation\"`.";
+                readonly description: string;
                 readonly enum: string[];
             };
         };

package/shared/lint/boolean-validator.d.ts

@@ -0,0 +1,32 @@
+export type BooleanValidatorFinding = {
+    path: string;
+    message: string;
+    suggestion: string;
+};
+/**
+ * Semantic lint for boolean validators — the mandatory-checkbox trap.
+ *
+ * The runtime facts (see `@golemui/gui-validators`): a boolean validator has no
+ * `required` refine, so `required: true` only rejects a MISSING value
+ * (`undefined`/`null`) — an unchecked box holding `false` passes. And a validator
+ * without `required: true` is wrapped in `optional()`, so `const: true` alone lets
+ * the pristine `undefined` pass. Forcing a checkbox to be checked therefore needs
+ * BOTH rules — either half alone validates something the author almost never means.
+ *
+ * Like `reactive-expressions.ts`, this is the shared engine for both surfaces:
+ * {@link lintBooleanValidators} walks a JSON form definition, while the DX path
+ * (`dx-lint.ts`) extracts each boolean-widget validator from the AST and funnels it
+ * through {@link checkBooleanValidatorRules} — one rule set, no drift.
+ */
+export declare function checkBooleanValidatorRules(validator: {
+    required?: unknown;
+    const?: unknown;
+}, path: string): BooleanValidatorFinding[];
+/**
+ * Walks a JSON form definition and applies {@link checkBooleanValidatorRules} to every
+ * boolean validator — the `validator` key and its state-suffixed variants
+ * (`"validator.<stateName>"`) on any widget, at any nesting depth (layout `children`,
+ * repeater `props.template`). Only validators declaring `"type": "boolean"` are
+ * checked; shape errors on other types are the JSON Schemas' job.
+ */
+export declare function lintBooleanValidators(formDefinition: unknown): BooleanValidatorFinding[];