@valbuild/next 0.100.0 → 0.101.0

package/README.md

@@ -55,6 +55,9 @@
   - [Image](#image)
   - [keyOf](#keyof)
   - [Route](#route)
+  - [Color](#color)
+  - [Date](#date)
+  - [DateTime](#datetime)
 
 ## Installation
 
@@ -886,6 +889,235 @@ export default c.define("/components/link.val.ts", linkSchema, {
 });
 ```
 
+## Color
+
+The `color` schema represents a color, stored as a CSS color string. Because the value is a plain CSS string, it can be used directly in a `style` attribute or set as a CSS custom property - there is nothing to convert in your components.
+
+### Color Schema
+
+```ts
+s.color(); // <- Schema<string>
+```
+
+### Output format
+
+The `format` option decides which CSS notation the color is stored in. It defaults to `"hsl"`.
+
+```ts
+s.color(); // hsl(217.22 91.22% 59.8%)
+s.color({ format: "hex" }); // #3b82f6
+s.color({ format: "rgb" }); // rgb(59 130 246)
+s.color({ format: "oklch" }); // oklch(0.6231 0.188 259.81)
+```
+
+The Val editor writes the value back in this format, so an editor who pastes `#3b82f6` into a field declared as `s.color()` gets `hsl(217.22 91.22% 59.8%)` stored.
+
+### Transparency
+
+Colors are fully opaque unless you opt into an alpha channel with `alpha: true`. A color with an alpha channel is a validation error in a field that does not allow it, so you can be sure an opaque color stays opaque.
+
+```ts
+s.color({ format: "hsl", alpha: true }); // hsl(217.22 91.22% 59.8% / 0.5)
+```
+
+With `alpha: true` the editor also gets an alpha slider next to the color picker.
+
+### Validation
+
+Validation is lenient about the syntax and strict about the format:
+
+- both the modern and the legacy notation of the declared format are accepted, so `hsl(0 100% 50%)` and `hsl(0, 100%, 50%)` are both valid `hsl` values, and `#f00` is a valid `hex` value
+- a color written in another format is an error which tells you the equivalent value in the right notation:
+  `Expected a color in the 'hsl' format (e.g. 'hsl(217.22 91.22% 59.8%)'), got '#ff0000'. Did you mean 'hsl(0 100% 50%)'?`
+- named colors (`red`), `lab()`, `color()` and `color-mix()` are not supported
+
+Colors can be nullable and can use `.describe()` and `.validate()` like any other schema:
+
+```ts
+s.color().nullable().describe("Optional highlight color");
+
+s.color({ format: "hex" }).validate((color) => {
+  if (color === "#000000") {
+    return "Pure black is too harsh - pick a dark grey instead";
+  }
+  return false;
+});
+```
+
+### Initializing color content
+
+```ts
+import { s, c, type t } from "../val.config";
+
+export const schema = s.object({
+  brand: s.color().describe("Primary brand color"),
+  background: s.color({ format: "hex" }).describe("Page background"),
+  overlay: s.color({ format: "hsl", alpha: true }).describe("Overlay tint"),
+});
+
+export type Theme = t.inferSchema<typeof schema>;
+export default c.define("/content/theme.val.ts", schema, {
+  brand: "hsl(217.22 91.22% 59.8%)",
+  background: "#0b1020",
+  overlay: "hsl(217.22 91.22% 59.8% / 0.15)",
+});
+```
+
+### Using colors
+
+The value is a string, so use it wherever CSS expects a color:
+
+```tsx
+import { fetchVal } from "../val/rsc";
+import themeVal from "../content/theme.val";
+
+export default async function Hero() {
+  const theme = await fetchVal(themeVal);
+  return (
+    <section style={{ background: theme.background, color: theme.brand }}>
+      <h1 style={{ borderBottom: `2px solid ${theme.brand}` }}>Hello</h1>
+    </section>
+  );
+}
+```
+
+To hand a color to a stylesheet instead, set it as a CSS custom property:
+
+```tsx
+<div style={{ "--brand": theme.brand } as React.CSSProperties}>
+```
+
+**NOTE**: colors are not steganographically tagged, since the value ends up in CSS where the invisible characters would break the declaration. Colors therefore do not participate in click-then-edit visual editing (the same is true of dates) - edit them from the studio instead.
+
+## Date
+
+The `date` schema represents a calendar day, with no time and no timezone. It is stored as a `YYYY-MM-DD` string.
+
+### Date Schema
+
+```ts
+s.date(); // <- Schema<string>
+```
+
+### Date bounds
+
+Use `.from()` and `.to()` to constrain which days are valid. Both bounds are inclusive.
+
+```ts
+s.date().from("1900-01-01"); // this day or later
+s.date().to("2024-01-01"); // this day or earlier
+s.date().from("1900-01-01").to("2024-01-01"); // within the range
+```
+
+These are methods, not options - `s.date({ from: "1900-01-01" })` does not type check.
+
+Bounds are compared as strings, which is exactly right for `YYYY-MM-DD` (it sorts chronologically) and wrong for anything else, so write bounds in that format.
+
+**NOTE**: the schema checks the bounds, but not the shape of the string: a value like `"the 3rd of May"` is stored and validated without complaint. The editor always writes `YYYY-MM-DD`, so this only bites hand-written content. Use `.validate()` if you want it enforced:
+
+```ts
+s.date().validate((day) =>
+  /^\d{4}-\d{2}-\d{2}$/.test(day) ? false : "Must be a YYYY-MM-DD date",
+);
+```
+
+### Editing dates
+
+Editors get a calendar. `from` and `to` limit which days can be picked, and a value already outside the bounds is shown clamped to the nearest one.
+
+### Initializing date content
+
+```ts
+import { s, c } from "../val.config";
+
+export const schema = s.object({
+  birthdate: s
+    .date()
+    .from("1900-01-01")
+    .to("2024-01-01")
+    .nullable()
+    .describe("Author's birthdate"),
+});
+
+export default c.define("/content/author.val.ts", schema, {
+  birthdate: "1981-12-30",
+});
+```
+
+### Using dates
+
+The value is a plain string, so it can be compared and sorted as one:
+
+```tsx
+const authors = [...allAuthors].sort((a, b) =>
+  (a.birthdate ?? "").localeCompare(b.birthdate ?? ""),
+);
+```
+
+To format it, hand it to `Date` or a date library. Note that `new Date("2024-05-03")` parses as UTC midnight, so formatting it in a local timezone west of UTC shows the previous day - format from the parts, or use a library that treats the value as a plain day:
+
+```tsx
+const [year, month, day] = author.birthdate.split("-").map(Number);
+const label = new Date(year, month - 1, day).toLocaleDateString();
+```
+
+## DateTime
+
+The `dateTime` schema represents an instant in time. It is stored as an ISO 8601 string in UTC, for example `2023-04-12T09:30:00.000Z`.
+
+### DateTime Schema
+
+```ts
+s.datetime(); // <- Schema<string>
+```
+
+The factory is spelled `datetime`, all lowercase. The schema type it serializes to is `dateTime` - that name shows up in validation output and in the editor, but you never write it yourself.
+
+### DateTime bounds
+
+As with `date`, use the inclusive `.from()` and `.to()` methods. They accept any ISO 8601 datetime that `Date.parse` understands, and are compared as instants rather than as strings, so bounds and values may be written in different notations:
+
+```ts
+s.datetime().from("2020-01-01T00:00:00Z");
+s.datetime().from("2020-01-01T00:00:00Z").to("2030-12-31T23:59:59Z");
+```
+
+Unlike `date`, the value itself is checked: a string that `Date.parse` cannot read is a validation error.
+
+> Value 'yesterday' is not a valid ISO 8601 datetime
+
+### Editing datetimes
+
+The editor shows a calendar, a time input (down to seconds) and a timezone picker. The picker starts on the browser's timezone and remembers the last choice, so an editor in one place can enter a time as it will be experienced somewhere else. Whichever zone is chosen, the value is converted and stored as UTC - the timezone is a property of the editor, never of the content.
+
+### Initializing datetime content
+
+```ts
+import { s, c } from "../val.config";
+
+export const schema = s.object({
+  joinedAt: s.datetime().nullable().describe("When the author joined"),
+});
+
+export default c.define("/content/author.val.ts", schema, {
+  joinedAt: "2023-04-12T09:30:00.000Z",
+});
+```
+
+### Using datetimes
+
+Since the value is an ISO 8601 UTC string, `Date` parses it directly:
+
+```tsx
+<time dateTime={author.joinedAt}>
+  {new Date(author.joinedAt).toLocaleString()}
+</time>
+```
+
+Rendering a UTC instant in the visitor's local timezone means server and client can format it differently. In Next.js that shows up as a hydration mismatch, so format inside a client component (or pass a fixed `timeZone` to `toLocaleString`) when the exact time matters.
+
+**NOTE**: neither `date` nor `dateTime` values are steganographically tagged, so they do not participate in click-then-edit visual editing - edit them from the studio instead. Both support `.nullable()`, `.describe()`, `.validate()`, `.readonly()` and `.hidden()` like any other schema.
+
 # Custom validation
 
 All schema can use the `validate` method to show custom validation errors to editors.

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

@@ -37,6 +37,13 @@ export declare const Internal: {
     joinModuleFilePathAndModulePath: typeof import("@valbuild/core/dist/declarations/src/module").joinModuleFilePathAndModulePath;
     nextAppRouter: import("@valbuild/core").ValRouter;
     externalPageRouter: import("@valbuild/core").ValRouter;
+    color: {
+        parseColor: typeof import("@valbuild/core/dist/declarations/src/schema/colorFormat").parseColor;
+        formatColor: typeof import("@valbuild/core/dist/declarations/src/schema/colorFormat").formatColor;
+        convertColor: typeof import("@valbuild/core/dist/declarations/src/schema/colorFormat").convertColor;
+        detectColorFormat: typeof import("@valbuild/core/dist/declarations/src/schema/colorFormat").detectColorFormat;
+        colorToHex: typeof import("@valbuild/core/dist/declarations/src/schema/colorFormat").colorToHex;
+    };
     remote: {
         createRemoteRef: typeof import("@valbuild/core/dist/declarations/src/source/remote").createRemoteRef;
         getValidationBasis: typeof import("@valbuild/core/dist/declarations/src/remote/validationBasis").getValidationBasis;

package/package.json

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