@valbuild/next 0.96.2 → 0.97.0

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/{ValNextProvider-26ef0c1c.cjs.dev.js → ValNextProvider-03a9f8fd.cjs.dev.js}

@@ -4,18 +4,20 @@
 Object.defineProperty(exports, '__esModule', { value: true });
 
 var slicedToArray = require('./slicedToArray-44036a76.cjs.dev.js');
-var objectSpread2 = require('./objectSpread2-792eb2c2.cjs.dev.js');
+var objectSpread2 = require('./objectSpread2-58024783.cjs.dev.js');
 var core = require('@valbuild/core');
 var ui = require('@valbuild/ui');
 var navigation = require('next/navigation');
 var Script = require('next/script');
 var React = require('react');
-var ValOverlayContext = require('./ValOverlayContext-c82a4507.cjs.dev.js');
+var ValOverlayContext = require('./ValOverlayContext-c6f27a6d.cjs.dev.js');
 var stega = require('@valbuild/react/stega');
 var internal = require('@valbuild/shared/internal');
 var cssUtils = require('./cssUtils-9c11102f.cjs.dev.js');
+var createForOfIteratorHelper = require('./createForOfIteratorHelper-0445603c.cjs.dev.js');
 var jsxRuntime = require('react/jsx-runtime');
 require('./unsupportedIterableToArray-c8ab77c9.cjs.dev.js');
+require('./defineProperty-f90345d7.cjs.dev.js');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
 
@@ -41,6 +43,39 @@ function initSessionTheme(config) {
   return theme;
 }
 
+/**
+ * Returns true if the Val Enable cookie is set to "true" in the given cookie
+ * string (typically `document.cookie`).
+ *
+ * Exact-token match: a naive `includes("val_enable=true")` would also match
+ * unrelated cookies like `xval_enable=true`. The server sets the cookie to
+ * "false" (rather than deleting it) on disable, so the value must be checked
+ * too.
+ */
+function hasValEnableCookie(cookieString) {
+  var _iterator = createForOfIteratorHelper._createForOfIteratorHelper(cookieString.split(";")),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var part = _step.value;
+      var eq = part.indexOf("=");
+      if (eq === -1) {
+        continue;
+      }
+      var name = part.slice(0, eq).trim();
+      var value = part.slice(eq + 1).trim();
+      if (name === core.Internal.VAL_ENABLE_COOKIE_NAME && value === "true") {
+        return true;
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return false;
+}
+
 var ValNextProvider = function ValNextProvider(props) {
   // TODO: use config:
   var route = "/api/val";
@@ -54,27 +89,40 @@ var ValNextProvider = function ValNextProvider(props) {
   var valStore = React__default["default"].useMemo(function () {
     return new ValOverlayContext.ValExternalStore();
   }, []);
-  var _React$useState = React__default["default"].useState(),
+  // Whether useValStega should actually suspend. False during SSR and the
+  // hydration render — the server store is never populated (draft data
+  // arrives via browser CustomEvents only), so suspending there would just
+  // stall into the waitForLoad timeout, and hydration must render the static
+  // source so it matches the server HTML exactly. Activated post-hydration
+  // (in an effect, only when the Val Enable cookie is present) inside a
+  // transition: React keeps the static content visible while hooks suspend
+  // and then swaps to draft data as a normal update — no Suspense fallback
+  // flash and no hydration mismatch.
+  var _React$useState = React__default["default"].useState(false),
     _React$useState2 = slicedToArray._slicedToArray(_React$useState, 2),
-    mountOverlay = _React$useState2[0],
-    setMountOverlay = _React$useState2[1];
-  var _React$useState3 = React__default["default"].useState(null),
+    suspendActive = _React$useState2[0],
+    setSuspendActive = _React$useState2[1];
+  var _React$useState3 = React__default["default"].useState(),
     _React$useState4 = slicedToArray._slicedToArray(_React$useState3, 2),
-    draftMode = _React$useState4[0],
-    setDraftMode = _React$useState4[1];
-  var _React$useState5 = React__default["default"].useState(false),
+    mountOverlay = _React$useState4[0],
+    setMountOverlay = _React$useState4[1];
+  var _React$useState5 = React__default["default"].useState(null),
     _React$useState6 = slicedToArray._slicedToArray(_React$useState5, 2),
-    spaReady = _React$useState6[0],
-    setSpaReady = _React$useState6[1]; // TODO: consider removing spaReady - it is not used? If we remove, clean up the custom events that send the message too...
+    draftMode = _React$useState6[0],
+    setDraftMode = _React$useState6[1];
+  var _React$useState7 = React__default["default"].useState(false),
+    _React$useState8 = slicedToArray._slicedToArray(_React$useState7, 2),
+    spaReady = _React$useState8[0],
+    setSpaReady = _React$useState8[1]; // TODO: consider removing spaReady - it is not used? If we remove, clean up the custom events that send the message too...
   var router = navigation.useRouter();
   var _React$useTransition = React__default["default"].useTransition(),
     _React$useTransition2 = slicedToArray._slicedToArray(_React$useTransition, 2),
     startTransition = _React$useTransition2[1];
   var rerenderCounterRef = React__default["default"].useRef(0);
-  var _React$useState7 = React__default["default"].useState(null),
-    _React$useState8 = slicedToArray._slicedToArray(_React$useState7, 2),
-    iframeSrc = _React$useState8[0],
-    setIframeSrc = _React$useState8[1];
+  var _React$useState9 = React__default["default"].useState(null),
+    _React$useState0 = slicedToArray._slicedToArray(_React$useState9, 2),
+    iframeSrc = _React$useState0[0],
+    setIframeSrc = _React$useState0[1];
   var pathname = navigation.usePathname();
   React.useEffect(function () {
     window.dispatchEvent(new CustomEvent("val-provider:pathname", {
@@ -91,8 +139,21 @@ var ValNextProvider = function ValNextProvider(props) {
       setMountOverlay(false);
       return;
     }
-    setMountOverlay(document.cookie.includes("".concat(core.Internal.VAL_ENABLE_COOKIE_NAME, "=true")));
+    setMountOverlay(hasValEnableCookie(document.cookie));
   }, []);
+  React__default["default"].useEffect(function () {
+    // Activate the Suspense gate after hydration. Inside a transition so
+    // already-visible (static) content stays on screen while useValStega
+    // suspends — no fallback flash — and the swap to draft data commits as a
+    // normal update instead of a hydration mismatch. Never deactivated:
+    // components must not stop suspending across renders (the draft-mode-off
+    // release valve lives in useValStega instead).
+    if (props.suspend && shouldEnableVal()) {
+      startTransition(function () {
+        setSuspendActive(true);
+      });
+    }
+  }, [props.suspend]);
   React__default["default"].useEffect(function () {
     if (!mountOverlay) {
       return;
@@ -179,7 +240,11 @@ var ValNextProvider = function ValNextProvider(props) {
           return;
         }
         if (res.status === 401) {
-          // ignore when not authorized
+          // Not authorized (e.g. stale Val Enable cookie after the session
+          // expired): treat draft mode as off so useValStega's Suspense gate
+          // is released instead of leaving draftMode stuck at null and
+          // re-suspending into the waitForLoad timeout.
+          setDraftMode(false);
           return;
         }
         if (res.status !== 200) {
@@ -275,10 +340,10 @@ var ValNextProvider = function ValNextProvider(props) {
       window.dispatchEvent(new CustomEvent("val-append-overlay"));
     }
   });
-  var _React$useState9 = React__default["default"].useState(null),
-    _React$useState0 = slicedToArray._slicedToArray(_React$useState9, 2),
-    dropZone = _React$useState0[0],
-    setDropZone = _React$useState0[1];
+  var _React$useState1 = React__default["default"].useState(null),
+    _React$useState10 = slicedToArray._slicedToArray(_React$useState1, 2),
+    dropZone = _React$useState10[0],
+    setDropZone = _React$useState10[1];
   React__default["default"].useEffect(function () {
     var storedDropZone = localStorage.getItem("val-menu-drop-zone-default");
     if (storedDropZone) {
@@ -291,10 +356,10 @@ var ValNextProvider = function ValNextProvider(props) {
   var initTheme = React__default["default"].useMemo(function () {
     return initSessionTheme(props.config);
   }, [props.config]);
-  var _React$useState1 = React__default["default"].useState(false),
-    _React$useState10 = slicedToArray._slicedToArray(_React$useState1, 2),
-    spaLoaded = _React$useState10[0],
-    setSpaLoaded = _React$useState10[1];
+  var _React$useState11 = React__default["default"].useState(false),
+    _React$useState12 = slicedToArray._slicedToArray(_React$useState11, 2),
+    spaLoaded = _React$useState12[0],
+    setSpaLoaded = _React$useState12[1];
   React__default["default"].useEffect(function () {
     var listener = function listener() {
       setSpaLoaded(true);
@@ -334,6 +399,7 @@ var ValNextProvider = function ValNextProvider(props) {
   }, [cssUtils.valPrefixedClass]);
   return /*#__PURE__*/jsxRuntime.jsxs(ValOverlayContext.ValOverlayProvider, {
     draftMode: draftMode,
+    suspend: suspendActive,
     store: valStore,
     children: [props.children, dropZone !== null && !spaLoaded && mountOverlay && initTheme !== null && /*#__PURE__*/jsxRuntime.jsxs(React__default["default"].Fragment, {
       children: [/*#__PURE__*/jsxRuntime.jsx("style", {
@@ -447,6 +513,18 @@ function isValStudioPath(pathname) {
   return pathname.startsWith("/val");
 }
 
+// Same guards as the mountOverlay effect: suspending where the overlay can't
+// mount would only ever stall into the waitForLoad timeout. Browser-only.
+function shouldEnableVal() {
+  if (location.search === "?message_onready=true") {
+    return false;
+  }
+  if (isValStudioPath(location.pathname)) {
+    return false;
+  }
+  return hasValEnableCookie(document.cookie);
+}
+
 // function ValIcon() {
 //   return (
 //     <svg

package/dist/ValNextProvider-6103cb74.cjs.js

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