@valbuild/next 0.57.0 → 0.58.0

package/README.md

@@ -73,7 +73,7 @@ As a CMS, Val is useful because:
 - **richtext** support is built-in
 - built-in **visual editing** which lets editors click-then-edit content (and therefore **code**!) directly in your app
 
-  ![Visual editing](./docs/visual-editing.png)
+  ![Visual editing](https://val.build/docs/images/overlay.png)
 
 <details>
 <summary>Definition: editor</summary>
@@ -86,11 +86,11 @@ But, with the benefits of **hard-coded** content:
 
 - 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)
+  ![Type check error](https://val.build/docs/images/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)
+  ![Renaming](https://val.build/docs/images/renaming.gif)
 - works as normal with your **favorite IDE** without any plugins: search for content, references to usages, ...
-  ![References](./docs/references.gif)
+  ![References](https://val.build/docs/images/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)
@@ -137,7 +137,7 @@ In addition, if you have a "content model", i.e. content schemas, that rarely ch
 
 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.
+**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
 
@@ -155,7 +155,7 @@ npm install @valbuild/next@latest @valbuild/eslint-plugin@latest
 - Run the init script:
 
 ```sh
-npx @valbuild/init
+npx @valbuild/init@latest
 ```
 
 ### Add editor support
@@ -398,6 +398,133 @@ export default function Page() {
 }
 ```
 
+#### ValRichText: theme property
+
+To add classes to `ValRichText` you can use the theme property:
+
+```tsx
+<ValRichText
+  theme={{
+    p: "font-sans",
+    // etc
+  }}
+>
+  {content}
+</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`:
+
+```tsx
+<ValRichText
+  theme={{
+    h1: "text-4xl font-bold",
+    bold: "font-bold",
+    img: null, // either a string or null is required
+  }}
+>
+  {content satisfies RichText<{ headings: ["h1"]; bold: true; img: true }>}
+</ValRichText>
+```
+
+**NOTE**: the reason you must define themes for every tag that the RichText is that this will force you to revisit the themes that are used if the schema changes. The alternative would be to accept changes to the schema.
+
+### ValRichText: transform 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.
+
+```tsx
+<ValRichText
+  transform={(node, _children, className) => {
+    if (typeof node !== "string" && node.tag === "img") {
+      return (
+        <div className="my-wrapper-class">
+          <img {...node} className={className} />
+        </div>
+      );
+    }
+    // if transform returns undefined the default render will be used
+  }}
+>
+  {content}
+</ValRichText>
+```
+
+### The RichText type
+
+The `RichText` type is actually an AST (abstract syntax tree) representing semantic HTML5 elements.
+
+That means they look something like this:
+
+```ts
+type RichTextNode = {
+  tag:
+    | "img"
+    | "a"
+    | "ul"
+    | "ol"
+    | "h1"
+    | "h2"
+    | "h3"
+    | "h4"
+    | "h5"
+    | "h6"
+    | "br"
+    | "p"
+    | "li"
+    | "span";
+  classes: "bold" | "line-through" | "italic"; // all styling classes
+  children: RichTextNode[] | undefined;
+};
+```
+
+### RichText: full custom
+
+The `RichText` type maps 1-to-1 to HTML.
+That means it is straightforward to build your own implementation of a React component that renders `RichText`.
+
+This example is a simplified version of the `ValRichText` component.
+You can use this as a template to create your own.
+
+NOTE: before writing your own, make sure you check out the `theme` and `transform` properties on the `ValRichText` - most simpler cases should be covered by them.
+
+```tsx
+export function ValRichText({
+  children: root,
+}: {
+  children: RichText<MyRichTextOptions>;
+}) {
+  function build(
+    node: RichTextNode<MyRichTextOptions>,
+    key?: number
+  ): JSX.Element | string {
+    if (typeof node === "string") {
+      return node;
+    }
+    // you can map the classes to something else here
+    const className = node.classes.join(" ");
+    const tag = node.tag; // one of: "img" | "a" | "ul" | "ol" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "br" | "p" | "li" | "span"
+
+    // Example of rendering img with MyOwnImageComponent:
+    if (tag === "img") {
+      return <MyOwnImageComponent {...node} />;
+    }
+    return React.createElement(
+      tag,
+      {
+        key,
+        className,
+      },
+      "children" in node ? node.children.map(build) : null
+    );
+  }
+  return <div {...val.attrs(root)}>{root.children.map(build)}</div>;
+}
+type MyRichTextOptions = AnyRichTextOptions; // you can reduce the surface of what you need to render, by restricting the `options` in `s.richtext(options)`
+```
+
 ## Image
 
 ### Image Schema
@@ -418,7 +545,19 @@ export const schema = s.image();
 export default c.define("/image", schema, c.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 validation errors like this by using the CLI or by using the VS Code plugin.
+
+### Rendering images
+
+The `ValImage` component is a wrapper around `next/image` that accepts a Val `Image` type.
+
+You can use it like this:
+
+```tsx
+const content = useVal(contentVal);
+
+return <ValImage src={content.image} alt={content.alt} />;
+```
 
 ### Using images in components
 

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

@@ -1,9 +1,14 @@
-import { type ValConfig, type InitVal, type ValConstructor } from "@valbuild/core";
+import { type ValConfig, type InitVal, type ValConstructor, RichText, AnyRichTextOptions, ValModule, SelectorSource, Json } from "@valbuild/core";
 import { raw } from "./raw.js";
 import { decodeValPathOfString } from "./decodeValPathOfString.js";
+type ValAttrs = {
+    "data-val-path"?: string;
+};
 export declare const initVal: (config?: ValConfig) => InitVal & {
     val: ValConstructor & {
         raw: typeof raw;
-        decodeValPathOfString: typeof decodeValPathOfString;
+        attrs: <T extends ValModule<SelectorSource> | Json | RichText<AnyRichTextOptions>>(target: T) => ValAttrs;
+        unstable_decodeValPathOfString: typeof decodeValPathOfString;
     };
 };
+export {};

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

@@ -33,6 +33,16 @@ function _interopNamespace(e) {
 var core__namespace = /*#__PURE__*/_interopNamespace(core);
 var NextImage__default = /*#__PURE__*/_interopDefault(NextImage);
 
+function _typeof(o) {
+  "@babel/helpers - typeof";
+
+  return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) {
+    return typeof o;
+  } : function (o) {
+    return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+  }, _typeof(o);
+}
+
 function toPrimitive(t, r) {
   if ("object" != typeof t || !t) return t;
   var e = t[Symbol.toPrimitive];
@@ -107,7 +117,28 @@ var initVal = function initVal(config) {
     s: s,
     c: c,
     val: _objectSpread2(_objectSpread2({}, val), {}, {
-      decodeValPathOfString: decodeValPathOfString,
+      attrs: function attrs(target) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        var anyTarget = target;
+        var path;
+        if (target === null) {
+          return {};
+        }
+        path = core.Internal.getValPath(anyTarget);
+        if (!path && _typeof(anyTarget) === "object") {
+          path = anyTarget["valPath"];
+        }
+        if (typeof anyTarget === "string") {
+          path = decodeValPathOfString(anyTarget);
+        }
+        if (path) {
+          return {
+            "data-val-path": path
+          };
+        }
+        return {};
+      },
+      unstable_decodeValPathOfString: decodeValPathOfString,
       raw: raw
     }),
     config: currentConfig

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

@@ -33,6 +33,16 @@ function _interopNamespace(e) {
 var core__namespace = /*#__PURE__*/_interopNamespace(core);
 var NextImage__default = /*#__PURE__*/_interopDefault(NextImage);
 
+function _typeof(o) {
+  "@babel/helpers - typeof";
+
+  return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) {
+    return typeof o;
+  } : function (o) {
+    return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+  }, _typeof(o);
+}
+
 function toPrimitive(t, r) {
   if ("object" != typeof t || !t) return t;
   var e = t[Symbol.toPrimitive];
@@ -107,7 +117,28 @@ var initVal = function initVal(config) {
     s: s,
     c: c,
     val: _objectSpread2(_objectSpread2({}, val), {}, {
-      decodeValPathOfString: decodeValPathOfString,
+      attrs: function attrs(target) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        var anyTarget = target;
+        var path;
+        if (target === null) {
+          return {};
+        }
+        path = core.Internal.getValPath(anyTarget);
+        if (!path && _typeof(anyTarget) === "object") {
+          path = anyTarget["valPath"];
+        }
+        if (typeof anyTarget === "string") {
+          path = decodeValPathOfString(anyTarget);
+        }
+        if (path) {
+          return {
+            "data-val-path": path
+          };
+        }
+        return {};
+      },
+      unstable_decodeValPathOfString: decodeValPathOfString,
       raw: raw
     }),
     config: currentConfig

package/dist/valbuild-next.esm.js

@@ -1,4 +1,4 @@
-import { initVal as initVal$1 } from '@valbuild/core';
+import { initVal as initVal$1, Internal } from '@valbuild/core';
 import * as core from '@valbuild/core';
 export { core as expr };
 export { FILE_REF_PROP, GenericSelector, Schema, VAL_EXTENSION, derefPatch } from '@valbuild/core';
@@ -9,6 +9,16 @@ import NextImage from 'next/image';
 import { jsx } from 'react/jsx-runtime';
 export { ValApp } from './ValApp-6827827a.esm.js';
 
+function _typeof(o) {
+  "@babel/helpers - typeof";
+
+  return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) {
+    return typeof o;
+  } : function (o) {
+    return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+  }, _typeof(o);
+}
+
 function toPrimitive(t, r) {
   if ("object" != typeof t || !t) return t;
   var e = t[Symbol.toPrimitive];
@@ -83,7 +93,28 @@ var initVal = function initVal(config) {
     s: s,
     c: c,
     val: _objectSpread2(_objectSpread2({}, val), {}, {
-      decodeValPathOfString: decodeValPathOfString,
+      attrs: function attrs(target) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        var anyTarget = target;
+        var path;
+        if (target === null) {
+          return {};
+        }
+        path = Internal.getValPath(anyTarget);
+        if (!path && _typeof(anyTarget) === "object") {
+          path = anyTarget["valPath"];
+        }
+        if (typeof anyTarget === "string") {
+          path = decodeValPathOfString(anyTarget);
+        }
+        if (path) {
+          return {
+            "data-val-path": path
+          };
+        }
+        return {};
+      },
+      unstable_decodeValPathOfString: decodeValPathOfString,
       raw: raw
     }),
     config: currentConfig

package/package.json

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