@valbuild/core 0.127.0 → 0.129.0

package/dist/declarations/src/schema/record.d.ts

@@ -11,7 +11,7 @@ import type { ImageEncodeOption } from "./image.js";
 type MediaOptions = {
     type: "files" | "images";
     accept: string;
-    directory: string;
+    dir: string;
     remote: boolean;
     altSchema?: Schema<SelectorSource>;
     /** Images only: how uploads are re-encoded in the browser. See `image.ts`. */
@@ -34,7 +34,7 @@ export type SerializedRecordSchema = {
     customValidate?: boolean;
     mediaType?: "files" | "images";
     accept?: string;
-    directory?: string;
+    dir?: string;
     remote?: boolean;
     encode?: ImageEncodeOption;
     alt?: SerializedSchema;
@@ -229,7 +229,7 @@ RO extends boolean = false> extends Schema<Src> {
      * Allow the files in this gallery to be stored on Val's remote content host
      * instead of in your repository.
      *
-     * For `s.images()` and `s.files()`, which are records of media. Remote is off
+     * For `s.imageset()` and `s.fileset()`, which are records of media. Remote is off
      * until this is called.
      *
      * Each entry is then keyed by its URL on the content host rather than by a
@@ -238,7 +238,7 @@ RO extends boolean = false> extends Schema<Src> {
      * upload it and rewrite the key.
      *
      * @example
-     * const schema = s.images({ directory: "/public/val/images" }).remote();
+     * const schema = s.imageset({ dir: "/public/val/images" }).remote();
      * export default c.define("/content/images.val.ts", schema, {
      *   "https://remote.val.build/file/p/my-project/b/01/v/1.0.0/h/8f2a1c/f/3b9d70/p/public/val/images/hero.webp":
      *     {
@@ -257,7 +257,7 @@ RO extends boolean = false> extends Schema<Src> {
      * which lets the runtime, the Studio and validation work one entry at a time
      * so a record/router can scale to many thousands of entries.
      *
-     * Not supported on image/file galleries (`s.images()` / `s.files()`).
+     * Not supported on image/file galleries (`s.imageset()` / `s.fileset()`).
      *
      * Only supported on a module's ROOT record/router — a `.jsonValues()` record
      * nested inside an object/array/record is rejected at startup with a module
@@ -284,7 +284,7 @@ RO extends boolean = false> extends Schema<Src> {
      * bucket — instead of in the module.
      *
      * Available on every record-derived schema, which is `s.record()`,
-     * `s.router()`, `s.images()` and `s.files()` alike: a router is a
+     * `s.router()`, `s.imageset()` and `s.fileset()` alike: a router is a
      * `RecordSchema` with a `ValRouter`, a gallery one with media options, so all
      * four get external storage from this one method.
      *

package/dist/declarations/src/schema/settings.d.ts

@@ -141,11 +141,18 @@ export declare class SettingsSchema<Src extends {
  *     context: "Val is a CMS for developers. British English, and 'Val' is never 'VAL'.",
  *     tone: "Plain and direct. No exclamation marks, sentence case in headings.",
  *   },
+ *   theme: {
+ *     accent: "#2563eb",
+ *     radius: "tight",
+ *     logo: { path: "/public/val/brand/mark_a1b2c.png", width: 512, height: 512, mimeType: "image/png" },
+ *   },
  * });
  * ```
  *
- * The Studio edits it under the cog at the foot of the left rail, and the
- * assistant is told `assistant.context` and `assistant.tone` on every message.
+ * The Studio edits it under the cog at the foot of the left rail. The assistant
+ * is told `assistant.context` and `assistant.tone` on every message, and
+ * `theme` restyles the Studio's own chrome — see {@link ThemeSettingsSource},
+ * and note that it is the CMS being restyled, not the site.
  *
  * `s.settings()` takes no arguments: the shape is Val's, which is what lets the
  * Studio render a UI built for each field rather than a generic form. A

package/dist/declarations/src/source/settings.d.ts

@@ -1,3 +1,4 @@
+import { ImageSource } from "./media.js";
 /**
  * The source of the project's settings module — `s.settings()`.
  *
@@ -22,8 +23,97 @@
  */
 export type SettingsSource = {
     assistant?: AssistantSettingsSource;
+    theme?: ThemeSettingsSource;
     locales?: LocalesSettingsSource;
 };
+/**
+ * How the Studio looks in this project.
+ *
+ * Chrome, and only chrome: nothing here reaches a visitor to the site. It is
+ * the CMS that is being restyled, so that a project can make the tool it edits
+ * in feel like its own.
+ *
+ * This is deliberately NOT the light/dark switch. That one is per-person and
+ * per-machine (see `ValThemeProvider`, which keeps it in `localStorage`), and it
+ * has to stay that way — one editor working in a dark room is not a fact about
+ * the project. {@link ThemeSettingsSource.mode} is the project's DEFAULT for
+ * someone who has not chosen, which is a different statement.
+ */
+export type ThemeSettingsSource = {
+    /**
+     * The one colour the Studio's chrome is built from, as a hex string.
+     *
+     * Unset means Val's own green. What it replaces is not a single value but the
+     * whole ten-step brand ramp — `--colors-brand-green-100` through `-1000` —
+     * because every brand token in `index.css` points into that ramp, and light
+     * and dark pick different steps out of it. One accent therefore drives both
+     * modes, with nothing to keep in sync.
+     *
+     * Any hex is allowed rather than a list of approved ones, and that is safe
+     * for a measured reason rather than an optimistic one: the ramp is generated
+     * by reusing green's LIGHTNESS at each step and changing only the hue, and
+     * WCAG contrast is almost entirely a function of lightness. See
+     * `accentRamp` in `@valbuild/shared`, whose tests hold every
+     * foreground/background pair the chrome renders to AA across the hue circle.
+     */
+    accent?: string | null;
+    /**
+     * How round the Studio's corners are.
+     *
+     * Named steps rather than a length, for two reasons: a number input invites
+     * `7px`, which nothing in the chrome is drawn around, and the scale is Val's
+     * decision rather than the project's. See {@link THEME_RADIUS_LENGTHS} for
+     * what each one is worth.
+     */
+    radius?: ThemeRadius | null;
+    /**
+     * The mode the Studio opens in for someone who has not picked one.
+     *
+     * A default, not a setting: an editor who has flicked the switch behind the
+     * account button keeps their choice, and this never overrides it.
+     */
+    mode?: "dark" | "light" | null;
+    /**
+     * The project's own mark, shown where Val's is in the Studio.
+     *
+     * The top of the left rail on desktop, and beside the menu button on mobile.
+     * NOT the launcher that floats on the project's own site: there the mark says
+     * "this is Val", and a project's logo on its own page says nothing at all —
+     * see {@link THEME_LOGO_DIRECTORY} and `architecture/logo.md`.
+     *
+     * A square-ish mark rather than a wordmark, because the slot it goes in is
+     * 32px wide. A wide image is contained rather than cropped, so nothing is
+     * cut off — it is simply small.
+     */
+    logo?: ImageSource | null;
+};
+/**
+ * Where an uploaded logo goes.
+ *
+ * Its own directory rather than the `/public/val` default, so that the one
+ * image a project uploads through the settings panel does not land in the
+ * middle of its content's media. `val list-unused-files` reads what is
+ * referenced rather than where it sits, so nothing depends on this beyond
+ * tidiness.
+ */
+export declare const THEME_LOGO_DIRECTORY = "/public/val/brand";
+/** @see {@link ThemeSettingsSource.radius} */
+export type ThemeRadius = "square" | "tight" | "default" | "soft";
+export declare const THEME_RADIUS_STEPS: readonly ThemeRadius[];
+/**
+ * What each radius step is worth, as a `--radius` value.
+ *
+ * `--radius` is the only length in the Studio's chrome that is a token:
+ * `rounded-sm`, `rounded-md` and `rounded-lg` are all `calc(var(--radius) …)`
+ * in `tailwind.config.js`, which is around three hundred call sites moving on
+ * one value. `default` is what `index.css` declares, so selecting it and
+ * clearing the setting look the same — which is what makes this list the whole
+ * of the feature.
+ *
+ * `rounded-full` and the hand-written `rounded-t` / `-r` / `-b` cases do not
+ * follow, and that is visible at `soft`: a pill stays a pill.
+ */
+export declare const THEME_RADIUS_LENGTHS: Record<ThemeRadius, string>;
 /**
  * The languages this project publishes.
  *