@valbuild/next 0.67.0 → 0.68.0

package/README.md

@@ -50,7 +50,7 @@ This version of Val is currently an alpha version - the API can be considered re
   - [String](#string)
   - [Number](#number)
   - [Boolean](#boolean)
-  - [Optional](#optional)
+  - [Nullable](#nullable)
   - [Array](#array)
   - [Record](#record)
   - [Object](#object)
@@ -60,7 +60,7 @@ This version of Val is currently an alpha version - the API can be considered re
 
 ## Installation
 
-- Make sure you have TypeScript 5+, Next 13.4+ (other meta frameworks will come), React 18.20.+ (other frontend frameworks will come)
+- Make sure you have TypeScript 5+, Next 14+, React 18.20.+
 - Install the packages (@valbuild/eslint-plugin is recommended but not required):
 
 ```sh
@@ -73,146 +73,136 @@ npm install @valbuild/core@latest @valbuild/next@latest @valbuild/eslint-plugin@
 npx @valbuild/init@latest
 ```
 
-### Online mode
+## Getting started
 
-To make it possible to do online edits directly in your app, head over to [val.build](https://app.val.build), sign up and import your repository.
+### Create your first Val content file
 
-**NOTE**: your content is yours. No subscription (or similar) is required to host content from your repository.
+Content in Val is always defined in `.val.ts` (or `.js`) files.
 
-If you do not need to edit content online (i.e. not locally), you do not need to sign up.
+**NOTE**: the init script will generate an example Val content file (unless you opt out of it).
 
-**WHY**: to update your code, we need to create a commit. This requires a server. We opted to create a service that does this easily, instead of having a self-hosted alternative, since time spent is money used. Also, the company behind [val.build](https://val.build) is the company that funds the development of this software.
+Val content files are _evaluated_ by Val, therefore they need to abide a set of requirements.
+If you use the eslint plugins these requirements will be enforced. You can also validate val files using the @valbuild/cli: `npx -p @valbuild/cli val validate`.
 
-#### Online mode configuration
+For reference these requirements are:
 
-Once you have setup your project in [val.build](https://app.val.build), you must configure your application to use this project.
+- they must export a default content definition (`c.define`) where the first argument equals the path of the file relative to the `val.config` file; and
+- they must be declared in the `val.modules` file; and
+- they must have a default export that is `c.define`; and
+- they can only import Val related files or types (using `import type { MyType } from "./otherModule.ts"`)
 
-To do this, you must set the following environment variables:
+### Val content file example
 
-- `VAL_API_KEY`: you get this in your project configuration page.
-- `VAL_SECRET`: this is a random secret you can generate. It is used for communication between the UX client and your Next.js application.
+```ts
+// ./examples/val/example.val.ts
+import { s /* s = schema */, c /* c = content */ } from "../../val.config";
 
-In addition, you need to set the following properties in the `val.config` file:
+/**
+ * This is the schema for the content. It defines the structure of the content and the types of each field.
+ */
+export const schema = s.object({
+  /**
+   * Basic text field
+   */
+  text: s.string(),
+});
 
-- project: This is the fully qualified name of your project. It should look like this: `<team>/<name>`.
-- gitBranch: This is the git branch your application is using. In Vercel you can use: `VERCEL_GIT_COMMIT_REF`.
-- gitCommit: This is the current git commit your application is running on. In Vercel you can use: `VERCEL_GIT_COMMIT_SHA`
+/**
+ * This is the content definition. Add your content below.
+ *
+ * NOTE: the first argument is the path of the file.
+ */
+export default c.define("/examples/val/example.val.ts", schema, {
+  text: "Basic text content",
+});
+```
 
-Example of `val.config.ts`:
+### The `val.modules` file
+
+Once you have created your Val content file, it must be declared in the `val.modules.ts` (or `.js`) file in the project root folder.
+
+Example:
 
 ```ts
-import { initVal } from "@valbuild/next";
+import { modules } from "@valbuild/next";
+import { config } from "./val.config";
 
-const { s, c, val, config } = initVal({
-  project: "myteam/myproject",
-  gitBranch: process.env.VERCEL_GIT_COMMIT_REF,
-  gitCommit: process.env.VERCEL_GIT_COMMIT_SHA,
-});
+export default modules(config, [
+  // Add your modules here
+  { def: () => import("./examples/val/example.val") },
+]);
+```
 
-export type { t } from "@valbuild/next";
-export { s, c, val, config };
+### Using Val in Client Components
+
+In client components you can access your content with the `useVal` hook:
+
+```tsx
+// ./app/page.tsx
+"use client";
+import { useVal } from "../val/val.client";
+import exampleVal from "../examples/val/example.val";
+
+export default function Home() {
+  const { text } = useVal(exampleVal);
+  return <main>{text}</main>;
+}
 ```
 
-## Getting started
+### Using Val in React Server Components
 
-### Create your first Val content file
+In React Server components you can access your content with the `fetchVal` function:
 
-Content in Val is always defined in `.val.ts` files.
+```tsx
+// ./app/page.tsx
+"use server";
+import { fetchVal } from "../val/val.rsc";
+import exampleVal from "../examples/val/example.val";
+
+export default async function Home() {
+  const { text } = await fetchVal(exampleVal);
+  return <main>{text}</main>;
+}
+```
 
-**NOTE**: Val also works with `.js` files.
+# Remote Mode
 
-They must export a default content definition (`c.define`) where the first argument equals the path of the file relative to the `val.config.ts` file.
+Enable remote mode to allow editors to update content online (outside of local development) by creating a project at [app.val.build](https://app.val.build).
 
-**NOTE**: `val.ts` files are _evaluated_ by Val, therefore they have a specific set of requirements:
+**NOTE**: Your content remains yours. Hosting content from your repository does not require a subscription. However, to edit content online, a subscription is needed — unless your project is a public repository or qualifies for the free tier. Visit the [pricing page](https://val.build/pricing) for details.
 
-- They must have a default export that is `c.define`, they must have a `export const schema` with the Schema; and
-- they CANNOT import anything other than `val.config` and `@valbuild/core`
+**WHY**: Updating code involves creating a commit, which requires a server. We offer a hosted service for simplicity and efficiency, as self-hosted solutions takes time to setup and maintain. Additionally, the [val.build](https://val.build) team funds the ongoing development of this library.
 
-### Example of a `.val.ts` file
+## Remote Mode Configuration
 
-```ts
-// ./src/app/content.val.ts
+Once your project is set up in [app.val.build](https://app.val.build), configure your application to use it by setting the following:
 
-import { s, c } from "../../../val.config";
+### Environment Variables
 
-export const schema = s.object({
-  title: s.string().optional(), //  <- NOTE: optional()
-  sections: s.array(
-    s.object({
-      title: s.string(),
-      text: s.richtext({
-        style: {
-          bold: true, // <- Enables bold in richtext
-        },
-      }),
-    }),
-  ),
-});
+- **`VAL_API_KEY`**: Obtain this from your project's configuration page.
+- **`VAL_SECRET`**: Generate a random secret to secure communication between the UX client and your Next.js application.
 
-export default c.define(
-  "/src/app/content", // <- NOTE: this must be the same path as the file
-  schema,
-  {
-    title: "My Page",
-    sections: [
-      {
-        title: "Section 1",
-        text: [
-          {
-            tag: "p",
-            children: [
-              "Val is",
-              { tag: "span", styles: ["bold"], children: ["awesome"] },
-            ],
-          },
-        ],
-      },
-    ],
-  },
-);
-```
+### `val.config` Properties
 
-### Use your content
+Set these properties in the `val.config` file:
 
-In client components you can access your content with the `useVal` hook:
+- **`project`**: The fully qualified name of your project, formatted as `<team>/<name>`.
+- **`gitBranch`**: The Git branch your application uses. For Vercel, use `VERCEL_GIT_COMMIT_REF`.
+- **`gitCommit`**: The current Git commit your application is running on. For Vercel, use `VERCEL_GIT_COMMIT_SHA`.
 
-**NOTE**: Support for React Server Components and server side rendering will come soon.
+### Example `val.config.ts`
 
-```tsx
-// ./src/app/page.tsx
-"use client";
-import { NextPage } from "next";
-import { useVal } from "./val/val.client";
-import contentVal from "./content.val";
+```ts
+import { initVal } from "@valbuild/next";
 
-const Page: NextPage = () => {
-  const { title, sections } = useVal(contentVal);
-  return (
-    <main>
-      {title && (
-        <section>
-          <h1>{title}</h1>
-        </section>
-      )}
-      {sections.map((section) => (
-        <section>
-          <h2>{section.title}</h2>
-          <ValRichText
-            theme={{
-              style: {
-                bold: "font-bold",
-              },
-            }}
-          >
-            {section.text}
-          </ValRichText>
-        </section>
-      ))}
-    </main>
-  );
-};
+const { s, c, val, config } = initVal({
+  project: "myteam/myproject",
+  gitBranch: process.env.VERCEL_GIT_COMMIT_REF,
+  gitCommit: process.env.VERCEL_GIT_COMMIT_SHA,
+});
 
-export default Page;
+export type { t } from "@valbuild/next";
+export { s, c, val, config };
 ```
 
 # Schema types
@@ -241,14 +231,14 @@ import { s } from "./val.config";
 s.boolean(); // <- Schema<boolean>
 ```
 
-## Optional
+## Nullable
 
-All schema types can be optional. An optional schema creates a union of the type and `null`.
+All schema types can be nullable (optional). A nullable schema creates a union of the type and `null`.
 
 ```ts
 import { s } from "./val.config";
 
-s.string().optional(); // <- Schema<string | null>
+s.string().nullable(); // <- Schema<string | null>
 ```
 
 ## Array
@@ -384,7 +374,7 @@ To add classes to `ValRichText` you can use the theme property:
 </ValRichText>
 ```
 
-**NOTE**: if a theme is defined, you must define a mapping for every tag that the you get. What tags you have is decided based on the `options` defined on the `s.richtext()` schema. For example: `s.richtext({ headings: ["h1"]; bold: true; img: true})` forces you to map the class for at least: `h1`, `bold` and `img`:
+**NOTE**: if a theme is defined, you must define a mapping for every tag that the you get. What tags you have is decided based on the `options` defined on the `s.richtext()` schema. For example: `s.richtext({ style: { bold: true } })` requires that you add a `bold` theme.
 
 ```tsx
 <ValRichText
@@ -394,7 +384,7 @@ To add classes to `ValRichText` you can use the theme property:
     img: null, // either a string or null is required
   }}
 >
-  {content satisfies RichText<{ headings: ["h1"]; bold: true; img: true }>}
+  {content}
 </ValRichText>
 ```
 
@@ -404,7 +394,7 @@ To add classes to `ValRichText` you can use the theme property:
 
 Vals `RichText` type maps RichText 1-to-1 with semantic HTML5.
 
-If you want to customize the type of elements which are rendered, you can use the `transform` property.
+If you want to customize / override the type of elements which are rendered, you can use the `transform` property.
 
 ```tsx
 <ValRichText
@@ -525,9 +515,9 @@ The `ValImage` component is a wrapper around `next/image` that accepts a Val `Im
 You can use it like this:
 
 ```tsx
-const content = useVal(contentVal);
+const content = useVal(contentVal); // schema of contentVal: s.object({ image: s.image() })
 
-return <ValImage src={content.image} alt={content.alt} />;
+return <ValImage src={content.image} />;
 ```
 
 ### Using images in components
@@ -585,7 +575,22 @@ s.union(
 
 ## KeyOf
 
-If you need to reference content in another `.val` file you can use the `keyOf` schema.
+You can use `keyOf` to reference a key in a record of a Val module.
+
+**NOTE**: currently you must reference keys in Val modules, you cannot reference keys of values nested inside a Val module. This is a feature on the roadmap.
+
+```ts
+const schema = s.record(s.object({ nested: s.record(s.string()) }));
+
+export default c.define("/keyof.val.ts", schema, {
+  "you-can-reference-me": {
+    // <- this can be referenced
+    nested: {
+      "but-not-me": ":(", // <- this cannot be referenced
+    },
+  },
+});
+```
 
 ### KeyOf Schema
 

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

@@ -1,3 +1,4 @@
+/// <reference types="react" />
 import NextImage from "next/image";
 import { Image } from "@valbuild/react/stega";
 export type ValImageProps = Omit<React.ComponentProps<typeof NextImage>, "src" | "alt" | "srcset" | "layout" | "objectFit" | "objectPosition" | "lazyBoundary" | "lazyRoot"> & {

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

@@ -1,5 +1,6 @@
+/// <reference types="react" />
 export declare const ValProvider: (props: {
-    children: React.ReactNode | React.ReactNode[];
+    children: import("react").ReactNode | import("react").ReactNode[];
     config: import("@valbuild/core").ValConfig;
-    disableRefresh?: boolean;
+    disableRefresh?: boolean | undefined;
 }) => import("react/jsx-runtime").JSX.Element;

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

@@ -44,30 +44,7 @@ export declare const Internal: {
         [k: string]: string;
     };
     ModuleFilePathSep: string;
-    notFileOp: (op: import("@valbuild/core/patch").Operation) => op is {
-        op: "add";
-        path: string[];
-        value: import("@valbuild/core/dist/declarations/src/patch").JSONValue;
-    } | {
-        op: "remove";
-        path: import("@valbuild/core/dist/declarations/src/fp/array").NonEmptyArray<string>;
-    } | {
-        op: "replace";
-        path: string[];
-        value: import("@valbuild/core/dist/declarations/src/patch").JSONValue;
-    } | {
-        op: "move";
-        from: import("@valbuild/core/dist/declarations/src/fp/array").NonEmptyArray<string>;
-        path: string[];
-    } | {
-        op: "copy";
-        from: string[];
-        path: string[];
-    } | {
-        op: "test";
-        path: string[];
-        value: import("@valbuild/core/dist/declarations/src/patch").JSONValue;
-    };
+    notFileOp: (op: import("@valbuild/core/patch").Operation) => boolean;
     isFileOp: (op: import("@valbuild/core/patch").Operation) => op is {
         op: "file";
         path: string[];

package/dist/declarations/src/rsc/initValRsc.d.ts

@@ -9,7 +9,7 @@ declare const initFetchValStega: (config: ValConfig, valApiEndpoints: string, va
         name: string;
         value: string;
     } | undefined;
-}>) => <T extends SelectorSource>(selector: T) => Promise<SelectorOf<T> extends GenericSelector<infer S> ? StegaOfSource<S> : never>;
+}>) => <T extends SelectorSource>(selector: T) => Promise<SelectorOf<T> extends GenericSelector<infer S extends import("@valbuild/core").Source, undefined> ? StegaOfSource<S> : never>;
 type ValNextRscConfig = {
     draftMode: typeof draftMode;
     headers: typeof headers;

package/dist/declarations/src/server/initValServer.d.ts

@@ -2,7 +2,7 @@ import { ValConfig, ValModules } from "@valbuild/core";
 import type { draftMode } from "next/headers";
 import { NextResponse } from "next/server";
 declare const initValNextAppRouter: (valModules: ValModules, config: ValConfig, nextConfig: ValServerNextConfig & {
-    formatter?: (code: string, filePath: string) => Promise<string> | string;
+    formatter?: ((code: string, filePath: string) => Promise<string> | string) | undefined;
 }) => (req: Request) => Promise<NextResponse<unknown>>;
 type ValServerNextConfig = {
     draftMode: typeof draftMode;

package/package.json

@@ -8,7 +8,7 @@
     "next",
     "react"
   ],
-  "version": "0.67.0",
+  "version": "0.68.0",
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "jest"
@@ -45,11 +45,11 @@
     "exports": true
   },
   "dependencies": {
-    "@valbuild/core": "~0.67.0",
-    "@valbuild/react": "~0.67.0",
-    "@valbuild/server": "~0.67.0",
-    "@valbuild/shared": "~0.67.0",
-    "@valbuild/ui": "~0.67.0",
+    "@valbuild/core": "~0.68.0",
+    "@valbuild/react": "~0.68.0",
+    "@valbuild/server": "~0.68.0",
+    "@valbuild/shared": "~0.68.0",
+    "@valbuild/ui": "~0.68.0",
     "client-only": "^0.0.1",
     "server-only": "^0.0.1"
   },

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

@@ -80,7 +80,7 @@ var initFetchValStega = function initFetchValStega(config, valApiEndpoints, valS
             case 38:
               valServer = _context.sent;
               _context.next = 41;
-              return valServer["/patches/~"]["GET"]({
+              return valServer["/patches"]["GET"]({
                 query: {
                   omit_patch: true,
                   author: undefined,
@@ -99,7 +99,7 @@ var initFetchValStega = function initFetchValStega(config, valApiEndpoints, valS
             case 44:
               allPatches = Object.keys(patchesRes.json.patches);
               _context.next = 47;
-              return valServer["/sources"]["PUT"]({
+              return valServer["/sources/~"]["PUT"]({
                 path: "/",
                 query: {
                   validate_sources: true,

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

@@ -80,7 +80,7 @@ var initFetchValStega = function initFetchValStega(config, valApiEndpoints, valS
             case 38:
               valServer = _context.sent;
               _context.next = 41;
-              return valServer["/patches/~"]["GET"]({
+              return valServer["/patches"]["GET"]({
                 query: {
                   omit_patch: true,
                   author: undefined,
@@ -99,7 +99,7 @@ var initFetchValStega = function initFetchValStega(config, valApiEndpoints, valS
             case 44:
               allPatches = Object.keys(patchesRes.json.patches);
               _context.next = 47;
-              return valServer["/sources"]["PUT"]({
+              return valServer["/sources/~"]["PUT"]({
                 path: "/",
                 query: {
                   validate_sources: true,

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

@@ -76,7 +76,7 @@ var initFetchValStega = function initFetchValStega(config, valApiEndpoints, valS
             case 38:
               valServer = _context.sent;
               _context.next = 41;
-              return valServer["/patches/~"]["GET"]({
+              return valServer["/patches"]["GET"]({
                 query: {
                   omit_patch: true,
                   author: undefined,
@@ -95,7 +95,7 @@ var initFetchValStega = function initFetchValStega(config, valApiEndpoints, valS
             case 44:
               allPatches = Object.keys(patchesRes.json.patches);
               _context.next = 47;
-              return valServer["/sources"]["PUT"]({
+              return valServer["/sources/~"]["PUT"]({
                 path: "/",
                 query: {
                   validate_sources: true,