@valbuild/next 0.101.1 → 0.103.0

package/README.md

@@ -42,6 +42,7 @@
 
 - [Installation](#installation)
 - [Getting started](#getting-started)
+- [Previewing unpublished pages](#previewing-unpublished-pages)
 - [Schema types](#schema-types):
   - [String](#string)
   - [Number](#number)
@@ -235,6 +236,50 @@ export type { t } from "@valbuild/next";
 export { s, c, val, config };
 ```
 
+# Previewing unpublished pages
+
+An editor who creates a page in the Val editor has not published it yet: the new
+route exists only as a pending change. Your app knows nothing about it, so
+opening that URL hits a `page.tsx` whose content lookup finds no such key — and
+a page component that answers a missing key with `notFound()` shows the editor a
+404 for the page they just made.
+
+`suspend` on `ValProvider` is what makes that page load. Set it when the editor
+should be able to preview unpublished pages:
+
+```tsx
+// ./app/layout.tsx
+<ValProvider config={config} suspend>
+  <ValModulesClient />
+  {children}
+</ValProvider>
+```
+
+With it set, a component reading content through `useVal`, `useValRoute`,
+`fetchVal` or `fetchValRoute` suspends until the editor's pending changes have
+been applied, instead of resolving against published content and rendering
+something the editor did not ask for. Put a `Suspense` boundary where you want
+the loading state to show; without one, Next uses the nearest `loading.tsx`.
+
+**It only ever waits for editors.** Nothing here runs for a visitor: the gate is
+behind the same `val_enable` cookie the editor overlay is, so a normal request
+makes no extra requests, waits for nothing, and renders exactly as it would
+without `suspend`. It is safe to leave on in production, which is the point —
+previewing unpublished content is something editors do against the deployed site.
+
+**What it costs an editor.** Pending changes come from the editor's browser, so a
+page opened with the editor active waits for them to arrive before it renders.
+That is the trade: a short wait instead of published content flashing up and
+being replaced, or a 404 for a page that exists.
+
+**Known limitation.** A page whose route exists _only_ in an unpublished change
+can still 404 on the very first render: `suspend` is activated in the browser
+after hydration, and the render before that resolves against published content.
+A page that calls `notFound()` at that point cannot recover, since the response
+has already been sent. Reloading the page in the editor works around it. Pages
+that read content for a route they already have — the common case, editing an
+existing page — are not affected.
+
 # Formatting published content
 
 If you are using `prettier` or another code formatting tool, it is recommended to setup formatting of code after changes have been applied.
@@ -460,6 +505,8 @@ export default c.define("/app/[slug]/page.val.ts", pageSchema, {
 
 To consume a page route from a NextJS "page component", it is recommended you use `fetchValRoute` or `useValRoute`.
 
+NOTE: a page an editor has created but not published yet is not in the record, so `fetchValRoute` / `useValRoute` return `null` for it and a page component that calls `notFound()` shows the editor a 404. See [previewing unpublished pages](#previewing-unpublished-pages).
+
 NOTE: to be refactor proof (i.e. not break when changing the route), you should always provide the params of the NextJS page component.
 
 #### Example fetchValRoute
@@ -730,7 +777,9 @@ import { s, c } from "../val.config";
 
 export const schema = s.image();
 
-export default c.define("/image", schema, c.image("/public/myfile.jpg"));
+export default c.define("/image", schema, {
+  path: "/public/myfile.jpg",
+});
 ```
 
 **NOTE**: This will not validate, since images requires `width`, `height` and `mimeType`. You can fix validation errors like this by using the CLI or by using the VS Code plugin.

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

@@ -7,7 +7,7 @@ var routeFromVal = require('../../dist/routeFromVal-b48a454a.cjs.dev.js');
 var core = require('@valbuild/core');
 var stega = require('@valbuild/react/stega');
 var React = require('react');
-var ValOverlayContext = require('../../dist/ValOverlayContext-c6f27a6d.cjs.dev.js');
+var ValOverlayContext = require('../../dist/ValOverlayContext-ca3b6ebd.cjs.dev.js');
 require('../../dist/createForOfIteratorHelper-0445603c.cjs.dev.js');
 require('../../dist/unsupportedIterableToArray-c8ab77c9.cjs.dev.js');
 require('../../dist/objectSpread2-58024783.cjs.dev.js');
@@ -46,7 +46,30 @@ function useValStega(selector) {
   // 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)) {
+  /**
+   * Wait until draft mode is KNOWN, before anything else.
+   *
+   * `draftMode === null` means `/draft/stat` has not answered yet, and the
+   * `getModule` below treats it as off — so a render that slips through here
+   * while it is unknown resolves against committed source. For an ordinary field
+   * that is a flash of published content; for `useValRoute` on a route that
+   * exists only in an uncommitted patch it is `notFound()`, which no later
+   * answer can undo. That was the 404 on a page you had just created.
+   */
+  if (valOverlayContext.suspend && valOverlayContext.draftMode === null && valOverlayContext.draftModeReady) {
+    React__default["default"].use(valOverlayContext.draftModeReady);
+  }
+  /**
+   * Then wait for the draft sources — but only while more might be coming.
+   *
+   * `draftSourcesSynced` is the editor saying it has sent everything it holds,
+   * and it only holds modules with patches: an unedited module has no draft, so
+   * nothing is ever sent for it. Without that signal this could not tell "not
+   * sent yet" from "nothing to send", and waited out `waitForLoad`'s ten second
+   * timeout once per unedited module the page reads — which is what left a newly
+   * created page sitting on its loading fallback.
+   */
+  if (valOverlayContext.suspend && valOverlayContext.draftMode !== false && !valOverlayContext.draftSourcesSynced && store && !store.hasAllLoaded(moduleIds)) {
     React__default["default"].use(store.waitForLoad(moduleIds));
   }
   return stega.stegaEncode(selector, {

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

@@ -7,7 +7,7 @@ var routeFromVal = require('../../dist/routeFromVal-8ac2f984.cjs.prod.js');
 var core = require('@valbuild/core');
 var stega = require('@valbuild/react/stega');
 var React = require('react');
-var ValOverlayContext = require('../../dist/ValOverlayContext-f7f45bc7.cjs.prod.js');
+var ValOverlayContext = require('../../dist/ValOverlayContext-1d019b95.cjs.prod.js');
 require('../../dist/createForOfIteratorHelper-d4afcad8.cjs.prod.js');
 require('../../dist/unsupportedIterableToArray-0d2087a2.cjs.prod.js');
 require('../../dist/objectSpread2-13f847a9.cjs.prod.js');
@@ -46,7 +46,30 @@ function useValStega(selector) {
   // 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)) {
+  /**
+   * Wait until draft mode is KNOWN, before anything else.
+   *
+   * `draftMode === null` means `/draft/stat` has not answered yet, and the
+   * `getModule` below treats it as off — so a render that slips through here
+   * while it is unknown resolves against committed source. For an ordinary field
+   * that is a flash of published content; for `useValRoute` on a route that
+   * exists only in an uncommitted patch it is `notFound()`, which no later
+   * answer can undo. That was the 404 on a page you had just created.
+   */
+  if (valOverlayContext.suspend && valOverlayContext.draftMode === null && valOverlayContext.draftModeReady) {
+    React__default["default"].use(valOverlayContext.draftModeReady);
+  }
+  /**
+   * Then wait for the draft sources — but only while more might be coming.
+   *
+   * `draftSourcesSynced` is the editor saying it has sent everything it holds,
+   * and it only holds modules with patches: an unedited module has no draft, so
+   * nothing is ever sent for it. Without that signal this could not tell "not
+   * sent yet" from "nothing to send", and waited out `waitForLoad`'s ten second
+   * timeout once per unedited module the page reads — which is what left a newly
+   * created page sitting on its loading fallback.
+   */
+  if (valOverlayContext.suspend && valOverlayContext.draftMode !== false && !valOverlayContext.draftSourcesSynced && store && !store.hasAllLoaded(moduleIds)) {
     React__default["default"].use(store.waitForLoad(moduleIds));
   }
   return stega.stegaEncode(selector, {

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

@@ -3,7 +3,7 @@ import { g as getJsonEntryStegaRoot, _ as _typeof, a as isJsonValuesRecordSchema
 import { Internal } from '@valbuild/core';
 import { getModuleIds, stegaEncode } from '@valbuild/react/stega';
 import React from 'react';
-import { useValOverlayContext } from '../../dist/ValOverlayContext-3c37e5a7.esm.js';
+import { useValOverlayContext } from '../../dist/ValOverlayContext-f63e0fc9.esm.js';
 import '../../dist/createForOfIteratorHelper-5758a730.esm.js';
 import '../../dist/unsupportedIterableToArray-5baabfdc.esm.js';
 import '../../dist/objectSpread2-60d1bd93.esm.js';
@@ -38,7 +38,30 @@ function useValStega(selector) {
   // 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)) {
+  /**
+   * Wait until draft mode is KNOWN, before anything else.
+   *
+   * `draftMode === null` means `/draft/stat` has not answered yet, and the
+   * `getModule` below treats it as off — so a render that slips through here
+   * while it is unknown resolves against committed source. For an ordinary field
+   * that is a flash of published content; for `useValRoute` on a route that
+   * exists only in an uncommitted patch it is `notFound()`, which no later
+   * answer can undo. That was the 404 on a page you had just created.
+   */
+  if (valOverlayContext.suspend && valOverlayContext.draftMode === null && valOverlayContext.draftModeReady) {
+    React.use(valOverlayContext.draftModeReady);
+  }
+  /**
+   * Then wait for the draft sources — but only while more might be coming.
+   *
+   * `draftSourcesSynced` is the editor saying it has sent everything it holds,
+   * and it only holds modules with patches: an unedited module has no draft, so
+   * nothing is ever sent for it. Without that signal this could not tell "not
+   * sent yet" from "nothing to send", and waited out `waitForLoad`'s ten second
+   * timeout once per unedited module the page reads — which is what left a newly
+   * created page sitting on its loading fallback.
+   */
+  if (valOverlayContext.suspend && valOverlayContext.draftMode !== false && !valOverlayContext.draftSourcesSynced && store && !store.hasAllLoaded(moduleIds)) {
     React.use(store.waitForLoad(moduleIds));
   }
   return stegaEncode(selector, {

package/dist/ValApp-90c4171d.cjs.js

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

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

@@ -7,7 +7,7 @@ var slicedToArray = require('./slicedToArray-ce613de6.cjs.prod.js');
 var ui = require('@valbuild/ui');
 var Script = require('next/script');
 var React = require('react');
-var cssUtils = require('./cssUtils-d97a757c.cjs.prod.js');
+var fallbackColors = require('./fallbackColors-d4a5b0da.cjs.prod.js');
 var jsxRuntime = require('react/jsx-runtime');
 require('./unsupportedIterableToArray-0d2087a2.cjs.prod.js');
 require('@valbuild/shared/internal');
@@ -26,7 +26,7 @@ var ValApp = function ValApp(_ref) {
     inMessageMode = _useState2[0],
     setInMessageMode = _useState2[1];
   var isClientSIde = inMessageMode === undefined;
-  cssUtils.useConfigStorageSave(config);
+  fallbackColors.useConfigStorageSave(config);
   var container = React.useRef(null);
   React.useEffect(function () {
     if (location.search === "?message_onready=true") {
@@ -65,8 +65,10 @@ var ValApp = function ValApp(_ref) {
       setLoadingTheme(config.defaultTheme);
     }
   }, [config]);
-  var darkBg = "#0c111d";
-  var lightBg = "white";
+  // The studio's canvas, so the loading screen is the same colour as what
+  // replaces it rather than a flash of a different one.
+  var darkBg = fallbackColors.canvasDarkBg;
+  var lightBg = fallbackColors.canvasLightBg;
   React.useEffect(function () {
     if (inMessageMode || loadingTheme === null) {
       return;
@@ -104,7 +106,7 @@ var ValApp = function ValApp(_ref) {
         minWidth: "100%"
       },
       children: [/*#__PURE__*/jsxRuntime.jsx("style", {
-        children: ".".concat(cssUtils.valPrefixedClass, "animate-spin {\n  animation: ").concat(cssUtils.valPrefixedClass, "spin 2s linear infinite;\n}\n@keyframes ").concat(cssUtils.valPrefixedClass, "spin {\n  0% {\n    transform: rotate(0deg);\n  }\n  100% {\n    transform: rotate(360deg);\n  }\n}")
+        children: ".".concat(fallbackColors.valPrefixedClass, "animate-spin {\n  animation: ").concat(fallbackColors.valPrefixedClass, "spin 2s linear infinite;\n}\n@keyframes ").concat(fallbackColors.valPrefixedClass, "spin {\n  0% {\n    transform: rotate(0deg);\n  }\n  100% {\n    transform: rotate(360deg);\n  }\n}")
       }), /*#__PURE__*/jsxRuntime.jsx("svg", {
         xmlns: "http://www.w3.org/2000/svg",
         width: "24",
@@ -115,7 +117,7 @@ var ValApp = function ValApp(_ref) {
         strokeWidth: "2",
         strokeLinecap: "round",
         strokeLinejoin: "round",
-        className: cssUtils.cn(["animate-spin"]),
+        className: fallbackColors.cn(["animate-spin"]),
         children: /*#__PURE__*/jsxRuntime.jsx("path", {
           d: "M21 12a9 9 0 1 1-6.219-8.56"
         })

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

@@ -7,7 +7,7 @@ var slicedToArray = require('./slicedToArray-44036a76.cjs.dev.js');
 var ui = require('@valbuild/ui');
 var Script = require('next/script');
 var React = require('react');
-var cssUtils = require('./cssUtils-9c11102f.cjs.dev.js');
+var fallbackColors = require('./fallbackColors-9a2ac53a.cjs.dev.js');
 var jsxRuntime = require('react/jsx-runtime');
 require('./unsupportedIterableToArray-c8ab77c9.cjs.dev.js');
 require('@valbuild/shared/internal');
@@ -26,7 +26,7 @@ var ValApp = function ValApp(_ref) {
     inMessageMode = _useState2[0],
     setInMessageMode = _useState2[1];
   var isClientSIde = inMessageMode === undefined;
-  cssUtils.useConfigStorageSave(config);
+  fallbackColors.useConfigStorageSave(config);
   var container = React.useRef(null);
   React.useEffect(function () {
     if (location.search === "?message_onready=true") {
@@ -65,8 +65,10 @@ var ValApp = function ValApp(_ref) {
       setLoadingTheme(config.defaultTheme);
     }
   }, [config]);
-  var darkBg = "#0c111d";
-  var lightBg = "white";
+  // The studio's canvas, so the loading screen is the same colour as what
+  // replaces it rather than a flash of a different one.
+  var darkBg = fallbackColors.canvasDarkBg;
+  var lightBg = fallbackColors.canvasLightBg;
   React.useEffect(function () {
     if (inMessageMode || loadingTheme === null) {
       return;
@@ -104,7 +106,7 @@ var ValApp = function ValApp(_ref) {
         minWidth: "100%"
       },
       children: [/*#__PURE__*/jsxRuntime.jsx("style", {
-        children: ".".concat(cssUtils.valPrefixedClass, "animate-spin {\n  animation: ").concat(cssUtils.valPrefixedClass, "spin 2s linear infinite;\n}\n@keyframes ").concat(cssUtils.valPrefixedClass, "spin {\n  0% {\n    transform: rotate(0deg);\n  }\n  100% {\n    transform: rotate(360deg);\n  }\n}")
+        children: ".".concat(fallbackColors.valPrefixedClass, "animate-spin {\n  animation: ").concat(fallbackColors.valPrefixedClass, "spin 2s linear infinite;\n}\n@keyframes ").concat(fallbackColors.valPrefixedClass, "spin {\n  0% {\n    transform: rotate(0deg);\n  }\n  100% {\n    transform: rotate(360deg);\n  }\n}")
       }), /*#__PURE__*/jsxRuntime.jsx("svg", {
         xmlns: "http://www.w3.org/2000/svg",
         width: "24",
@@ -115,7 +117,7 @@ var ValApp = function ValApp(_ref) {
         strokeWidth: "2",
         strokeLinecap: "round",
         strokeLinejoin: "round",
-        className: cssUtils.cn(["animate-spin"]),
+        className: fallbackColors.cn(["animate-spin"]),
         children: /*#__PURE__*/jsxRuntime.jsx("path", {
           d: "M21 12a9 9 0 1 1-6.219-8.56"
         })

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

@@ -3,7 +3,7 @@ import { _ as _slicedToArray } from './slicedToArray-aa291011.esm.js';
 import { VERSION, VAL_APP_PATH, VAL_APP_ID } from '@valbuild/ui';
 import Script from 'next/script';
 import { useState, useRef, useEffect } from 'react';
-import { u as useConfigStorageSave, v as valPrefixedClass, c as cn } from './cssUtils-b5651c03.esm.js';
+import { u as useConfigStorageSave, v as valPrefixedClass, c as cn, a as canvasDarkBg, b as canvasLightBg } from './fallbackColors-5ead2c26.esm.js';
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 import './unsupportedIterableToArray-5baabfdc.esm.js';
 import '@valbuild/shared/internal';
@@ -57,8 +57,10 @@ var ValApp = function ValApp(_ref) {
       setLoadingTheme(config.defaultTheme);
     }
   }, [config]);
-  var darkBg = "#0c111d";
-  var lightBg = "white";
+  // The studio's canvas, so the loading screen is the same colour as what
+  // replaces it rather than a flash of a different one.
+  var darkBg = canvasDarkBg;
+  var lightBg = canvasLightBg;
   useEffect(function () {
     if (inMessageMode || loadingTheme === null) {
       return;