@valbuild/next 0.33.0 → 0.35.0

package/README.md

@@ -1,9 +1,40 @@
 <p align="center">
-  <h1 align="center">Val</h1>
   <p align="center">
-    ✨ <a href="https://app.val.build">https://app.val.build</a> ✨
+    <a href="https://app.val.build">
+<svg width="100" height="100" viewBox="0 0 944 944" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="472" cy="472" r="472" fill="#1D1C28"/>
+<g filter="url(#filter0_d_14_601)">
+<path d="M181 348C181 345.791 182.791 344 185 344H320C322.209 344 324 345.791 324 348V602C324 604.209 322.209 606 320 606H185C182.791 606 181 604.209 181 602V348Z" fill="#38CD80"/>
+</g>
+<g filter="url(#filter1_i_14_601)">
+<circle cx="252" cy="550" r="24" fill="#1E1F2A"/>
+</g>
+<path d="M659.085 550.374H658.585H654.427C652.095 550.374 650.434 549.729 649.347 548.522C648.25 547.306 647.658 545.431 647.658 542.807V439.857C647.658 437.924 646.091 436.357 644.158 436.357H629.16C627.227 436.357 625.66 437.924 625.66 439.857V455.828C625.66 456.658 624.986 457.332 624.155 457.332C623.593 457.332 623.072 457.015 622.798 456.508C618.502 448.559 612.704 442.661 605.399 438.838C597.962 434.671 589.622 432.592 580.394 432.592C571.897 432.592 563.846 434.128 556.247 437.2C548.643 440.274 541.944 444.796 536.154 450.761L536.153 450.761C530.537 456.552 526.106 463.693 522.854 472.174C519.598 480.668 517.975 490.411 517.975 501.395V505.697C517.975 516.86 519.597 526.693 522.854 535.187C526.105 543.667 530.535 550.895 536.148 556.864L536.153 556.869L536.159 556.875C541.95 562.659 548.647 567.088 556.246 570.161L556.256 570.165C563.856 573.057 572.083 574.5 580.932 574.5C589.456 574.5 597.527 572.325 605.137 567.982C612.625 563.807 618.519 557.469 622.822 548.992C623.085 548.475 623.609 548.147 624.176 548.147H624.546C625.161 548.147 625.66 548.646 625.66 549.261C625.66 555.468 627.583 560.617 631.452 564.665L631.451 564.665L631.46 564.673C635.511 568.72 640.668 570.735 646.889 570.735H658.585H659.085H661.157H661.657H760C761.933 570.735 763.5 569.168 763.5 567.235V553.874C763.5 551.941 761.933 550.374 760 550.374H733.542C732.161 550.374 731.042 549.255 731.042 547.874V385C731.042 383.067 729.475 381.5 727.542 381.5H680.701C678.768 381.5 677.201 383.067 677.201 385V398.361C677.201 400.294 678.768 401.861 680.701 401.861H706.543C707.924 401.861 709.043 402.981 709.043 404.361V547.874C709.043 549.255 707.924 550.374 706.543 550.374H661.657H661.157H659.085ZM600.117 550.146L600.111 550.149C594.977 552.448 589.304 553.601 583.086 553.601C570.468 553.601 560.194 549.435 552.222 541.12C544.436 532.633 540.512 520.847 540.512 505.697V501.395C540.512 494.274 541.581 487.79 543.712 481.936L543.714 481.931C545.849 475.89 548.778 470.842 552.495 466.775C556.398 462.521 560.92 459.246 566.061 456.944C571.195 454.645 576.867 453.492 583.086 453.492C589.117 453.492 594.696 454.731 599.829 457.207L599.838 457.211L599.848 457.215C605.166 459.517 609.681 462.79 613.4 467.035L613.4 467.035L613.408 467.044C617.306 471.292 620.324 476.431 622.458 482.469L622.459 482.474C624.59 488.328 625.66 494.812 625.66 501.933V505.16C625.66 512.46 624.59 519.125 622.458 525.159C620.324 531.022 617.393 536.075 613.669 540.326C609.95 544.571 605.435 547.844 600.117 550.146ZM464.902 570.735C466.39 570.735 467.716 569.794 468.206 568.389L512.685 441.011C513.479 438.736 511.79 436.357 509.38 436.357H491.006C489.496 436.357 488.157 437.325 487.683 438.758L447.951 558.864C447.716 559.575 447.051 560.055 446.303 560.055C445.554 560.055 444.89 559.575 444.655 558.864L404.923 438.758C404.449 437.325 403.109 436.357 401.6 436.357H383.225C380.815 436.357 379.126 438.736 379.921 441.011L424.399 568.389C424.89 569.794 426.215 570.735 427.704 570.735H464.902Z" fill="white" stroke="white"/>
+<defs>
+<filter id="filter0_d_14_601" x="127.464" y="290.464" width="250.072" height="369.072" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feOffset/>
+<feGaussianBlur stdDeviation="26.768"/>
+<feComposite in2="hardAlpha" operator="out"/>
+<feColorMatrix type="matrix" values="0 0 0 0 0.219608 0 0 0 0 0.803922 0 0 0 0 0.501961 0 0 0 0.3 0"/>
+<feBlend mode="normal" in2="BackgroundImageFix" result="effect1_dropShadow_14_601"/>
+<feBlend mode="normal" in="SourceGraphic" in2="effect1_dropShadow_14_601" result="shape"/>
+</filter>
+<filter id="filter1_i_14_601" x="228" y="526" width="48" height="48" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
+<feFlood flood-opacity="0" result="BackgroundImageFix"/>
+<feBlend mode="normal" in="SourceGraphic" in2="BackgroundImageFix" result="shape"/>
+<feColorMatrix in="SourceAlpha" type="matrix" values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0" result="hardAlpha"/>
+<feOffset/>
+<feGaussianBlur stdDeviation="6"/>
+<feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1"/>
+<feColorMatrix type="matrix" values="0 0 0 0 0.219608 0 0 0 0 0.803922 0 0 0 0 0.501961 0 0 0 0.3 0"/>
+<feBlend mode="normal" in2="shape" result="effect1_innerShadow_14_601"/>
+</filter>
+</defs>
+</svg>
+    </a>
     <br/>
-    hard-coded content - super-charged
   </p>
 </p>
 
@@ -11,57 +42,117 @@
 
 Val is PRE-ALPHA - MOST features are broken and in state of flux.
 
-This is released only for **INTERNAL** **TESTING** PURPOSES.
+This is release is only for **INTERNAL** **TESTING** PURPOSES.
 
 ## Table of contents
 
-- [Table of contents](#table-of-contents)
 - [Introduction](#introduction)
 - [Installation](#installation)
 - [Getting started](#getting-started)
-- [Concepts](#concepts)
-- [String](#string)
-- [Number](#number)
-- [Boolean](#boolean)
-- [Optional](#optional)
-- [Array](#array)
-- [Object](#object)
-- [Rich text](#richtext)
-- [Image](#image)
-- [Internalization](#internalization)
-- [Union](#union)
-- [One-of references](#one-of-references)
-- [Remote](#remote)
-- [Selector](#selector)
+- [Schema types](#schema-types):
+  - [String](#string)
+  - [Number](#number)
+  - [Boolean](#boolean)
+  - [Optional](#optional)
+  - [Array](#array)
+  - [Record](#record)
+  - [Object](#object)
+  - [Rich text](#richtext)
+  - [Image](#image)
+  - [keyOf](#keyof)
 
 ## Introduction
 
-Val treats your content as code, but it remains fully editable.
+Val is a CMS where **content** is **code** stored in your git repo.
 
-Val is built on top of TypeScript and Git, letting you use types, branches, version control (even rollbacks!) seamlessly.
+As a CMS, Val is useful because:
 
-- Val is **TypeSafe**: being TypeScript-first means you see errors as you type. In addition you can **refactor**, find references and auto-complete content - just as if it was hard-coded. Safety means no more "add-only" content models, where your content model continues to expand because you hesitate to remove anything.
+- editors can **change content** without having to ask developers to do it for them (and nobody wants that)
+- a **well-documented** way to **structure content**
+- **image** support is built-in
+- **richtext** support is built-in
+- built-in **visual editing** which lets editors click-then-edit content (and therefore **code**!) directly in your app
 
-- Version **control**: content is tied to commits, which means you can use branches and reverts just as you would normally do.
+  ![Visual editing](./docs/visual-editing.png)
 
-- Val is **isomorphic**: if your content scales beyond your code base, Val lets you easily make it remote. Just add `.remote()` to your schema and Val will host your content - your components stays the same. Remote content are handled using immutable references, so remote content are tied to Git commits - rollbacks, branches works as before.
+<details>
+<summary>Definition: editor</summary>
+An editor in this context, is a non-technical person that edits content in your application (technical writer, proof-reader, legal, ...).
+</details>
 
-- Contextual editing: Val is built from the ground up to support contextual editing. Editors can see Val content in the context of the app, and make edits directly there.
+<br />
 
-- Full CMS: even hard-coded content has its drawbacks: i18n, images, rich text - Val supports all of these.
+But, with the benefits of **hard-coded** content:
 
-- No signup required: **your** content is yours. Local development requires no sign ups and is free. When you are ready and editors needs access, you can sign up and without any changes to your code base. Head over to [https://app.val.build](https://app.val.build) to get started 🚀.
+- works seamlessly **locally** or with git **branches**
+- content is **type-checked** so you can spend less time on figuring out why something isn't working
+  ![Type check error](./docs/type-check-error.png)
+- content can be refactored (change names, etc) just as if it was hard-coded (because it is)
+  ![Renaming](./docs/renaming.gif)
+- works as normal with your **favorite IDE** without any plugins: search for content, references to usages, ...
+  ![References](./docs/references.gif)
+- **no** need for **code-gen** and extra build steps
+- **fast** since the content is literally hosted with the application
+- content is **always there** and can never fail (since it is not loaded from somewhere)
+- no need to manage different **environments** containing different versions of content
+- **resolve conflicts** like you normally resolve conflicts: **in git**
+
+Compared to other CMSs, Val has the following advantages:
+
+- **easy** to setup and to _grok_: Val is designed to have a minimum of boilerplate and there's **0** query languages to learn. If you know your way around JSON that's enough (if you don't you might want to learn it)
+- **no signup** required to use it locally
+- **no fees** for content that is in your code: your content is your code, and your code is... yours
+- **minimal** API surface: Val is designed to not "infect" your code base
+- **easy to remove**: since your content is already in your code and Val is designed to have a minimal surface, it's easy to remove if you want to switch
+
+<details>
+<summary>Upcoming feature: <strong>i18n</strong></summary>
+Val will soon have support for i18n. Follow this repository to get notified when this is the case.
+</details>
+
+<details>
+<summary>Upcoming feature: <strong>remote content</strong></summary>
+Having hard-coded content is great for landing pages, product pages and other pages where the amount of content is manageable.
+
+However, checking in the 10 000th blog entry in git might feel wrong (though we would say it is ok).
+
+Therefore, Val will add `remote content` support which enables you to seamlessly move content to the cloud and back again as desired.
+You code will still be the one truth, but the actual content will be hosted on [val.build](https://val.build).
+
+`.remote()` support will also make it possible to have remote images to avoid having to put them in your repository.
+
+There will also be specific support for remote i18n, which will make it possible to split which languages are defined in code, and which are fetched from remote.
+
+More details on `.remote()` will follow later.
+
+</details>
+
+## When to NOT use Val
+
+Val is designed to work well on a single web-app, and currently only supports Next 13.4+ (more meta-frameworks will supported) and GitHub (more Git providers will follow).
+
+Unless your application fits these requirements, you should have a look elsewhere (at least for now).
+
+In addition, if you have a "content model", i.e. content schemas, that rarely change and you plan on using them in a lot of different applications (web, mobile, etc), Val will most likely not be a great fit.
+
+If that is the case, we recommend having a look at [sanity](https://sanity.io) instead (we have no affiliation, but if we didn't have Val we would use Sanity).
+
+**NOTE**: Our experience is that however nice it sounds, it is hard to "nail" the content model down. Usually content is derived from what you want to present, not vice-versa. In addition, you should think carefully whether you _really_ want to present the exact same content on all these different surfaces.
+
+## Examples
+
+Check out this README or the [examples](./examples) directory for examples.
 
 ## Installation
 
-- Make sure you have TypeScript 4.9+, Next 12+ (other meta frameworks will come), React 18+ (other frontend frameworks will come)
-- Install the packages:
+- Make sure you have TypeScript 5+, Next 13.4+ (other meta frameworks will come), React 18.20.+ (other frontend frameworks will come)
+- Install the package:
 
 ```sh
-npm install @valbuild/next
+npm install @valbuild/next@latest
 ```
 
-- Create your val.config.ts file. NOTE: this file should be in the same directory as `tsconfig.json`:
+- Create a `val.config.ts` file. **NOTE**: this file should be in the same directory as `tsconfig.json`:
 
 ```ts
 // ./val.config.ts
@@ -73,127 +164,170 @@ const { s, val } = initVal();
 export { s, val };
 ```
 
-- Enable contextual editing: setup Val endpoints
+- Create the endpoints file:
 
 ```ts
 // ./src/pages/api/val/[...val].ts
 
-import { valEditHandler } from "../../../../val.config";
+import { createRequestListener } from "@valbuild/server";
 import { NextApiHandler } from "next";
 
-const handler: NextApiHandler = valEditHandler;
+const handler: NextApiHandler = createRequestListener("/api/val", {
+  valConfigPath: "./val.config",
+});
 
 export default handler;
 
 export const config = {
   api: {
+    responseLimit: false,
     bodyParser: false,
     externalResolver: true,
   },
 };
 ```
 
-- Enable contextual editing: Use the Val provider in the \_app file:
+- Use the Val provider in the root layout file:
 
 ```tsx
-// ./src/pages/_app.tsx
+// ./app/layout.tsx
 
-import { ValProvider } from "@valbuild/react";
-import type { AppProps } from "next/app";
+import { ValProvider } from "@valbuild/next";
 
-function MyApp({ Component, pageProps }: AppProps) {
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
   return (
-    <ValProvider host="/api/val">
-      <Component {...pageProps} />
-    </ValProvider>
+    <html lang="en">
+      <body className={inter.className}>
+        <ValProvider> {children}</ValProvider>
+      </body>
+    </html>
   );
 }
+```
+
+### [OPTIONAL]: Setup eslint
+
+Install the eslint package:
+
+```bash
+npm install @valbuild/eslint-plugin@latest
+```
 
-export default MyApp;
+Add the following to your `.eslintrc.json`:
+
+```json
+  "plugins": ["@valbuild"],
+  "rules": {
+    "@valbuild/no-illegal-module-ids": "error"
+  }
 ```
 
+### Add editor support
+
+To make it possible to do non-local edits, head over to [val.build](https://val.build) and import your repository.
+
+**NOTE**: your content is yours. No subscription (or similar) is required to host content from your repository.
+
+If you do not need to edit content online (i.e. not locally), you do not need to sign up.
+
+**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.
+
 ## Getting started
 
 ### Create your first Val content file
 
-Content defined in Val is always defined `.val.{ts|js}` files.
+Content in Val is always defined in `.val.ts` files.
+
+**NOTE**: Val also works with `.js` files.
+
+They must export a default `val.content` where the first argument equals the path of the file relative to the `val.config.ts` file.
+
+**NOTE**: `val.ts` files are _evaluated_ by Val, therefore they have a specific set of requirements:
+
+- They must have a default export that is `val.content`, they must have a `export const schema` with the Schema; and
+- they CANNOT import anything other than `val.config` and `@valbuild/core`
 
-They must export a default `val.content` where the first argument equals the path of the file relative to the `val.config.{js|ts}` file.
+### Example of a `.val.ts` file
 
 ```ts
-// ./src/content/example/blogs.val.ts
+// ./src/app/content.val.ts
 
 import { s, val } from "../../../val.config";
 
+export const schema = s.object({
+  title: s.string().optional(), //  <- NOTE: optional()
+  sections: s.array(
+    s.object({
+      title: s.string(),
+      text: s.richtext({
+        bold: true, // <- Enables bold in richtext
+      }),
+    })
+  ),
+});
+
 export default val.content(
-  "/src/content/example/blogs", // <- NOTE: this must be the same path as the file
-  s.array(s.object({ title: s.string(), text: s.string() })),
-  [
-    {
-      title: "Title 1",
-      text: "Text 1",
-    },
-    {
-      title: "Title 2",
-      text: "Text 2",
-    },
-  ]
+  "/src/app/content", // <- NOTE: this must be the same path as the file
+  schema,
+  {
+    title: "My Page",
+    sections: [
+      {
+        title: "Section 1",
+        text: val.richtext`
+RichText is **awesome**`,
+      },
+    ],
+  }
 );
 ```
 
 ### Use your content
 
-```tsx
-// ./src/pages/example/index.tsx
+In client components you can access your content with the `useVal` hook:
 
+**NOTE**: Support for React Server Components and server side rendering will come soon.
+
+```tsx
+// ./src/app/page.tsx
+"use client";
 import { NextPage } from "next";
-import { useVal } from "@valbuild/react";
-import blogsVal from "@/content/example/blogs.val";
+import { useVal } from "@valbuild/next/client";
+import contentVal from "./content.val";
 
-const Blog: NextPage = () => {
-  const blog = useVal(blogsVal[0]);
+const Page: NextPage = () => {
+  const { title, sections } = useVal(contentVal);
   return (
     <main>
-      <article>
+      {title && (
+        <section>
+          <h1>{title}</h1>
+        </section>
+      )}
+      {sections.map((section) => (
         <section>
-          <h1>{blog.title}</h1>
-          <p>{blog.text}</p>
+          <h2>{section.title}</h2>
+          <ValRichText
+            theme={{
+              bold: "font-bold",
+            }}
+          >
+            {section.text}
+          </ValRichText>
         </section>
-      </article>
+      ))}
     </main>
   );
 };
 
-export default Blog;
+export default Page;
 ```
 
-## Concepts
-
-`.val.{ts|js}` files **MUST** have a default export which is a ValModule. A ValModule is a special type of [Selector](#selectors). Selectors makes it possible to select a subset of content from a ValModule or a another Selector.
-
-Selectors can be turned to Val types using `useVal` or `fetchVal`.
-
-### .val files
-
-`.val.{ts|js}` files are the files in which you store your content.
-
-They are evaluated when the content is run, therefore they have a specific set of requirements. They must have a default export that is `val.content`, they must have a `export const schema` with the Schema and they CANNOT import anything other than `val.config` and `@valbuild/core`.
-
-Example:
-
-```ts
-import { s, val } from "../val.config";
-
-export const schema = t.string();
-
-export default val.content(
-  "/file/path/relative/to/val/config",
-  schema,
-  "My string content"
-);
-```
-
-NOTE: IN THE FUTURE, they will be validated by the eslint-plugin.
+# Schema types
 
 ## String
 
@@ -203,16 +337,6 @@ import { s } from "./val.config";
 s.string(); // <- Schema<string>
 ```
 
-### String selectors
-
-See [Selectors](#selector) for more info.
-
-### String `.eq`
-
-```ts
-useVal(stringVal.eq("")); // <- Val<boolean>
-```
-
 ## Number
 
 ```ts
@@ -221,16 +345,6 @@ import { s } from "./val.config";
 s.number(); // <- Schema<number>
 ```
 
-### Number selectors
-
-See [Selectors](#selector) for more info.
-
-### Number `.eq`
-
-```ts
-useVal(numberVal.eq(2)); // <- Val<boolean>
-```
-
 ## Boolean
 
 ```ts
@@ -239,16 +353,6 @@ import { s } from "./val.config";
 s.boolean(); // <- Schema<boolean>
 ```
 
-### Boolean selectors
-
-See [Selectors](#selector) for more info.
-
-### Boolean `.eq`
-
-```ts
-useVal(booleanVal.eq(true)); // <- Val<boolean>
-```
-
 ## Optional
 
 All schema types can be optional. An optional schema creates a union of the type and `null`.
@@ -259,34 +363,22 @@ import { s } from "./val.config";
 s.string().optional(); // <- Schema<string | null>
 ```
 
-### Selectors
-
-### Accessing the underlying type: `.andThen`
-
-To use and optional val, you can use the [.andThen](#andthen) selector.
-
 ## Array
 
 ```ts
-s.array(t.string());
+s.array(t.string()); // <- Schema<string[]>
 ```
 
-### Selecting arrays
-
-### `.filter`
-
-TODO: text
+## Record
 
-```ts
-useVal(myArray.filter((item) => item.title.eq("Title 1")));
-```
+The type of `s.record` is `Record`.
 
-### `.map`
+It is similar to an array, in that editors can add and remove items in it, however it has a unique key which can be used as, for example, the slug or as a part of an route.
 
-TODO:
+**NOTE**: records can also be used with `keyOf`.
 
 ```ts
-useVal(myArray.map((item) => ({ test: item.title })));
+s.record(t.number()); // <- Schema<Record<string, number>>
 ```
 
 ## Object
@@ -297,24 +389,23 @@ s.object({
 });
 ```
 
-### Selecting objects
+## RichText
 
-You can select Selector objects almost as if they were normal objects. The exception is that you cannot use the spread (`...`) operator.
+<details>
+<summary>RichText in Val represented both in code and to the editors as <strong>semantic html5</strong>.</summary>
 
-Example:
+This means that content will be accessible and according to spec out of the box. The flip-side is that Val will not support RichText that includes elements that is not part of the html 5 standard.
 
-```ts
-useVal({ foo: myObjectVal.hello });
-```
+This opinionated approach was chosen since rendering anything, makes it hard for developers to maintain and hard for editors to understand.
 
-## RichText
+</details>
 
 ### RichText Schema
 
 ```ts
-import { s } from "./val.config";
-
-s.richtext();
+s.richtext({
+  // options
+});
 ```
 
 ### Initializing RichText content
@@ -324,54 +415,60 @@ To initialize some text content using a RichText schema, you can use follow the
 ```ts
 import { s, val } from "./val.config";
 
-// TODO: need some other way of doing this:
-export default val.content("/example/richtext.ts", s.richtext(), {
-  children: [
-    {
-      type: "paragraph",
-      version: 1,
-      indent: 0,
-      direction: "ltr",
-      format: "",
-      children: [
-        {
-          type: "text",
-          version: 1,
-          mode: "normal",
-          format: 0,
-          detail: 0,
-          style: "",
-          text: "TODO: update me",
-        },
-      ],
-    },
-  ],
-  direction: "ltr",
-  format: "",
-  indent: 0,
-  type: "root",
-  version: 1,
+export const schema = s.richtext({
+  // styling:
+  bold: true, // enables bold
+  //italic: true, // enables italic text
+  //lineThrough: true, // enables line/strike-through
+  // tags:
+  //headings: ["h1", "h2", "h3", "h4", "h5", "h6"], // sets which headings are available
+  //a: true, // enables links
+  //img: true, // enables images
+  //ul: true, // enables unordered lists
+  //ol: true, // enables ordered lists
 });
+
+export default val.content(
+  "/src/app/content",
+  schema,
+  val.richtext`
+NOTE: this is markdown.
+
+**Bold** text.
+`
+);
 ```
 
-### Render RichText
+### Rendering RichText
 
 You can use the `ValRichText` component to render content.
 
 ```tsx
 "use client";
-import { useVal, ValRichText } from "@valbuild/react";
-import richtextVal from "./richtext";
+import { ValRichText } from "@valbuild/next";
+import contentVal from "./content.val";
+import { useVal } from "@valbuild/next/client";
 
 export default function Page() {
-  const richtext = useVal(richtextVal);
-  return <ValRichText>{richtext}</ValRichText>;
+  const content = useVal(contentVal);
+  return (
+    <main>
+      <ValRichText
+        theme={{
+          bold: "font-bold", // <- maps bold to a class. NOTE: tailwind classes are supported
+          //
+        }}
+      >
+        {content}
+      </ValRichText>
+    </main>
+  );
 }
 ```
 
 ## Image
 
-### Schema
+### Image Schema
 
 ```ts
 s.image();
@@ -389,7 +486,7 @@ export const schema = s.image();
 export default val.content("/image", schema, val.file("/public/myfile.jpg"));
 ```
 
-NOTE: This will not validate, since images requires `width`, `height` and a `sha256` checksum. You can fix this validation in the UI by opening the image and clicking the Fix button.
+**NOTE**: This will not validate, since images requires `width`, `height` and a `sha256` checksum. You can fix this validation in the UI by opening the image and clicking the Fix button.
 
 ### Using images in components
 
@@ -404,100 +501,25 @@ const image = useVal(imageVal);
 return <img src={image.url} />;
 ```
 
-## Internalization
-
-**NOTE**: WORKS ONLY ON THE TYPE LEVEL
-
-To enable i18n, you must update your Val with the locales you want to enforce.
-
-Example:
-
-```ts
-// ./val.config.ts
-
-import { initVal } from "@valbuild/core";
-
-const { s, val } = initVal({
-  locales: {
-    required: ["en_US", "fr_FR"],
-    fallback: "en_US",
-  },
-});
-
-export { s, val };
-```
-
-## Union
+## KeyOf
 
-**NOTE**: WORKS ONLY ON THE TYPE LEVEL
+If you need to reference content in another `.val` file you can use the `keyOf` schema.
 
-TODO: fill in.
+### KeyOf Schema
 
 ```ts
-s.union(
-  "type",
-  s.object({ type: s.literal("type1"), bar: s.string() }),
-  s.object({ type: s.literal("type2"), foo: s.number() })
-);
-```
-
-### Selecting unions
-
-### `.fold`
-
-TODO: description
+import otherVal from "./other.val"; // NOTE: this must be an array or a record
 
-```ts
-useVal(myUnionVal.fold("type")({
-
-})
+s.keyOf(otherVal);
 ```
 
-## One of references
-
-**NOTE**: Currently not possible to change from UI
-
-```ts
-
-```
-
-# Remote
-
-**NOTE**: WORKS ONLY ON THE TYPE LEVEL
+### Initializing keyOf
 
-All schemas can be converted into `.remote`.
+### Using keyOf to reference content
 
-TODO: add description.
-
-Example:
-
-```ts
-export const schema = s.object({ stuff: s.string() });
-
-export default val.content("/remote/example", schema, val.remote("REFERENCE"));
-```
-
-## Selector
-
-To select parts of a your content you should use Selectors.
-If you make the content `.remote`
-
-### `.andThen`
-
-All selectors can use `andThen` method which is similar to the `&&` operator. You can use this to only do operations on optionals that are defined. NOTE: only TRUTHY arguments are passed in to `andThen` (i.e. the empty string, `''` is NOT truthy).
-
-Given the example schema:
-
-```ts
-// ./maybeArray.val.ts
-//...
-
-export const schema = t.array(t.string()).optional();
-
-//...
-```
+```tsx
+const article = useVal(articleVal); // s.object({ author: s.keyOf(otherVal) })
+const authors = useVal(otherVal); // s.array(s.object({ name: s.string() }))
 
-```ts
-import maybeArrayVal from "./maybeArray.val";
-useVal(maybeArrayVal.andThen((array) => array.filter((v) => v.eq("foo"))));
+const nameOfAuthor = authors[articleVal.author].name;
 ```