@valbuild/tanstack 0.125.0 → 0.126.0

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # @valbuild/tanstack
 
+## 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
 
 ### Minor Changes

package/README.md

@@ -374,7 +374,7 @@ SDK of your choice. See [`@valbuild/mcp`](https://www.npmjs.com/package/@valbuil
 ## Schema reference
 
 The schema types — `s.string()`, `s.richtext()`, `s.image()`, `s.record()`,
-`s.union()`, `s.keyOf()`, `s.route()`, and the rest — are the same in every Val
+`s.discriminatedUnion()`, `s.keyOf()`, `s.route()`, and the rest — are the same in every Val
 package and are documented in full at
 [val.build/docs](https://val.build/docs) and in
 [`@valbuild/next`'s README](https://github.com/valbuild/val/blob/main/packages/next/README.md#schema-types).

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

@@ -20,6 +20,10 @@ export declare const initVal: (config?: ValConfig) => InitVal & {
      *
      * 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 function, a server route handler, or during SSR:
+     * const enabled = await isValEnabled();
      */
     isValEnabled: typeof isValEnabled;
     val: ValConstructor & {
@@ -34,10 +38,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;
         /**
@@ -46,12 +62,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;
     };
     /**
@@ -69,6 +103,21 @@ export declare const initVal: (config?: ValConfig) => InitVal & {
      * });
      */
     tanstackRouter: 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-tanstack.cjs.dev.js

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var version = require('./version-6eeefb70.cjs.dev.js');
+var version = require('./version-1a220586.cjs.dev.js');
 var createForOfIteratorHelper = require('./createForOfIteratorHelper-e75681d7.cjs.dev.js');
 var core = require('@valbuild/core');
 var stega = require('@valbuild/react/stega');

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

@@ -2,7 +2,7 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-var version = require('./version-803e9fd4.cjs.prod.js');
+var version = require('./version-1837c67c.cjs.prod.js');
 var createForOfIteratorHelper = require('./createForOfIteratorHelper-0324e063.cjs.prod.js');
 var core = require('@valbuild/core');
 var stega = require('@valbuild/react/stega');

package/dist/valbuild-tanstack.esm.js

@@ -1,4 +1,4 @@
-import { _ as _asyncToGenerator, a as _regenerator, V as VERSION$1 } from './version-9b3ce6c3.esm.js';
+import { _ as _asyncToGenerator, a as _regenerator, V as VERSION$1 } from './version-a7a1374a.esm.js';
 import { _ as _objectSpread2, a as _slicedToArray, b as _createForOfIteratorHelper } from './createForOfIteratorHelper-485c2ce1.esm.js';
 import { Internal as Internal$1, initVal as initVal$1, DEFAULT_CONTENT_HOST } from '@valbuild/core';
 import * as core from '@valbuild/core';

package/dist/{version-6eeefb70.cjs.dev.js → version-1837c67c.cjs.prod.js}

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

package/dist/{version-803e9fd4.cjs.prod.js → version-1a220586.cjs.dev.js}

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

package/dist/{version-9b3ce6c3.esm.js → version-a7a1374a.esm.js}

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

package/package.json

@@ -14,7 +14,7 @@
     "tanstack-router",
     "react"
   ],
-  "version": "0.125.0",
+  "version": "0.126.0",
   "main": "dist/valbuild-tanstack.cjs.js",
   "module": "dist/valbuild-tanstack.esm.js",
   "exports": {
@@ -42,13 +42,13 @@
     "exports": true
   },
   "dependencies": {
-    "@valbuild/core": "0.125.0",
-    "@valbuild/language-server": "0.125.0",
-    "@valbuild/mcp": "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/mcp": "0.126.0",
+    "@valbuild/react": "0.126.0",
+    "@valbuild/shared": "0.126.0",
+    "@valbuild/server": "0.126.0",
+    "@valbuild/ui": "0.126.0"
   },
   "devDependencies": {
     "@tanstack/react-router": "^1.170.33",

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

@@ -5,7 +5,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 var createForOfIteratorHelper = require('../../dist/createForOfIteratorHelper-e75681d7.cjs.dev.js');
 var core = require('@valbuild/core');
 var server = require('@valbuild/server');
-var version = require('../../dist/version-6eeefb70.cjs.dev.js');
+var version = require('../../dist/version-1a220586.cjs.dev.js');
 var routeFromVal = require('../../dist/routeFromVal-a9147ceb.cjs.dev.js');
 var stega = require('@valbuild/react/stega');
 var internal = require('@valbuild/shared/internal');

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

@@ -5,7 +5,7 @@ Object.defineProperty(exports, '__esModule', { value: true });
 var createForOfIteratorHelper = require('../../dist/createForOfIteratorHelper-0324e063.cjs.prod.js');
 var core = require('@valbuild/core');
 var server = require('@valbuild/server');
-var version = require('../../dist/version-803e9fd4.cjs.prod.js');
+var version = require('../../dist/version-1837c67c.cjs.prod.js');
 var routeFromVal = require('../../dist/routeFromVal-6693e037.cjs.prod.js');
 var stega = require('@valbuild/react/stega');
 var internal = require('@valbuild/shared/internal');

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

@@ -1,7 +1,7 @@
 import { _ as _objectSpread2, a as _slicedToArray, d as _defineProperty } from '../../dist/createForOfIteratorHelper-485c2ce1.esm.js';
 import { Internal } from '@valbuild/core';
 import { createValApiRouter, createValServer } from '@valbuild/server';
-import { _ as _asyncToGenerator, a as _regenerator, V as VERSION } from '../../dist/version-9b3ce6c3.esm.js';
+import { _ as _asyncToGenerator, a as _regenerator, V as VERSION } from '../../dist/version-a7a1374a.esm.js';
 import { b as initValRouteFromVal, g as getJsonEntryStegaRoot, i as isJsonValuesRecordSchema, a as getValRouteUrlFromVal, _ as _typeof } from '../../dist/routeFromVal-728295a0.esm.js';
 import { stegaEncode, SET_AUTO_TAG_JSX_ENABLED } from '@valbuild/react/stega';
 import { VAL_SESSION_COOKIE } from '@valbuild/shared/internal';