@golemui/gui-mcp 1.0.3 → 1.1.1-rc.0

package/{list-dx-factories-C-Z5Sc5E.js → list-dx-factories-Dwy_BYZi.js}

@@ -1,8 +1,11 @@
-import { h as checkReactiveExpression } from "./get-concept-Py3iLVmb.js";
+import { h as checkReactiveExpression } from "./get-concept-DRFSt-XX.js";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { resolve, join, dirname } from "node:path";
 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 CONFIG_FIELDS = ["include", "exclude", "disabled", "readonly"];
 function lintDxSnippet(ts, sourceText, lineOffset) {
   const sf = ts.createSourceFile("__dx_lint__.ts", sourceText, ts.ScriptTarget.ES2020, true);
@@ -23,7 +26,7 @@ function lintDxSnippet(ts, sourceText, lineOffset) {
     while (ts.isPropertyAccessExpression(e)) e = e.expression;
     return ts.isIdentifier(e) && e.text === "gui";
   };
-  const visit = (node) => {
+  const visit = (node, inTemplate) => {
     if (ts.isObjectLiteralExpression(node)) {
       const spreadsGui = node.properties.some(
         (p) => ts.isSpreadAssignment(p) && isGuiCall(p.expression)
@@ -46,13 +49,17 @@ function lintDxSnippet(ts, sourceText, lineOffset) {
     }
     if (ts.isPropertyAssignment(node) && nameOf(node.name) === "when" && ts.isStringLiteralLike(node.initializer)) {
       const { line, column } = posOf(node.initializer);
-      for (const f of checkReactiveExpression(node.initializer.text, `when@${line}:${column}`)) {
+      const findings = checkReactiveExpression(node.initializer.text, `when@${line}:${column}`, {
+        inRepeaterTemplate: inTemplate
+      });
+      for (const f of findings) {
         expressionWarnings.push(f);
       }
     }
-    ts.forEachChild(node, visit);
+    const childInTemplate = inTemplate || ts.isPropertyAssignment(node) && nameOf(node.name) === "template";
+    ts.forEachChild(node, (child) => visit(child, childInTemplate));
   };
-  visit(sf);
+  visit(sf, false);
   return { diagnostics, expressionWarnings };
 }
 let cachedRequire;
@@ -63,8 +70,7 @@ const GOLEMUI_TYPE_PACKAGES = [
   { spec: "@golemui/gui-shared", rel: "gui/shared/index.d.ts" },
   { spec: "@golemui/gui-shared/internals", rel: "gui/shared/internals.d.ts" },
   { spec: "@golemui/gui-validators", rel: "gui/validators/index.d.ts" },
-  { spec: "@golemui/core", rel: "core/index.d.ts" },
-  { spec: "@golemui/core/internals", rel: "core/internals.d.ts" }
+  { spec: "@golemui/core", rel: "core/index.d.ts" }
 ];
 const DIST_SEARCH_DEPTH = 8;
 const SNIPPET_FILE = "__dx_snippet__.ts";
@@ -213,6 +219,249 @@ const DX_CHECK_CODE_TOOL = {
     required: ["code"]
   }
 };
+function objectWithSuffix(specs) {
+  return new Decoder((json) => {
+    if (typeof json !== "object" || json === null) {
+      return err([{ message: `Expected object literal, got "${typeof json}"`, path: [] }]);
+    }
+    const out = {};
+    for (const [specKey, spec] of Object.entries(specs)) {
+      const res = spec.decoder.decode(json[specKey]);
+      if (!res.isOk()) {
+        return err(
+          res.issues.map((issue) => ({
+            message: issue.message,
+            path: [specKey, ...issue.path]
+          }))
+        );
+      }
+      out[specKey] = res.value;
+      if (spec.suffixed) {
+        for (const [jsonKey, jsonValue] of Object.entries(json)) {
+          if (jsonKey.startsWith(specKey + ".")) {
+            const res2 = spec.decoder.decode(jsonValue);
+            if (!res2.isOk()) {
+              return err(
+                res2.issues.map((issue) => ({
+                  message: issue.message,
+                  path: [jsonKey, ...issue.path]
+                }))
+              );
+            }
+            out[jsonKey] = res2.value;
+          }
+        }
+      }
+    }
+    return ok(out);
+  });
+}
+const shortUUID = () => crypto.randomUUID().slice(0, 8);
+const isInputWidget = (widget) => typeof widget !== "function" && widget.kind === "input";
+const isLayoutWidget = (widget) => typeof widget !== "function" && widget.kind === "layout";
+const isFunctionWidget = (widget) => typeof widget === "function";
+const inDecoder = object({ in: array(string()) });
+const whenDecoder = object({ when: string() });
+const includeDecoder = oneOf([inDecoder, whenDecoder]);
+const fromDecoder = object({ from: array(string()) });
+const excludeDecoder = oneOf([fromDecoder, whenDecoder]);
+const boolWhenDecoder = oneOf([boolean(), whenDecoder]);
+const widgetPropFnDecoder = new Decoder((json) => {
+  const jsonTypeof = typeof json;
+  if (jsonTypeof === "function") {
+    return ok(json);
+  } else {
+    return err([{ message: `Expected a function, got '${jsonTypeof}'`, path: [] }]);
+  }
+});
+const decodeWidgetPropOrWidgetPropFn = (decoder) => oneOf([decoder, widgetPropFnDecoder]);
+const onDecoder = objectWithSuffix({
+  load: { suffixed: true, decoder: decodeWidgetPropOrWidgetPropFn(optional(string())) },
+  click: { suffixed: true, decoder: decodeWidgetPropOrWidgetPropFn(optional(string())) },
+  change: { suffixed: true, decoder: decodeWidgetPropOrWidgetPropFn(optional(string())) },
+  filter: { suffixed: true, decoder: decodeWidgetPropOrWidgetPropFn(optional(string())) },
+  blur: { suffixed: true, decoder: decodeWidgetPropOrWidgetPropFn(optional(string())) }
+});
+const translationConfigDecoder = object({
+  key: string(),
+  default: optional(string()),
+  params: optional(succeed())
+});
+const localizableDecoder = oneOf([string(), translationConfigDecoder]);
+const uidDecoder = optional(string());
+const displayWidgetDecoder = objectWithSuffix({
+  kind: { decoder: literal("display") },
+  uid: { decoder: uidDecoder },
+  type: { decoder: string() },
+  size: { suffixed: true, decoder: optional(number()) },
+  include: { decoder: optional(includeDecoder) },
+  exclude: { decoder: optional(excludeDecoder) },
+  props: { decoder: optional(succeed()) }
+});
+const actionWidgetDecoder = objectWithSuffix({
+  kind: { decoder: literal("action") },
+  uid: { decoder: uidDecoder },
+  type: { decoder: string() },
+  actionType: {
+    decoder: optional(oneOf([literal("button"), literal("submit")]))
+  },
+  size: { suffixed: true, decoder: optional(number()) },
+  include: { decoder: optional(includeDecoder) },
+  exclude: { decoder: optional(excludeDecoder) },
+  label: {
+    suffixed: true,
+    decoder: decodeWidgetPropOrWidgetPropFn(optional(localizableDecoder))
+  },
+  disabled: { suffixed: true, decoder: optional(boolWhenDecoder) },
+  on: { decoder: optional(onDecoder) },
+  props: { decoder: optional(succeed()) }
+});
+const functionWidgetDecoder = new Decoder((json) => {
+  const jsonTypeof = typeof json;
+  if (jsonTypeof === "function") {
+    const fnWidget = json;
+    const widget = fnWidget({
+      $form: {},
+      errors: void 0,
+      touched: void 0,
+      translate: void 0
+    });
+    fnWidget.uid = fnWidget.uid || widget.uid || shortUUID();
+    fnWidget.type = widget.type;
+    fnWidget.path = widget.path;
+    return ok(fnWidget);
+  } else {
+    return err([{ message: `Expected a function, got '${jsonTypeof}'`, path: [] }]);
+  }
+});
+const inputWidgetDecoder = objectWithSuffix({
+  kind: { decoder: literal("input") },
+  uid: { decoder: optional(string()) },
+  type: { decoder: string() },
+  size: { suffixed: true, decoder: optional(number()) },
+  include: { decoder: optional(includeDecoder) },
+  exclude: { decoder: optional(excludeDecoder) },
+  disabled: { suffixed: true, decoder: optional(boolWhenDecoder) },
+  readonly: { suffixed: true, decoder: optional(boolWhenDecoder) },
+  on: { decoder: optional(onDecoder) },
+  props: { decoder: optional(succeed()) },
+  label: {
+    suffixed: true,
+    decoder: decodeWidgetPropOrWidgetPropFn(optional(localizableDecoder))
+  },
+  path: { decoder: string() },
+  defaultValue: { decoder: optional(succeed()) },
+  validator: {
+    suffixed: true,
+    decoder: decodeWidgetPropOrWidgetPropFn(optional(succeed()))
+  }
+}).map((ctrl) => {
+  const transformed = { ...ctrl };
+  if (!ctrl.uid) {
+    transformed.uid = `${ctrl.path}-${ctrl.type}`;
+  }
+  if (ctrl.type === "repeater") {
+    const props = ctrl["props"];
+    transformed.props = { ...props, template: layoutWidgetDecoder.parse(props["template"]) };
+  }
+  return transformed;
+});
+const formWidgetDecoder = lazy(() => {
+  const objectWidgetDecoder = discriminatedUnion("kind", {
+    input: inputWidgetDecoder,
+    layout: layoutWidgetDecoder,
+    display: displayWidgetDecoder,
+    action: actionWidgetDecoder
+  });
+  return new Decoder(
+    (json) => typeof json === "function" ? functionWidgetDecoder.decode(json) : objectWidgetDecoder.decode(json)
+  );
+});
+const layoutWidgetDecoder = objectWithSuffix({
+  kind: { decoder: literal("layout") },
+  uid: { decoder: uidDecoder },
+  type: { decoder: string() },
+  size: { suffixed: true, decoder: optional(number()) },
+  include: { decoder: optional(includeDecoder) },
+  exclude: { decoder: optional(excludeDecoder) },
+  props: { decoder: optional(succeed()) },
+  on: { decoder: optional(onDecoder) },
+  children: { decoder: array(formWidgetDecoder) }
+});
+function assignDeterministicUids(root) {
+  assignUidByPosition(root, "#0");
+}
+function assignUidByPosition(widget, positionUid) {
+  if (isFunctionWidget(widget)) {
+    return;
+  }
+  if (!widget.uid) {
+    widget.uid = positionUid;
+  }
+  if (isLayoutWidget(widget)) {
+    widget.children.forEach((child, index) => {
+      assignUidByPosition(child, `${positionUid}.${index}`);
+    });
+  }
+  if (isInputWidget(widget) && widget.type === "repeater") {
+    const template = widget.props?.["template"];
+    if (template) {
+      assignUidByPosition(template, `${positionUid}.t`);
+    }
+  }
+}
+object({
+  states: optional(record(string())),
+  form: lazy(() => layoutWidgetDecoder)
+}).map((formDef) => {
+  assignDeterministicUids(formDef.form);
+  return formDef;
+});
+const formEventNames = {
+  submit: "formSubmit"
+};
+pipe(
+  map((store) => store.data),
+  distinctUntilChanged()
+);
+pipe(
+  filter((store) => store.touched === true),
+  map((store) => store.validations),
+  distinctUntilChanged()
+);
+pipe(
+  filter((store) => store.touched === true),
+  map((store) => store.injectedValidations),
+  distinctUntilChanged()
+);
+pipe(
+  map((store) => store.lang),
+  distinctUntilChanged()
+);
+pipe(
+  map((store) => store.calculatedWidgets),
+  distinctUntilChanged()
+);
+pipe(
+  map((store) => store.widgetFlags),
+  distinctUntilChanged()
+);
+pipe(
+  map((store) => store.touchedControls),
+  distinctUntilChanged()
+);
+pipe(
+  map((store) => store.formHealth),
+  distinctUntilChanged((prev, current) => {
+    if (prev.status !== current.status) {
+      return false;
+    }
+    if (prev.status === "errored" && current.status === "errored") {
+      return prev.message === current.message && prev.code === current.code;
+    }
+    return true;
+  })
+);
 const DX_FRAMEWORKS = ["react", "angular", "vue", "lit", "vanilla"];
 function resolveDxFramework() {
   const raw = typeof process !== "undefined" ? process.env?.["GOLEMUI_FRAMEWORK"]?.toLowerCase() : void 0;
@@ -222,8 +471,8 @@ const FRAMEWORK_SETUP = {
   react: "RENDER (React) — `import { gui } from '@golemui/gui-shared'; import { GuiForm } from '@golemui/gui-react'; import type { FormSubmitEvent } from '@golemui/core';`, then render `<GuiForm config={{ formDef: form }} formSubmit={(e: FormSubmitEvent) => { /* e.data is the form data */ }} />`. A `gui.displays.display(() => <h2>…</h2>)` returns React JSX.",
   angular: "RENDER (Angular) — `import { gui } from '@golemui/gui-shared'; import { FormComponent } from '@golemui/gui-angular';`, add `FormComponent` to the standalone component's `imports`, then in the template `<gui-form [config]=\"{ formDef: form }\" (formSubmit)=\"onSubmit($event)\"></gui-form>` — `$event` is a `FormSubmitEvent` (type from `@golemui/core`), `$event.data` is the form data.",
   vue: "RENDER (Vue) — `import { gui } from '@golemui/gui-shared'; import { GuiForm } from '@golemui/gui-vue';`, then `<GuiForm :config=\"{ formDef: form }\" @form-submit=\"onSubmit\" />` — the handler receives a `FormSubmitEvent` (`.data` is the form data). The event is `form-submit` (kebab-case), not `formSubmit`.",
-  lit: "RENDER (Lit) — `import { gui } from '@golemui/gui-shared'; import '@golemui/gui-lit';` (registers the `<gui-form>` custom element), then `<gui-form .config=${{ formDef: form }} @form-submit=${(e: CustomEvent) => { /* e.detail is the FormSubmitEvent; e.detail.data */ }}></gui-form>`.",
-  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('form-submit', (e) => { /* e.detail.data */ });`"
+  lit: "RENDER (Lit) — `import { gui } from '@golemui/gui-shared'; import '@golemui/gui-lit';` (registers the `<gui-form>` custom element), then `<gui-form .config=${{ formDef: form }} @" + formEventNames.submit + "=${(e: CustomEvent) => { /* e.detail is the FormSubmitEvent; e.detail.data */ }}></gui-form>`. The event name is `" + formEventNames.submit + "` (camelCase) — Lit dispatches a raw CustomEvent, so there is no kebab-case alias.",
+  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: [...] })`).";
@@ -264,6 +513,7 @@ const INPUTS = [
   {
     factory: "textInput",
     namespace: "inputs",
+    docSlug: "textinput",
     call: "gui.inputs.textInput(path, { label, placeholder?, defaultValue?, validator? })",
     example: "gui.inputs.textInput('fullName', { label: 'Full name', validator: { required: true, minLength: 2 } })",
     notes: [
@@ -274,6 +524,7 @@ const INPUTS = [
   {
     factory: "numberInput",
     namespace: "inputs",
+    docSlug: "number",
     call: "gui.inputs.numberInput(path, { label, defaultValue?, validator? })",
     example: "gui.inputs.numberInput('age', { label: 'Age', validator: { required: true, minimum: 0, maximum: 120 } })",
     notes: [
@@ -283,6 +534,7 @@ const INPUTS = [
   {
     factory: "booleanInput",
     namespace: "inputs",
+    docSlug: "toggle",
     call: "gui.inputs.booleanInput(path, { label, defaultValue? })",
     example: "gui.inputs.booleanInput('newsletter', { label: 'Subscribe to newsletter', defaultValue: false })",
     notes: ["The on/off toggle for a single boolean. Use `checkbox` for a checkbox presentation."]
@@ -290,6 +542,7 @@ 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."]
@@ -297,6 +550,7 @@ const INPUTS = [
   {
     factory: "textarea",
     namespace: "inputs",
+    docSlug: "textarea",
     call: "gui.inputs.textarea(path, { label, placeholder?, validator? })",
     example: "gui.inputs.textarea('bio', { label: 'Bio', validator: { maxLength: 500 } })",
     notes: ["Multi-line text; same loose string validator as `textInput`."]
@@ -304,6 +558,7 @@ const INPUTS = [
   {
     factory: "password",
     namespace: "inputs",
+    docSlug: "password",
     call: "gui.inputs.password(path, { label, validator? })",
     example: "gui.inputs.password('password', { label: 'Password', validator: { required: true, minLength: 8 } })",
     notes: ["Masked text input; loose string validator."]
@@ -311,6 +566,7 @@ const INPUTS = [
   {
     factory: "dropdown",
     namespace: "inputs",
+    docSlug: "dropdown",
     call: "gui.inputs.dropdown(path, { label, items, validator? })",
     example: "gui.inputs.dropdown('country', { label: 'Country', items: [{ value: 'us', label: 'United States' }, { value: 'ca', label: 'Canada' }], validator: { type: 'string', required: true } })",
     notes: [
@@ -321,6 +577,7 @@ const INPUTS = [
   {
     factory: "radiogroup",
     namespace: "inputs",
+    docSlug: "radiogroup",
     call: "gui.inputs.radiogroup(path, { label, options, defaultValue?, validator? })",
     example: "gui.inputs.radiogroup('accountType', { label: 'Account type', defaultValue: 'personal', options: [{ value: 'personal', label: 'Personal' }, { value: 'business', label: 'Business' }] })",
     notes: [
@@ -331,6 +588,7 @@ const INPUTS = [
   {
     factory: "datePicker",
     namespace: "inputs",
+    docSlug: "date-picker",
     call: "gui.inputs.datePicker(path, { label, minDate?, maxDate?, validator? })",
     example: "gui.inputs.datePicker('startDate', { label: 'Coverage start', minDate: '2025-01-01', validator: { required: true } })",
     notes: [
@@ -341,6 +599,7 @@ const INPUTS = [
   {
     factory: "currency",
     namespace: "inputs",
+    docSlug: "currency",
     call: "gui.inputs.currency(path, { label, validator? })",
     example: "gui.inputs.currency('price', { label: 'Price', validator: { required: true, minimum: 0 } })",
     notes: ["Numeric money input; number-style validator."]
@@ -348,6 +607,7 @@ const INPUTS = [
   {
     factory: "select",
     namespace: "inputs",
+    docSlug: "select",
     call: "gui.inputs.select(path, { label, options, validator? })",
     example: "gui.inputs.select('plan', { label: 'Plan', options: [{ value: 'free', label: 'Free' }, { value: 'pro', label: 'Pro' }], validator: { type: 'string', required: true } })",
     notes: [
@@ -358,6 +618,7 @@ const INPUTS = [
   {
     factory: "dateInput",
     namespace: "inputs",
+    docSlug: "dateinput",
     call: "gui.inputs.dateInput(path, { label, minDate?, maxDate?, validator? })",
     example: "gui.inputs.dateInput('startDate', { label: 'Start date', validator: { required: true } })",
     notes: [
@@ -365,9 +626,40 @@ const INPUTS = [
       "`minDate` / `maxDate` (ISO `YYYY-MM-DD` strings) constrain the accepted range — see `datePicker`."
     ]
   },
+  {
+    factory: "timeInput",
+    namespace: "inputs",
+    docSlug: "timeinput",
+    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."
+    ]
+  },
+  {
+    factory: "timePicker",
+    namespace: "inputs",
+    docSlug: "timepicker",
+    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."
+    ]
+  },
+  {
+    factory: "dateTimeInput",
+    namespace: "inputs",
+    docSlug: "datetimeinput",
+    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`."
+    ]
+  },
   {
     factory: "calendar",
     namespace: "inputs",
+    docSlug: "calendar",
     call: "gui.inputs.calendar(path, { label, minDate?, maxDate? })",
     example: "gui.inputs.calendar('day', { label: 'Pick a day', minDate: '2025-01-01' })",
     notes: [
@@ -375,9 +667,34 @@ const INPUTS = [
       "`minDate` / `maxDate` (ISO `YYYY-MM-DD` strings) constrain the selectable range — see `datePicker`."
     ]
   },
+  {
+    factory: "dateTimeCalendar",
+    namespace: "inputs",
+    docSlug: "datetimecalendar",
+    call: "gui.inputs.dateTimeCalendar(path, { label, minDate?, maxDate?, minTime?, maxTime?, minuteStep?, disabledTimeRanges?, allowCustomTime? })",
+    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.",
+      "`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."
+    ]
+  },
+  {
+    factory: "dateTimePicker",
+    namespace: "inputs",
+    docSlug: "datetimepicker",
+    call: "gui.inputs.dateTimePicker(path, { label, minDate?, maxDate?, minTime?, maxTime?, minuteStep?, disabledTimeRanges?, allowCustomTime? })",
+    example: "gui.inputs.dateTimePicker('appointmentAt', { label: 'Appointment', minTime: '09:00', maxTime: '18:00' })",
+    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."
+    ]
+  },
   {
     factory: "markdown",
     namespace: "inputs",
+    docSlug: "markdown",
     call: "gui.inputs.markdown(path, { label })",
     example: "gui.inputs.markdown('notes', { label: 'Notes (markdown)' })",
     notes: [
@@ -387,6 +704,7 @@ const INPUTS = [
   {
     factory: "tags",
     namespace: "inputs",
+    docSlug: "tags",
     call: "gui.inputs.tags(path, { label })",
     example: "gui.inputs.tags('skills', { label: 'Skills' })",
     notes: ["Free-form multi-value tag input; the value is a string array."]
@@ -394,6 +712,7 @@ const INPUTS = [
   {
     factory: "repeater",
     namespace: "inputs",
+    docSlug: "repeater",
     call: "gui.inputs.repeater(path, { label?, addLabel?, removeLabel?, limit?, template })",
     example: "gui.inputs.repeater('attendees', { label: 'Attendees', addLabel: 'Add attendee', template: [ gui.inputs.textInput('attendees.items.name', { label: 'Name' }) ] })",
     notes: [
@@ -405,6 +724,7 @@ const INPUTS = [
   {
     factory: "list",
     namespace: "inputs",
+    docSlug: "list",
     call: "gui.inputs.list(path, { label, items, height?, itemHeight? })",
     example: "gui.inputs.list('selection', { label: 'Pick an option', items: ['Option 1', 'Option 2', 'Option 3'], height: 200, itemHeight: 40 })",
     notes: [
@@ -415,6 +735,7 @@ const INPUTS = [
   {
     factory: "rangeCalendar",
     namespace: "inputs",
+    docSlug: "range-calendar",
     call: "gui.inputs.rangeCalendar(path, { label? })",
     example: "gui.inputs.rangeCalendar('stayDates', { label: 'Stay dates' })",
     notes: [
@@ -424,22 +745,78 @@ const INPUTS = [
   {
     factory: "rangeDateInput",
     namespace: "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`)."]
   },
+  {
+    factory: "rangeTimeInput",
+    namespace: "inputs",
+    docSlug: "range-time-input",
+    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."
+    ]
+  },
+  {
+    factory: "rangeDateTimeInput",
+    namespace: "inputs",
+    docSlug: "range-datetime-input",
+    call: "gui.inputs.rangeDateTimeInput(path, { label?, minDateTime?, maxDateTime? })",
+    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."
+    ]
+  },
+  {
+    factory: "rangeDateTimeCalendar",
+    namespace: "inputs",
+    docSlug: "range-datetime-calendar",
+    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.",
+      "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."
+    ]
+  },
+  {
+    factory: "rangeDateTimePicker",
+    namespace: "inputs",
+    docSlug: "range-datetime-picker",
+    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.",
+      "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`."
+    ]
+  },
   {
     factory: "rangeDatePicker",
     namespace: "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`)."]
+  },
+  {
+    factory: "rangeTimePicker",
+    namespace: "inputs",
+    docSlug: "range-time-picker",
+    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."
+    ]
   }
 ];
 const ACTIONS = [
   {
     factory: "button",
     namespace: "actions",
+    docSlug: "button",
     call: "gui.actions.button({ label, actionType?: 'submit', onClick? })",
     example: "gui.actions.button({ label: 'Sign up', actionType: 'submit' })",
     notes: [
@@ -453,6 +830,7 @@ const DISPLAYS = [
   {
     factory: "alert",
     namespace: "displays",
+    docSlug: "alert",
     call: "gui.displays.alert({ text })",
     example: "gui.displays.alert({ text: 'Please review your details before submitting.' })",
     notes: [
@@ -462,6 +840,7 @@ const DISPLAYS = [
   {
     factory: "display",
     namespace: "displays",
+    docSlug: "renderer",
     call: "gui.displays.display(render)",
     example: "gui.displays.display(() => 'Order summary')",
     notes: [
@@ -474,6 +853,7 @@ const LAYOUTS = [
   {
     factory: "flex",
     namespace: "layouts",
+    docSlug: "flex",
     call: "gui.layouts.flex(children, props?)",
     example: "gui.layouts.flex([ gui.inputs.textInput('firstName', { label: 'First name' }), gui.inputs.textInput('lastName', { label: 'Last name' }) ])",
     notes: [
@@ -484,6 +864,7 @@ const LAYOUTS = [
   {
     factory: "verticalFlex",
     namespace: "layouts",
+    docSlug: "flex",
     call: "gui.layouts.verticalFlex(children, props?)",
     example: "gui.layouts.verticalFlex([ gui.inputs.textInput('a', { label: 'A' }), gui.inputs.textInput('b', { label: 'B' }) ])",
     notes: ["A `flex` with direction fixed to vertical."]
@@ -491,6 +872,7 @@ const LAYOUTS = [
   {
     factory: "horizontalFlex",
     namespace: "layouts",
+    docSlug: "flex",
     call: "gui.layouts.horizontalFlex(children, props?)",
     example: "gui.layouts.horizontalFlex([ gui.inputs.textInput('a', { label: 'A' }), gui.inputs.textInput('b', { label: 'B' }) ])",
     notes: ["A `flex` with direction fixed to horizontal."]
@@ -498,6 +880,7 @@ const LAYOUTS = [
   {
     factory: "grid",
     namespace: "layouts",
+    docSlug: "grid",
     call: "gui.layouts.grid(children, props?)",
     example: "gui.layouts.grid([ gui.inputs.textInput('a', { label: 'A' }), gui.inputs.textInput('b', { label: 'B' }) ])",
     notes: ["Grid layout; `horizontalGrid` / `verticalGrid` lock the direction."]
@@ -505,6 +888,7 @@ const LAYOUTS = [
   {
     factory: "verticalGrid",
     namespace: "layouts",
+    docSlug: "grid",
     call: "gui.layouts.verticalGrid(children, props?)",
     example: "gui.layouts.verticalGrid([ gui.inputs.textInput('a', { label: 'A' }), gui.inputs.textInput('b', { label: 'B' }) ])",
     notes: ["A `grid` with direction fixed to vertical."]
@@ -512,6 +896,7 @@ const LAYOUTS = [
   {
     factory: "horizontalGrid",
     namespace: "layouts",
+    docSlug: "grid",
     call: "gui.layouts.horizontalGrid(children, props?)",
     example: "gui.layouts.horizontalGrid([ gui.inputs.textInput('a', { label: 'A' }), gui.inputs.textInput('b', { label: 'B' }) ])",
     notes: ["A `grid` with direction fixed to horizontal."]
@@ -519,6 +904,7 @@ const LAYOUTS = [
   {
     factory: "tabs",
     namespace: "layouts",
+    docSlug: "tabs",
     call: "gui.layouts.tabs(sections)",
     example: "gui.layouts.tabs([ { label: 'Account', children: [ gui.inputs.textInput('email', { label: 'Email' }) ] }, { label: 'Profile', children: [ gui.inputs.textInput('name', { label: 'Name' }) ] } ])",
     notes: [
@@ -528,6 +914,7 @@ const LAYOUTS = [
   {
     factory: "accordion",
     namespace: "layouts",
+    docSlug: "accordion",
     call: "gui.layouts.accordion(sections)",
     example: "gui.layouts.accordion([ { label: 'Billing', children: [ gui.inputs.textInput('card', { label: 'Card' }) ] } ])",
     notes: [