@valbuild/next 0.96.3 → 0.97.1

package/README.md

@@ -333,6 +333,39 @@ import { s } from "./val.config";
 s.string().nullable(); // <- Schema<string | null>
 ```
 
+## Description
+
+All schema types can be given a human-readable description with `.describe(text)`. Descriptions are shown in the Val editor UI as muted helper text under the field label, helping editors understand what a field is for without leaving the page.
+
+```ts
+import { s } from "./val.config";
+
+s.object({
+  name: s.string().describe("The author's full name"),
+}).describe("Author of the blog post");
+```
+
+For records, calling `.describe()` on the **key** schema labels the record keys in the editor (useful when the key is something like an email or slug that benefits from extra context), while calling it on the **value** schema describes the entry itself.
+
+```ts
+s.record(
+  s.string().describe("Email"),
+  s.object({ name: s.string() }).describe("Author"),
+);
+```
+
+`.describe()` can be combined freely with other modifiers and is preserved through `.nullable()`, `.validate()`, `.minLength()`, etc.:
+
+```ts
+s.string().describe("Slug").minLength(1).maxLength(64);
+```
+
+Pass `null` to clear a previously set description (useful when extending a base schema):
+
+```ts
+s.string().describe("Original").describe(null); // no description on the resulting schema
+```
+
 ## Array
 
 ```ts

package/client/dist/valbuild-next-client.cjs.dev.js

@@ -6,11 +6,12 @@ require('client-only');
 var core = require('@valbuild/core');
 var stega = require('@valbuild/react/stega');
 var React = require('react');
-var ValOverlayContext = require('../../dist/ValOverlayContext-c82a4507.cjs.dev.js');
-var routeFromVal = require('../../dist/routeFromVal-8fdaa0d0.cjs.dev.js');
+var ValOverlayContext = require('../../dist/ValOverlayContext-c6f27a6d.cjs.dev.js');
+var routeFromVal = require('../../dist/routeFromVal-9b610e77.cjs.dev.js');
 require('../../dist/createForOfIteratorHelper-0445603c.cjs.dev.js');
 require('../../dist/unsupportedIterableToArray-c8ab77c9.cjs.dev.js');
-require('../../dist/objectSpread2-792eb2c2.cjs.dev.js');
+require('../../dist/objectSpread2-58024783.cjs.dev.js');
+require('../../dist/defineProperty-f90345d7.cjs.dev.js');
 require('../../dist/slicedToArray-44036a76.cjs.dev.js');
 require('@valbuild/shared/internal');
 
@@ -31,6 +32,23 @@ function useValStega(selector) {
   }, store ? store.getServerSnapshot(moduleIds) : function () {
     return;
   });
+  // Suspense gate. `suspend` is false during SSR and hydration (so the static
+  // committed source is rendered, matching the server HTML exactly) and is
+  // activated by ValProvider after hydration — inside a transition — when the
+  // `suspend` prop is set AND the Val Enable cookie is present (checked
+  // client-side; the server store is never populated). It never deactivates.
+  // The production path (no cookie) skips the call entirely. The
+  // `draftMode !== false` check is a release valve: with draft mode off the
+  // store never receives source updates, so waitForLoad could only ever
+  // resolve via its timeout — and would then re-suspend on every subsequent
+  // render since the resolved promise is evicted from the cache. draftMode is
+  // null until the first /draft/stat poll resolves; null -> true keeps
+  // suspending, -> false only unblocks, and false -> true happens only on an
+  // explicit draft-mode enable which already refreshes the route.
+  // React.use is allowed inside conditionals — it is not a hook.
+  if (valOverlayContext.suspend && valOverlayContext.draftMode !== false && store && !store.hasAllLoaded(moduleIds)) {
+    React__default["default"].use(store.waitForLoad(moduleIds));
+  }
   return stega.stegaEncode(selector, {
     disabled: !valOverlayContext.draftMode,
     getModule: function getModule(moduleId) {
@@ -44,17 +62,18 @@ function resolveParams(params) {
   if (!params) {
     return null;
   }
-  var resolvedParams = "then" in params ? undefined : params;
   if ("then" in params) {
-    if ("use" in React__default["default"]) {
-      // This feels fairly safe: use should be possible to use inside if (?) and the if should most likely
-      resolvedParams = React__default["default"].use(params);
-    } else {
-      console.error("Val: useValRoute params argument was promise, but the React.use hook is unavailable. Please resolve the promise before passing it to useValRoute (or upgrade to React 19+).");
+    // Defensive guard: peerDependencies declare React >=19, but if a consumer
+    // somehow ends up on React 18 with a promise params arg, surface a
+    // diagnosable error instead of a cryptic `TypeError: React.use is not a
+    // function`. Callers treat null as the error sentinel.
+    if (!("use" in React__default["default"])) {
+      console.error("Val: useValRoute received a Promise params argument but React.use is unavailable. Upgrade to React 19+ or pre-resolve the promise before passing it.");
       return null;
     }
+    return React__default["default"].use(params);
   }
-  return resolvedParams;
+  return params;
 }
 function useValRouteStega(selector, params) {
   var val = useValStega(selector);

package/client/dist/valbuild-next-client.cjs.prod.js

@@ -6,11 +6,12 @@ require('client-only');
 var core = require('@valbuild/core');
 var stega = require('@valbuild/react/stega');
 var React = require('react');
-var ValOverlayContext = require('../../dist/ValOverlayContext-942f1294.cjs.prod.js');
-var routeFromVal = require('../../dist/routeFromVal-ef8c304a.cjs.prod.js');
+var ValOverlayContext = require('../../dist/ValOverlayContext-f7f45bc7.cjs.prod.js');
+var routeFromVal = require('../../dist/routeFromVal-13c832b2.cjs.prod.js');
 require('../../dist/createForOfIteratorHelper-d4afcad8.cjs.prod.js');
 require('../../dist/unsupportedIterableToArray-0d2087a2.cjs.prod.js');
-require('../../dist/objectSpread2-3c87fb4f.cjs.prod.js');
+require('../../dist/objectSpread2-13f847a9.cjs.prod.js');
+require('../../dist/defineProperty-8951f469.cjs.prod.js');
 require('../../dist/slicedToArray-ce613de6.cjs.prod.js');
 require('@valbuild/shared/internal');
 
@@ -31,6 +32,23 @@ function useValStega(selector) {
   }, store ? store.getServerSnapshot(moduleIds) : function () {
     return;
   });
+  // Suspense gate. `suspend` is false during SSR and hydration (so the static
+  // committed source is rendered, matching the server HTML exactly) and is
+  // activated by ValProvider after hydration — inside a transition — when the
+  // `suspend` prop is set AND the Val Enable cookie is present (checked
+  // client-side; the server store is never populated). It never deactivates.
+  // The production path (no cookie) skips the call entirely. The
+  // `draftMode !== false` check is a release valve: with draft mode off the
+  // store never receives source updates, so waitForLoad could only ever
+  // resolve via its timeout — and would then re-suspend on every subsequent
+  // render since the resolved promise is evicted from the cache. draftMode is
+  // null until the first /draft/stat poll resolves; null -> true keeps
+  // suspending, -> false only unblocks, and false -> true happens only on an
+  // explicit draft-mode enable which already refreshes the route.
+  // React.use is allowed inside conditionals — it is not a hook.
+  if (valOverlayContext.suspend && valOverlayContext.draftMode !== false && store && !store.hasAllLoaded(moduleIds)) {
+    React__default["default"].use(store.waitForLoad(moduleIds));
+  }
   return stega.stegaEncode(selector, {
     disabled: !valOverlayContext.draftMode,
     getModule: function getModule(moduleId) {
@@ -44,17 +62,18 @@ function resolveParams(params) {
   if (!params) {
     return null;
   }
-  var resolvedParams = "then" in params ? undefined : params;
   if ("then" in params) {
-    if ("use" in React__default["default"]) {
-      // This feels fairly safe: use should be possible to use inside if (?) and the if should most likely
-      resolvedParams = React__default["default"].use(params);
-    } else {
-      console.error("Val: useValRoute params argument was promise, but the React.use hook is unavailable. Please resolve the promise before passing it to useValRoute (or upgrade to React 19+).");
+    // Defensive guard: peerDependencies declare React >=19, but if a consumer
+    // somehow ends up on React 18 with a promise params arg, surface a
+    // diagnosable error instead of a cryptic `TypeError: React.use is not a
+    // function`. Callers treat null as the error sentinel.
+    if (!("use" in React__default["default"])) {
+      console.error("Val: useValRoute received a Promise params argument but React.use is unavailable. Upgrade to React 19+ or pre-resolve the promise before passing it.");
       return null;
     }
+    return React__default["default"].use(params);
   }
-  return resolvedParams;
+  return params;
 }
 function useValRouteStega(selector, params) {
   var val = useValStega(selector);

package/client/dist/valbuild-next-client.esm.js

@@ -2,11 +2,12 @@ import 'client-only';
 import { Internal } from '@valbuild/core';
 import { getModuleIds, stegaEncode } from '@valbuild/react/stega';
 import React from 'react';
-import { useValOverlayContext } from '../../dist/ValOverlayContext-6635a4d7.esm.js';
-import { i as initValRouteFromVal, g as getValRouteUrlFromVal } from '../../dist/routeFromVal-748d2aec.esm.js';
+import { useValOverlayContext } from '../../dist/ValOverlayContext-3c37e5a7.esm.js';
+import { i as initValRouteFromVal, g as getValRouteUrlFromVal } from '../../dist/routeFromVal-8855a5cc.esm.js';
 import '../../dist/createForOfIteratorHelper-5758a730.esm.js';
 import '../../dist/unsupportedIterableToArray-5baabfdc.esm.js';
-import '../../dist/objectSpread2-c1340c1c.esm.js';
+import '../../dist/objectSpread2-60d1bd93.esm.js';
+import '../../dist/defineProperty-cca5affa.esm.js';
 import '../../dist/slicedToArray-aa291011.esm.js';
 import '@valbuild/shared/internal';
 
@@ -23,6 +24,23 @@ function useValStega(selector) {
   }, store ? store.getServerSnapshot(moduleIds) : function () {
     return;
   });
+  // Suspense gate. `suspend` is false during SSR and hydration (so the static
+  // committed source is rendered, matching the server HTML exactly) and is
+  // activated by ValProvider after hydration — inside a transition — when the
+  // `suspend` prop is set AND the Val Enable cookie is present (checked
+  // client-side; the server store is never populated). It never deactivates.
+  // The production path (no cookie) skips the call entirely. The
+  // `draftMode !== false` check is a release valve: with draft mode off the
+  // store never receives source updates, so waitForLoad could only ever
+  // resolve via its timeout — and would then re-suspend on every subsequent
+  // render since the resolved promise is evicted from the cache. draftMode is
+  // null until the first /draft/stat poll resolves; null -> true keeps
+  // suspending, -> false only unblocks, and false -> true happens only on an
+  // explicit draft-mode enable which already refreshes the route.
+  // React.use is allowed inside conditionals — it is not a hook.
+  if (valOverlayContext.suspend && valOverlayContext.draftMode !== false && store && !store.hasAllLoaded(moduleIds)) {
+    React.use(store.waitForLoad(moduleIds));
+  }
   return stegaEncode(selector, {
     disabled: !valOverlayContext.draftMode,
     getModule: function getModule(moduleId) {
@@ -36,17 +54,18 @@ function resolveParams(params) {
   if (!params) {
     return null;
   }
-  var resolvedParams = "then" in params ? undefined : params;
   if ("then" in params) {
-    if ("use" in React) {
-      // This feels fairly safe: use should be possible to use inside if (?) and the if should most likely
-      resolvedParams = React.use(params);
-    } else {
-      console.error("Val: useValRoute params argument was promise, but the React.use hook is unavailable. Please resolve the promise before passing it to useValRoute (or upgrade to React 19+).");
+    // Defensive guard: peerDependencies declare React >=19, but if a consumer
+    // somehow ends up on React 18 with a promise params arg, surface a
+    // diagnosable error instead of a cryptic `TypeError: React.use is not a
+    // function`. Callers treat null as the error sentinel.
+    if (!("use" in React)) {
+      console.error("Val: useValRoute received a Promise params argument but React.use is unavailable. Upgrade to React 19+ or pre-resolve the promise before passing it.");
       return null;
     }
+    return React.use(params);
   }
-  return resolvedParams;
+  return params;
 }
 function useValRouteStega(selector, params) {
   var val = useValStega(selector);

package/dist/{ValApp-3df36e0d.cjs.dev.js → ValApp-1992d8b3.cjs.dev.js}

@@ -18,7 +18,8 @@ function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e };
 var Script__default = /*#__PURE__*/_interopDefault(Script);
 
 var ValApp = function ValApp(_ref) {
-  var config = _ref.config;
+  var config = _ref.config,
+    children = _ref.children;
   var route = "/api/val"; // TODO: make configurable
   var _useState = React.useState(),
     _useState2 = slicedToArray._slicedToArray(_useState, 2),
@@ -134,7 +135,7 @@ var ValApp = function ValApp(_ref) {
     }), /*#__PURE__*/jsxRuntime.jsx("div", {
       id: ui.VAL_APP_ID,
       ref: container
-    })]
+    }), children]
   });
 };
 

package/dist/{ValApp-e2e1dfed.esm.js → ValApp-8912fc8b.esm.js}

@@ -10,7 +10,8 @@ import '@valbuild/shared/internal';
 import '@valbuild/core';
 
 var ValApp = function ValApp(_ref) {
-  var config = _ref.config;
+  var config = _ref.config,
+    children = _ref.children;
   var route = "/api/val"; // TODO: make configurable
   var _useState = useState(),
     _useState2 = _slicedToArray(_useState, 2),
@@ -126,7 +127,7 @@ var ValApp = function ValApp(_ref) {
     }), /*#__PURE__*/jsx("div", {
       id: VAL_APP_ID,
       ref: container
-    })]
+    }), children]
   });
 };
 

package/dist/ValApp-bb207e96.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+if (process.env.NODE_ENV === "production") {
+  module.exports = require("./ValApp-bb207e96.cjs.prod.js");
+} else {
+  module.exports = require("./ValApp-bb207e96.cjs.dev.js");
+}

package/dist/{ValApp-22147086.cjs.prod.js → ValApp-bb207e96.cjs.prod.js}

@@ -18,7 +18,8 @@ function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e };
 var Script__default = /*#__PURE__*/_interopDefault(Script);
 
 var ValApp = function ValApp(_ref) {
-  var config = _ref.config;
+  var config = _ref.config,
+    children = _ref.children;
   var route = "/api/val"; // TODO: make configurable
   var _useState = React.useState(),
     _useState2 = slicedToArray._slicedToArray(_useState, 2),
@@ -134,7 +135,7 @@ var ValApp = function ValApp(_ref) {
     }), /*#__PURE__*/jsxRuntime.jsx("div", {
       id: ui.VAL_APP_ID,
       ref: container
-    })]
+    }), children]
   });
 };
 

package/dist/ValModulesClient-0dd601a1.esm.js

@@ -0,0 +1,48 @@
+'use client';
+import { useEffect } from 'react';
+
+// Keep in sync with VAL_MODULES_UPDATED_EVENT in @valbuild/ui (useValModules.ts).
+var VAL_MODULES_UPDATED_EVENT = "val-modules-updated";
+
+/**
+ * Registers the user's `val.modules` registry on `window.__VAL_MODULES__` so
+ * the Val editor SPA (both the `/val` app and the on-page overlay) can read it.
+ *
+ * Must be called from a Client Component that statically imports `val.modules`:
+ * the module `def` entries are function closures, so the registry cannot be
+ * passed as a prop across the Server → Client Component boundary and must be
+ * pulled into the client bundle and registered via the window global instead.
+ *
+ * Re-runs when the `modules` reference changes (e.g. on HMR) and dispatches
+ * `val-modules-updated` so the SPA picks up the new registry.
+ */
+function useRegisterValModules(modules) {
+  useEffect(function () {
+    window.__VAL_MODULES__ = modules;
+    window.dispatchEvent(new CustomEvent(VAL_MODULES_UPDATED_EVENT));
+  }, [modules]);
+}
+
+/**
+ * Registers the user's `val.modules` registry for the Val editor SPA.
+ *
+ * Render this inside both `<ValProvider>` (root layout) and `<ValApp>` (the
+ * `/val` page), passing your `val.modules` default export. Use it from a
+ * Client Component so the registry ends up in the client bundle:
+ *
+ * @example
+ * "use client";
+ * import { ValModulesClient } from "@valbuild/next";
+ * import valModules from "../../val.modules";
+ *
+ * export function RegisterValModules() {
+ *   return <ValModulesClient modules={valModules} />;
+ * }
+ */
+function ValModulesClient(_ref) {
+  var modules = _ref.modules;
+  useRegisterValModules(modules);
+  return null;
+}
+
+export { ValModulesClient, useRegisterValModules };

package/dist/ValModulesClient-10c0721c.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+if (process.env.NODE_ENV === "production") {
+  module.exports = require("./ValModulesClient-10c0721c.cjs.prod.js");
+} else {
+  module.exports = require("./ValModulesClient-10c0721c.cjs.dev.js");
+}

package/dist/ValModulesClient-10c0721c.cjs.prod.js

@@ -0,0 +1,53 @@
+'use client';
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var React = require('react');
+
+// Keep in sync with VAL_MODULES_UPDATED_EVENT in @valbuild/ui (useValModules.ts).
+var VAL_MODULES_UPDATED_EVENT = "val-modules-updated";
+
+/**
+ * Registers the user's `val.modules` registry on `window.__VAL_MODULES__` so
+ * the Val editor SPA (both the `/val` app and the on-page overlay) can read it.
+ *
+ * Must be called from a Client Component that statically imports `val.modules`:
+ * the module `def` entries are function closures, so the registry cannot be
+ * passed as a prop across the Server → Client Component boundary and must be
+ * pulled into the client bundle and registered via the window global instead.
+ *
+ * Re-runs when the `modules` reference changes (e.g. on HMR) and dispatches
+ * `val-modules-updated` so the SPA picks up the new registry.
+ */
+function useRegisterValModules(modules) {
+  React.useEffect(function () {
+    window.__VAL_MODULES__ = modules;
+    window.dispatchEvent(new CustomEvent(VAL_MODULES_UPDATED_EVENT));
+  }, [modules]);
+}
+
+/**
+ * Registers the user's `val.modules` registry for the Val editor SPA.
+ *
+ * Render this inside both `<ValProvider>` (root layout) and `<ValApp>` (the
+ * `/val` page), passing your `val.modules` default export. Use it from a
+ * Client Component so the registry ends up in the client bundle:
+ *
+ * @example
+ * "use client";
+ * import { ValModulesClient } from "@valbuild/next";
+ * import valModules from "../../val.modules";
+ *
+ * export function RegisterValModules() {
+ *   return <ValModulesClient modules={valModules} />;
+ * }
+ */
+function ValModulesClient(_ref) {
+  var modules = _ref.modules;
+  useRegisterValModules(modules);
+  return null;
+}
+
+exports.ValModulesClient = ValModulesClient;
+exports.useRegisterValModules = useRegisterValModules;

package/dist/ValModulesClient-4ecabf99.cjs.dev.js

@@ -0,0 +1,53 @@
+'use client';
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var React = require('react');
+
+// Keep in sync with VAL_MODULES_UPDATED_EVENT in @valbuild/ui (useValModules.ts).
+var VAL_MODULES_UPDATED_EVENT = "val-modules-updated";
+
+/**
+ * Registers the user's `val.modules` registry on `window.__VAL_MODULES__` so
+ * the Val editor SPA (both the `/val` app and the on-page overlay) can read it.
+ *
+ * Must be called from a Client Component that statically imports `val.modules`:
+ * the module `def` entries are function closures, so the registry cannot be
+ * passed as a prop across the Server → Client Component boundary and must be
+ * pulled into the client bundle and registered via the window global instead.
+ *
+ * Re-runs when the `modules` reference changes (e.g. on HMR) and dispatches
+ * `val-modules-updated` so the SPA picks up the new registry.
+ */
+function useRegisterValModules(modules) {
+  React.useEffect(function () {
+    window.__VAL_MODULES__ = modules;
+    window.dispatchEvent(new CustomEvent(VAL_MODULES_UPDATED_EVENT));
+  }, [modules]);
+}
+
+/**
+ * Registers the user's `val.modules` registry for the Val editor SPA.
+ *
+ * Render this inside both `<ValProvider>` (root layout) and `<ValApp>` (the
+ * `/val` page), passing your `val.modules` default export. Use it from a
+ * Client Component so the registry ends up in the client bundle:
+ *
+ * @example
+ * "use client";
+ * import { ValModulesClient } from "@valbuild/next";
+ * import valModules from "../../val.modules";
+ *
+ * export function RegisterValModules() {
+ *   return <ValModulesClient modules={valModules} />;
+ * }
+ */
+function ValModulesClient(_ref) {
+  var modules = _ref.modules;
+  useRegisterValModules(modules);
+  return null;
+}
+
+exports.ValModulesClient = ValModulesClient;
+exports.useRegisterValModules = useRegisterValModules;