@valbuild/next 0.125.0 → 0.126.0

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # @valbuild/next
 
+## 0.126.0
+
+### Patch Changes
+
+- [#652](https://github.com/valbuild/val/pull/652) [`f2fe70d`](https://github.com/valbuild/val/commit/f2fe70dab2b65000dfaf289f09c70b4a8291467a) Thanks [@freekh](https://github.com/freekh)! - `s.union` is now `s.discriminatedUnion` and `s.enum`.
+
+  `s.union` did two unrelated jobs and worked out which one you meant from its
+  first argument: a string key meant a tagged union of objects, literal schemas
+  meant a set of allowed strings. Those are now two schemas with two names.
+
+  ```ts
+  // A fixed set of strings — presents as a dropdown
+  s.enum("primary", "secondary", "ghost"); // Schema<"primary" | "secondary" | "ghost">
+
+  // One of several object shapes, told apart by a tag field
+  s.discriminatedUnion(
+    "type",
+    s.object({ type: s.literal("hero"), heading: s.string() }),
+    s.object({ type: s.literal("quote"), text: s.string() }),
+  );
+  ```
+
+  `s.enum` takes the strings directly, so the `s.literal(...)` wrapper is gone.
+
+  **`s.union` still works** — it is deprecated, and it builds exactly the schema
+  above, so nothing has to change today:
+
+  ```ts
+  s.union(s.literal("one"), s.literal("two")); // → s.enum("one", "two")
+  s.union("type", pageA, pageB); // → s.discriminatedUnion("type", pageA, pageB)
+  ```
+
+  The two are different kinds of node, and that is the reason for the split. A
+  discriminated union is a container: the selected variant's fields are the fields
+  being edited, and everything that walks a schema descends through it. An enum is
+  a leaf — a string with a closed domain — so nothing recurses into it. Told apart
+  only by the shape of `key`, every consumer had to re-derive which one it was
+  holding; each now has its own serialized type (`"discriminated-union"` and
+  `"enum"`) and Val Studio has a field per kind rather than one field that
+  branches.
+
+  Two behaviour changes fall out of the split, both of them fixes:
+
+  - A value that is not a string at all now fails an enum's validation with a
+    type error. `s.union` of literals only ever checked the value against its
+    literals when the value WAS a string, so a number or an object where an enum
+    was declared validated clean.
+  - An enum field now shows its validation errors in Val Studio where the field
+    is opened on its own — the module editor and the canvas's fields column — and
+    gets the compact error layout inside an inline list row. It is a leaf now, so
+    it goes through the same error rendering as every other leaf field; the string
+    union bypassed it and showed nothing in those places.
+
+  Several latent crashes in the old `s.union` are fixed on the way past, all of
+  them cases where it threw a `TypeError` instead of reporting:
+
+  - A required discriminated union holding `null` now reports a type error rather
+    than throwing, and resolving a path underneath a nullable one that is `null`
+    gives the error the API promises instead of a crash.
+  - `s.literal("")` is a legal discriminator tag, and `s.enum("")` a legal value.
+    Both used to be treated as absent by a truthiness check — in path resolution,
+    in stega encoding, and in the message that lists a union's valid tags. The
+    editor's dropdowns handle them too: an empty value is reserved by the select
+    component and had to be mapped around.
+  - A variant that omits the discriminator entirely is now reported as the schema
+    error it is, instead of throwing while the check looked for it.
+  - An enum's value is now indexed for search, like every other string leaf. The
+    old string union was never indexed at all, so searching for one of its values
+    could not find the field.
+  - A nullable discriminated union set to `null` no longer renders a spinner that
+    never resolves.
+
+  `s.discriminatedUnion` also requires at least one variant, as `s.enum` requires
+  at least one value: a union with nothing to select is not a thing to write, and
+  everything downstream reads the first variant where it needs any.
+
+  If you read serialized schemas yourself, that is the breaking part: `type` is no
+  longer `"union"`, an enum carries `values: string[]` instead of a `key` plus
+  `items` of literal schemas, and `UnionSchema` is no longer a class.
+  `SerializedUnionSchema`, `SerializedStringUnionSchema`,
+  `SerializedObjectUnionSchema` and `UnionSchema` remain as deprecated type
+  aliases.
+
+- [#661](https://github.com/valbuild/val/pull/661) [`171208a`](https://github.com/valbuild/val/commit/171208a20177e68ed5a8b1a6fdaabfe893a6aa5f) Thanks [@freekh](https://github.com/freekh)! - Every schema method now has a worked `@example` in its JSDoc, so hovering it in
+  your editor shows what to write.
+
+  That covers the whole builder surface — `.describe()`, `.validate()`,
+  `.nullable()`, `.readonly()`, `.hidden()`, `.preview()`, `.render()`, and the
+  per-type methods such as `.minLength()`, `.regexp()`, `.raw()`, `.multiline()`,
+  `.from()` / `.to()`, `.remote()`, `.jsonValues()` and `.external()` — as well as
+  `c.define()`, `c.json()`, `c.external()` and the `val` helpers (`val.attrs`,
+  `val.raw`, `val.unstable_getPath` and friends).
+
+  One of the examples corrected a real trap: a custom validator returns
+  `false | string`, so the natural-looking
+
+  ```ts
+  s.string().validate((val) => val.trim() === val || "No surrounding spaces");
+  ```
+
+  does not type check — `||` yields `true`, and `true` is not one of the two
+  answers. Write it as a ternary instead:
+
+  ```ts
+  s.string().validate((val) =>
+    val.trim() === val ? false : "No surrounding spaces",
+  );
+  ```
+
+  The examples are checked in CI, not just written: one test asks the TypeScript
+  checker for the doc each method actually resolves to and fails if it has no
+  `@example`, and another compiles every example it finds.
+
+- Updated dependencies [[`719ad6b`](https://github.com/valbuild/val/commit/719ad6b607bcf136d0dbde9e90bf4b8a843561a4), [`9830277`](https://github.com/valbuild/val/commit/9830277e9aaca8da3030f629c2656ec58da47e45), [`64bfd0a`](https://github.com/valbuild/val/commit/64bfd0a6c85832ea5169b53e47087f22e193df36), [`7782979`](https://github.com/valbuild/val/commit/7782979e9b52f2015a6e72dc981e630d4f8c78e2), [`5bfd630`](https://github.com/valbuild/val/commit/5bfd630b63dee2189e238f20fe72ecc5537160f7), [`ccbcda6`](https://github.com/valbuild/val/commit/ccbcda60b3e3c465071229ae1ba28ac735483e63), [`f2fe70d`](https://github.com/valbuild/val/commit/f2fe70dab2b65000dfaf289f09c70b4a8291467a), [`5c18c99`](https://github.com/valbuild/val/commit/5c18c99ecc84651f82123481fc042063db953833), [`755e1a3`](https://github.com/valbuild/val/commit/755e1a3953775cb8d2c2dce87d6810d3dc329640), [`c6b1ec8`](https://github.com/valbuild/val/commit/c6b1ec84f1883750a4cfe5f70470b177621e971f), [`656f680`](https://github.com/valbuild/val/commit/656f680043c640f678625a64e690389ab23a0a69), [`610a041`](https://github.com/valbuild/val/commit/610a0414b120b521f38a2eb1182b3778bf778b2b), [`171208a`](https://github.com/valbuild/val/commit/171208a20177e68ed5a8b1a6fdaabfe893a6aa5f)]:
+  - @valbuild/ui@0.126.0
+  - @valbuild/shared@0.126.0
+  - @valbuild/server@0.126.0
+  - @valbuild/core@0.126.0
+  - @valbuild/react@0.126.0
+  - @valbuild/language-server@0.126.0
+  - @valbuild/mcp@0.126.0
+
 ## 0.125.0
 
 ### Patch Changes

package/README.md

@@ -571,7 +571,7 @@ const sectionsSchema = s.array(
 );
 ```
 
-A tagged union with no preview of its own previews as the VARIANT the value
+A discriminated union with no preview of its own previews as the VARIANT the value
 takes, so a page-builder list previews each block by its own block type.
 
 Your function is run on demand, for the rows actually on screen, so it is fine
@@ -909,20 +909,16 @@ const image = useVal(imageVal);
 return <img src={image.url} />;
 ```
 
-## Union
+## Discriminated Union
 
-The union schema can be used to create either "tagged unions" or a union of string literals.
+A discriminated union is a union of objects which all have the same field (of the same type). This field determines (or "discriminates") which of the union's types a value is.
 
-### Union Schema tagged unions
-
-A tagged union is a union of objects which all have the same field (of the same type). This field can be used to determine (or "discriminate") the exact type of one of the types of the union.
-
-It is useful when editors should be able to chose from a set of objects that are different.
+It is useful when editors should be able to choose from a set of objects that are different.
 
 Example: let us say you have a page that can be one of the following: blog (page) or product (page). In this case your schema could look like this:
 
 ```ts
-s.union(
+s.discriminatedUnion(
   "type", // the key of the "discriminator"
   s.object({
     type: s.literal("blogPage"), // <- each type must have a UNIQUE value
@@ -937,16 +933,23 @@ s.union(
 ); // <- Schema<{ type: "blogPage", author: string } | { type: "productPage", sku: number }>
 ```
 
-## Union Schema: union of string literals
+## Enum
+
+Use `s.enum` for a fixed set of strings. It gives you a type-safe way to describe the valid values an editor can choose from, and it presents as a dropdown in Val Studio.
+
+```ts
+s.enum("one", "two"); // <- Schema<"one" | "two">
+```
+
+### `s.union` is deprecated
 
-You can also use a union to create a union of string literals. This is useful if you want a type-safe way to describe a set of valid strings that can be chosen by an editor.
+`s.union` did both of these jobs, deciding which one you meant from its first
+argument. It still works, and produces exactly the schemas above, but name the
+one you mean instead:
 
 ```ts
-s.union(
-  s.literal("one"),
-  s.literal("two"),
-  //...
-); // <- Schema<"one" | "two">
+s.union(s.literal("one"), s.literal("two")); // -> s.enum("one", "two")
+s.union("type", pageA, pageB); // -> s.discriminatedUnion("type", pageA, pageB)
 ```
 
 ## KeyOf

package/dist/declarations/src/initVal.d.ts

@@ -26,6 +26,10 @@ export declare const initVal: (config?: ValConfig) => InitVal & {
      * cache for every route it covers, for all visitors. It is NOT needed for
      * the `suspend` prop on ValProvider (which detects the cookie client-side)
      * — reserve it for advanced server-side conditionals.
+     *
+     * @example
+     * // In a Server Component, a Server Action or a Route Handler:
+     * const enabled = await isValEnabled();
      */
     isValEnabled: typeof isValEnabled;
     val: ValConstructor & {
@@ -40,10 +44,22 @@ export declare const initVal: (config?: ValConfig) => InitVal & {
          *
          * This method is primarily intended for tooling and other advanced use cases
          * outside of the actual application.
+         *
+         * @example
+         * import pageVal from "./page.val";
+         * const page = val.unstable_getUnpatchedUnencodedVal(pageVal);
          */
         unstable_getUnpatchedUnencodedVal: typeof getUnpatchedUnencodedVal;
         /**
          * Convert any object that is encoded with Val stega encoding back to the original values
+         *
+         * Use it wherever an encoded string would break something: a `key`, a
+         * comparison, a URL, anything sent to an API.
+         *
+         * @example
+         * import pageVal from "./page.val";
+         * const page = useVal(pageVal);
+         * const slug = val.raw(page.slug);
          */
         raw: typeof raw;
         /**
@@ -52,12 +68,30 @@ export declare const initVal: (config?: ValConfig) => InitVal & {
          * This is typically used to manually set the data-val-path attribute for visual editing on any element.
          *
          * @example
-         * const page = useVal(pageVal)
-         * <a href={page.url.href} {...val.attrs(page)}>
-         *   {page.url.label}
-         * </a>
+         * import pageVal from "./page.val";
+         * function PageLink() {
+         *   const page = useVal(pageVal);
+         *   return (
+         *     <a href={page.url.href} {...val.attrs(page)}>
+         *       {page.url.label}
+         *     </a>
+         *   );
+         * }
          */
         attrs: typeof attrs;
+        /**
+         * The Val paths encoded into a single stega encoded string, or `undefined`
+         * when there are none.
+         *
+         * `val.attrs` is what an element usually wants; this is the lower-level
+         * read, for when you need the paths themselves. Unstable: the shape of a
+         * path is not part of the public API yet.
+         *
+         * @example
+         * import pageVal from "./page.val";
+         * const page = useVal(pageVal);
+         * const paths = val.unstable_decodeValPathsOfString(page.title);
+         */
         unstable_decodeValPathsOfString: typeof decodeValPathsOfString;
     };
     /**
@@ -73,6 +107,21 @@ export declare const initVal: (config?: ValConfig) => InitVal & {
      * });
      */
     nextAppRouter: ValRouter;
+    /**
+     * A router for pages that are NOT in this application: the keys of the record
+     * are whole URLs, not route paths of your site.
+     *
+     * It is what `s.route()` links to when the destination is somewhere else -
+     * a campaign site, a docs host, a social profile.
+     *
+     * @example
+     * const links = s.record(s.object({ title: s.string() }));
+     * export default c.define(
+     *   "/content/external.val.ts",
+     *   links.router(externalPageRouter),
+     *   { "https://val.build": { title: "Val" } },
+     * );
+     */
     externalPageRouter: ValRouter;
 };
 export {};

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

@@ -12,7 +12,7 @@ var NextImage = require('next/image');
 var jsxRuntime = require('react/jsx-runtime');
 var ValApp = require('./ValApp-294e5b53.cjs.dev.js');
 var ValModulesClient = require('./ValModulesClient-4ecabf99.cjs.dev.js');
-var version = require('./version-4302babf.cjs.dev.js');
+var version = require('./version-7b12f65c.cjs.dev.js');
 var createForOfIteratorHelper = require('./createForOfIteratorHelper-0445603c.cjs.dev.js');
 require('./defineProperty-f90345d7.cjs.dev.js');
 require('./unsupportedIterableToArray-c8ab77c9.cjs.dev.js');

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

@@ -12,7 +12,7 @@ var NextImage = require('next/image');
 var jsxRuntime = require('react/jsx-runtime');
 var ValApp = require('./ValApp-ab8a96fd.cjs.prod.js');
 var ValModulesClient = require('./ValModulesClient-10c0721c.cjs.prod.js');
-var version = require('./version-eb9498d9.cjs.prod.js');
+var version = require('./version-ed4739ee.cjs.prod.js');
 var createForOfIteratorHelper = require('./createForOfIteratorHelper-d4afcad8.cjs.prod.js');
 require('./defineProperty-8951f469.cjs.prod.js');
 require('./unsupportedIterableToArray-0d2087a2.cjs.prod.js');

package/dist/valbuild-next.esm.js

@@ -11,7 +11,7 @@ import NextImage from 'next/image';
 import { jsx } from 'react/jsx-runtime';
 export { ValApp } from './ValApp-3a70afe1.esm.js';
 export { ValModulesClient, useRegisterValModules } from './ValModulesClient-0dd601a1.esm.js';
-import { V as VERSION } from './version-8ab79315.esm.js';
+import { V as VERSION } from './version-f8b10637.esm.js';
 import { _ as _createForOfIteratorHelper } from './createForOfIteratorHelper-5758a730.esm.js';
 import './defineProperty-cca5affa.esm.js';
 import './unsupportedIterableToArray-5baabfdc.esm.js';

package/dist/{version-4302babf.cjs.dev.js → version-7b12f65c.cjs.dev.js}

@@ -14,7 +14,7 @@ var packageJson = {
 		"next",
 		"react"
 	],
-	version: "0.125.0",
+	version: "0.126.0",
 	scripts: {
 		typecheck: "tsc --noEmit",
 		test: "jest"

package/dist/{version-eb9498d9.cjs.prod.js → version-ed4739ee.cjs.prod.js}

@@ -14,7 +14,7 @@ var packageJson = {
 		"next",
 		"react"
 	],
-	version: "0.125.0",
+	version: "0.126.0",
 	scripts: {
 		typecheck: "tsc --noEmit",
 		test: "jest"

package/dist/{version-8ab79315.esm.js → version-f8b10637.esm.js}

@@ -12,7 +12,7 @@ var packageJson = {
 		"next",
 		"react"
 	],
-	version: "0.125.0",
+	version: "0.126.0",
 	scripts: {
 		typecheck: "tsc --noEmit",
 		test: "jest"

package/package.json

@@ -12,7 +12,7 @@
     "next",
     "react"
   ],
-  "version": "0.125.0",
+  "version": "0.126.0",
   "main": "dist/valbuild-next.cjs.js",
   "module": "dist/valbuild-next.esm.js",
   "exports": {
@@ -47,13 +47,13 @@
   "dependencies": {
     "client-only": "^0.0.1",
     "server-only": "^0.0.1",
-    "@valbuild/core": "0.125.0",
-    "@valbuild/mcp": "0.125.0",
-    "@valbuild/language-server": "0.125.0",
-    "@valbuild/react": "0.125.0",
-    "@valbuild/server": "0.125.0",
-    "@valbuild/shared": "0.125.0",
-    "@valbuild/ui": "0.125.0"
+    "@valbuild/core": "0.126.0",
+    "@valbuild/language-server": "0.126.0",
+    "@valbuild/react": "0.126.0",
+    "@valbuild/mcp": "0.126.0",
+    "@valbuild/server": "0.126.0",
+    "@valbuild/shared": "0.126.0",
+    "@valbuild/ui": "0.126.0"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.3",

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

@@ -11,7 +11,7 @@ var stega = require('@valbuild/react/stega');
 var core = require('@valbuild/core');
 var internal = require('@valbuild/shared/internal');
 var server = require('@valbuild/server');
-var version = require('../../dist/version-4302babf.cjs.dev.js');
+var version = require('../../dist/version-7b12f65c.cjs.dev.js');
 require('../../dist/createForOfIteratorHelper-0445603c.cjs.dev.js');
 require('../../dist/unsupportedIterableToArray-c8ab77c9.cjs.dev.js');
 require('../../dist/slicedToArray-44036a76.cjs.dev.js');

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

@@ -11,7 +11,7 @@ var stega = require('@valbuild/react/stega');
 var core = require('@valbuild/core');
 var internal = require('@valbuild/shared/internal');
 var server = require('@valbuild/server');
-var version = require('../../dist/version-eb9498d9.cjs.prod.js');
+var version = require('../../dist/version-ed4739ee.cjs.prod.js');
 require('../../dist/createForOfIteratorHelper-d4afcad8.cjs.prod.js');
 require('../../dist/unsupportedIterableToArray-0d2087a2.cjs.prod.js');
 require('../../dist/slicedToArray-ce613de6.cjs.prod.js');

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

@@ -7,7 +7,7 @@ import { SET_RSC, stegaEncode, SET_AUTO_TAG_JSX_ENABLED } from '@valbuild/react/
 import { Internal } from '@valbuild/core';
 import { VAL_SESSION_COOKIE } from '@valbuild/shared/internal';
 import { createValServer } from '@valbuild/server';
-import { V as VERSION } from '../../dist/version-8ab79315.esm.js';
+import { V as VERSION } from '../../dist/version-f8b10637.esm.js';
 import '../../dist/createForOfIteratorHelper-5758a730.esm.js';
 import '../../dist/unsupportedIterableToArray-5baabfdc.esm.js';
 import '../../dist/slicedToArray-aa291011.esm.js';

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

@@ -9,7 +9,7 @@ var objectSpread2 = require('../../dist/objectSpread2-58024783.cjs.dev.js');
 var core = require('@valbuild/core');
 var server = require('@valbuild/server');
 var server$1 = require('next/server');
-var version = require('../../dist/version-4302babf.cjs.dev.js');
+var version = require('../../dist/version-7b12f65c.cjs.dev.js');
 var mcp = require('@valbuild/mcp');
 require('../../dist/unsupportedIterableToArray-c8ab77c9.cjs.dev.js');
 require('../../dist/defineProperty-f90345d7.cjs.dev.js');

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

@@ -9,7 +9,7 @@ var objectSpread2 = require('../../dist/objectSpread2-13f847a9.cjs.prod.js');
 var core = require('@valbuild/core');
 var server = require('@valbuild/server');
 var server$1 = require('next/server');
-var version = require('../../dist/version-eb9498d9.cjs.prod.js');
+var version = require('../../dist/version-ed4739ee.cjs.prod.js');
 var mcp = require('@valbuild/mcp');
 require('../../dist/unsupportedIterableToArray-0d2087a2.cjs.prod.js');
 require('../../dist/defineProperty-8951f469.cjs.prod.js');

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

@@ -5,7 +5,7 @@ import { _ as _objectSpread2 } from '../../dist/objectSpread2-60d1bd93.esm.js';
 import { Internal } from '@valbuild/core';
 import { createValApiRouter, createValServer } from '@valbuild/server';
 import { NextResponse } from 'next/server';
-import { V as VERSION } from '../../dist/version-8ab79315.esm.js';
+import { V as VERSION } from '../../dist/version-f8b10637.esm.js';
 import { initValMcp as initValMcp$1 } from '@valbuild/mcp';
 import '../../dist/unsupportedIterableToArray-5baabfdc.esm.js';
 import '../../dist/defineProperty-cca5affa.esm.js';