@valbuild/core 0.128.0 → 0.129.0

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # @valbuild/core
 
+## 0.129.0
+
+### Minor Changes
+
+- [#655](https://github.com/valbuild/val/pull/655) [`7d34ecc`](https://github.com/valbuild/val/commit/7d34ecce787a0709025ae7b4764cb6c3ad1f766b) Thanks [@freekh](https://github.com/freekh)! - A project can now make Val Studio look like its own.
+
+  `s.settings()` has a new `theme` section, edited under **Settings → Appearance**
+  in the Studio. It is content like everything else: edited as a draft, shown in
+  the publish diff, and the same for everyone working on the project.
+
+  ```ts
+  export default c.define("/settings.val.ts", s.settings(), {
+    theme: {
+      accent: "#2563eb",
+      radius: "tight",
+      mode: "light",
+    },
+  });
+  ```
+
+  **`accent` is one hex, and it restyles the whole chrome** — Publish, the active
+  rail item, focus rings, switches, the caret in a rich text field, and the
+  outlines the canvas draws around editable elements on your own page. Any colour
+  is allowed, not a list of approved ones, because what the accent replaces is a
+  ten-step ramp that is _generated_ from it: each step keeps the lightness of the
+  step it replaces and changes only the hue. WCAG contrast is almost entirely a
+  function of lightness, so every foreground/background pair the chrome renders
+  stays at AA — which is asserted across the hue circle, pure black and a
+  saturated yellow included, rather than argued for. One value drives both light
+  and dark mode, since the semantic tokens pick different steps of the ramp in
+  each.
+
+  **`radius`** is `square`, `tight`, `default` or `soft`, and moves every corner
+  in the Studio.
+
+  The accent also moves the outlines the canvas draws around editable elements on
+  your own page. Those are drawn inside your document, which has none of Val's
+  stylesheet, so the colour is sent to the page over the canvas protocol — which
+  means a project on an older `@valbuild/next` or `@valbuild/tanstack` than its
+  Studio keeps Val's green there until it upgrades, rather than breaking.
+
+  **`mode`** is the mode the Studio opens in for an editor who has never picked
+  one. It never overrides an editor who has — that choice stays theirs, per
+  person and per browser, behind the account button.
+
+  Every field is optional, and unset means Val's own look, so an existing
+  settings module needs no change.
+
+  Two smaller fixes that came with it:
+
+  - **A settings change is its own entry in the publish diff.** Editing the
+    assistant's tone used to collapse the entire settings module into one change
+    card labelled "Settings", because the patch that writes a settings field is
+    an `add`, and `PatchSets` had no case for a settings section — so it gave up
+    and grouped the whole module. Two unrelated settings edits now show as two
+    changes, each under the name the panel gives it.
+  - **The Val mark keeps its green.** It named a step of the brand ramp, so it
+    would have recoloured along with a project's accent. It has its own token now.
+
+- [#657](https://github.com/valbuild/val/pull/657) [`0c351c4`](https://github.com/valbuild/val/commit/0c351c4f97ae7f09772eab0e856ae69821b803b7) Thanks [@freekh](https://github.com/freekh)! - A project can put its own logo in Val Studio.
+
+  `s.settings()`'s `theme` section takes a `logo`, uploaded from **Settings →
+  Appearance**. It replaces Val's mark at the top of the left rail, and beside the
+  menu button below the desktop breakpoint — the two slots that say which
+  workspace you are in.
+
+  ```ts
+  export default c.define("/settings.val.ts", s.settings(), {
+    theme: {
+      logo: {
+        path: "/public/val/brand/mark_a1b2c.png",
+        width: 512,
+        height: 512,
+        mimeType: "image/png",
+      },
+    },
+  });
+  ```
+
+  It is an ordinary image field, so it comes with the upload, the alt text and
+  everything else `s.image()` has, and the file lands in `/public/val/brand` so it
+  does not sit in the middle of your content's media. A draft logo shows
+  immediately and publishes with the rest of your changes.
+
+  Two things are deliberate:
+
+  - **A square-ish mark, not a wordmark.** The slot is 32px wide. A wide image is
+    fitted into it rather than cropped, so all of it is there and none of it is
+    large.
+  - **Val's mark stays on the launcher that floats on your own site.** In the
+    Studio the mark labels the workspace, so your logo belongs there. On your own
+    page it labels the tool — it is the button that opens Val — and your logo
+    floating over your own website says nothing.
+
 ## 0.128.0
 
 ### Minor Changes

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

@@ -54,7 +54,7 @@ export { type SerializedImageSchema, ImageSchema } from "./schema/image.js";
 export { type SerializedFileSchema, FileSchema } from "./schema/file.js";
 export { type SerializedDateSchema, DateSchema } from "./schema/date.js";
 export { type SerializedSettingsSchema, SettingsSchema, } from "./schema/settings.js";
-export { type SettingsSource, type AssistantSettingsSource, type LocalesSettingsSource, type AssistantAvailability, ASSISTANT_SETTINGS_MAX_LENGTH, assistantAvailability, } from "./source/settings.js";
+export { type SettingsSource, type AssistantSettingsSource, type LocalesSettingsSource, type AssistantAvailability, type ThemeSettingsSource, type ThemeRadius, ASSISTANT_SETTINGS_MAX_LENGTH, THEME_LOGO_DIRECTORY, THEME_RADIUS_STEPS, THEME_RADIUS_LENGTHS, assistantAvailability, } from "./source/settings.js";
 export { type ResolvedSettingsModule, SETTINGS_MODULE_CONVENTION, isRootModuleFilePath, resolveSettingsModule, } from "./settingsModule.js";
 export { type Locale, localeTagError, localeOfValue } from "./locale.js";
 export { type SerializedLocaleSchema, LocaleSchema } from "./schema/locale.js";

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.
  *