@valbuild/core 0.129.0 → 0.134.0

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

@@ -0,0 +1,197 @@
+import { Schema, SchemaAssertResult, SerializedSchema } from "./index.js";
+import type { ModuleIdOf, ValModuleBrand } from "../module.js";
+import { ReifiedPreview } from "../preview.js";
+import { FieldRender } from "../render.js";
+import { GenericSelector } from "../selector/index.js";
+import { Source } from "../source/index.js";
+import { ValViewSource } from "../source/view.js";
+import { ModuleFilePath, SourcePath } from "../val/index.js";
+import { ValidationError, ValidationErrors } from "./validation/ValidationError.js";
+export type SerializedValViewSchema = {
+    type: "view";
+    render?: FieldRender;
+    /** Never set: a view has no value of its own to preview. Carried for shape parity. */
+    preview?: true;
+    /** Always false: a view points at a module, and `null` is not a module. */
+    opt: false;
+    /** Always false: there is no value for a custom validator to look at. */
+    customValidate?: false;
+    /** The module this field points at. */
+    moduleFilePath: ModuleFilePath;
+    readonly?: boolean;
+    hidden?: boolean;
+    description?: string;
+};
+/** The source type of the module a selector points at. */
+type SourceOf<M> = M extends GenericSelector<infer S> ? S : never;
+/**
+ * A field that points at ANOTHER module, for the Val editor's benefit.
+ *
+ * The source is `{ view: "/other.val.ts" }` — a pointer, and nothing else. The
+ * module it names keeps its own source, its own patches, its own validation and
+ * its own address; this field puts a row on THIS module's screen that an editor
+ * clicks through to it.
+ *
+ * Two type parameters, each earning its place:
+ *
+ * - `Id` — the target's module file path as a literal, so the author writes
+ *   `{ view: "/other.val.ts" }` with autocomplete, and naming a different module
+ *   than the schema does is a type error rather than a validation error.
+ * - `T` — the target's source type, carried on a phantom slot so the READ side
+ *   can say `ValView<T>` rather than `ValView<unknown>`. Nothing reads it yet;
+ *   it is here so that resolving a view through `useVal` can be added without
+ *   changing what is stored.
+ */
+export declare class ValViewSchema<Id extends string = string, T = unknown> extends Schema<ValViewSource<Id, T>> {
+    private readonly moduleFilePath;
+    /**
+     * The module this points at, as an object.
+     *
+     * Not serialized and not part of the schema's identity — it is here so the
+     * READ path can resolve a view without a path-to-module registry, which the
+     * app does not have (`val.modules` is lazy thunks, `<ValModulesClient>` is
+     * optional). Absent on a schema that came off the wire, which is fine: the
+     * Studio navigates to a view, it does not resolve one.
+     */
+    private readonly valModule;
+    private readonly isReadonly;
+    private readonly isHidden;
+    private readonly description?;
+    private readonly renderInput;
+    constructor(moduleFilePath: Id, 
+    /**
+     * The module this points at, as an object.
+     *
+     * Not serialized and not part of the schema's identity — it is here so the
+     * READ path can resolve a view without a path-to-module registry, which the
+     * app does not have (`val.modules` is lazy thunks, `<ValModulesClient>` is
+     * optional). Absent on a schema that came off the wire, which is fine: the
+     * Studio navigates to a view, it does not resolve one.
+     */
+    valModule?: unknown, isReadonly?: boolean, isHidden?: boolean, description?: string | undefined, renderInput?: FieldRender | null);
+    /**
+     * Describe this field.
+     *
+     * Shown next to the field's label in the Val editor — here, the place to say
+     * WHY the other module is on this screen, since an editor who follows the row
+     * is about to change content that other pages use too.
+     *
+     * @example
+     * import otherVal from "./other.val"; // another module
+     * const schema = s.object({
+     *   shared: s.view(otherVal).describe("Shared by every page"),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   shared: { view: "/other.val.ts" },
+     *   title: "Hello",
+     * });
+     */
+    describe(description: string | null): ValViewSchema<Id, T>;
+    /**
+     * The stored pointer must name the module the SCHEMA names.
+     *
+     * It cannot disagree in a `.val.ts` — the source type is the literal path, so
+     * a mismatch does not compile. It can disagree in hand-written JSON (a
+     * `.jsonValues()` entry, an external record), which is what this is for.
+     */
+    protected executeValidate(path: SourcePath, src: ValViewSource<Id, T>): ValidationErrors;
+    protected executeCustomValidateAt(_path: SourcePath, _src: ValViewSource<Id, T>): ValidationError[];
+    protected executeAssert(path: SourcePath, src: unknown): SchemaAssertResult<ValViewSource<Id, T>>;
+    /**
+     * Not available: a view points at a module, and `null` is not a module.
+     * Throws if called.
+     *
+     * @example
+     * import otherVal from "./other.val"; // another module
+     * // `s.view(otherVal).nullable()` throws — a view is never nullable.
+     * const schema = s.object({ shared: s.view(otherVal), title: s.string() });
+     * export default c.define("/example.val.ts", schema, {
+     *   shared: { view: "/other.val.ts" },
+     *   title: "Hello",
+     * });
+     */
+    nullable(): Schema<ValViewSource<Id, T> | null>;
+    /**
+     * Marks the row read-only.
+     *
+     * The view's OWN flag, and it says nothing about the module it names: that
+     * module has its own `readonly`, which is what governs editing once an
+     * editor is there. A view is a link rather than an editor, so this changes
+     * nothing about the row today — it exists because every schema has it, and
+     * because a view that renders its target inline would need it.
+     *
+     * @example
+     * import otherVal from "./other.val"; // another module
+     * const schema = s.object({
+     *   shared: s.view(otherVal).readonly(),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   shared: { view: "/other.val.ts" },
+     *   title: "Hello",
+     * });
+     */
+    readonly(isReadonly?: boolean): ValViewSchema<Id, T>;
+    /**
+     * Hide the ROW in the editor.
+     *
+     * The view's OWN flag, and it is the only thing that decides whether the row
+     * is drawn — a view whose TARGET is hidden is still shown, and still leads
+     * there. That is the point of it: a module that many modules `keyOf` into is
+     * noise in the nav and belongs on exactly one page, so it is hidden from the
+     * listing and reached through the view that puts it where it belongs.
+     *
+     * @example
+     * import otherVal from "./other.val"; // another module
+     * const schema = s.object({
+     *   shared: s.view(otherVal).hidden(),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   shared: { view: "/other.val.ts" },
+     *   title: "Hello",
+     * });
+     */
+    hidden(isHidden?: boolean): ValViewSchema<Id, T>;
+    /**
+     * How this field is laid out in the editor. Static configuration, not a
+     * callback — see `render.ts`.
+     *
+     * @example
+     * import otherVal from "./other.val"; // another module
+     * const schema = s.object({
+     *   shared: s.view(otherVal).render({ as: "inline" }),
+     *   title: s.string(),
+     * });
+     * export default c.define("/example.val.ts", schema, {
+     *   shared: { view: "/other.val.ts" },
+     *   title: "Hello",
+     * });
+     */
+    render(input: FieldRender): ValViewSchema<Id, T>;
+    protected executeSerialize(): SerializedSchema;
+    protected executePreview(): ReifiedPreview;
+}
+/**
+ * Point at another module, so the Val editor shows a way into it from here.
+ *
+ * A view stores a pointer and nothing else: the module it names keeps its own
+ * source, patches, validation and address, and an editor reaches it by clicking
+ * through rather than by hunting for it. It is there so content that has to live
+ * in its own module — a `keyOf` target, shared settings, a route-keyed record —
+ * can still be found from the page it belongs to.
+ *
+ * Reading it in consuming code gives you a pointer with no fields on it. Read
+ * the module it names directly instead.
+ *
+ * @example
+ * import otherVal from "./other.val"; // another module
+ * const schema = s.object({ shared: s.view(otherVal), title: s.string() });
+ * export default c.define("/example.val.ts", schema, {
+ *   shared: { view: "/other.val.ts" },
+ *   title: "Hello",
+ * });
+ */
+export declare const view: <M extends GenericSelector<Source> & ValModuleBrand>(valModule: M) => ValViewSchema<ModuleIdOf<M>, SourceOf<M>>;
+export {};

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

@@ -13,11 +13,13 @@ import { AllRichTextOptions, RichTextSource } from "../source/richtext.js";
 import { RichTextSelector } from "./richtext.js";
 import { JsonSource } from "../source/json.js";
 import { ExternalRecordSrc } from "../source/external.js";
+import { ValViewSource } from "../source/view.js";
+import { ValView } from "./view.js";
 import { SettingsSource } from "../source/settings.js";
-export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends MediaSource ? GenericSelector<T> : T extends JsonSource ? GenericSelector<JsonSource> : T extends ExternalRecordSrc ? GenericSelector<T> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends SettingsSource ? GenericSelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
+export type Selector<T extends Source> = Source extends T ? GenericSelector<T> : T extends MediaSource ? GenericSelector<T> : T extends JsonSource ? GenericSelector<JsonSource> : T extends ExternalRecordSrc ? GenericSelector<T> : T extends ValViewSource<string, infer Target> ? ValView<Target> : T extends RichTextSource<infer O> ? RichTextSelector<O> : T extends SourceObject ? ObjectSelector<T> : T extends SourceArray ? ArraySelector<T> : T extends SettingsSource ? GenericSelector<T> : T extends string ? StringSelector<T> : T extends number ? NumberSelector<T> : T extends boolean ? BooleanSelector<T> : T extends null ? PrimitiveSelector<null> : never;
 export type SelectorSource = SourcePrimitive | undefined | readonly SelectorSource[] | {
     [key: string]: SelectorSource;
-} | MediaSource | JsonSource | ExternalRecordSrc | SettingsSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
+} | MediaSource | JsonSource | ExternalRecordSrc | ValViewSource | ValView<Source> | SettingsSource | RichTextSource<AllRichTextOptions> | GenericSelector<Source>;
 /**
  * @internal
  */

package/dist/declarations/src/selector/view.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Type-level-only slot naming the source type of the module a {@link ValView}
+ * points at. Required, not optional: nothing else should ever be a `ValView` by
+ * accident, and reading a property off one has to be an error.
+ */
+declare const ViewTarget: unique symbol;
+/**
+ * A pointer to another module, as consuming code sees it.
+ *
+ * It has no properties on purpose. A view exists for the Val editor — it puts a
+ * way into another module on this module's screen — and there is nothing in it
+ * to render. Read the module it names directly.
+ *
+ * `T` is the target's source type. It is what lets `useVal(page.header)` be
+ * typed as the header's content — the overload that resolves a handle
+ * constrains `T` to `Source` there rather than here, because `ValViewSource` is a
+ * member of the `Source` union and a constraint here is a circular reference.
+ */
+export type ValView<T> = {
+    readonly [ViewTarget]: T;
+};
+export {};

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

@@ -1,9 +1,10 @@
 import { ExternalRecordSrc } from "./external.js";
+import { ValViewSource } from "./view.js";
 import { JsonSource } from "./json.js";
 import { MediaSource } from "./media.js";
 import { RichTextOptions, RichTextSource } from "./richtext.js";
 import { SettingsSource } from "./settings.js";
-export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | ExternalRecordSrc | SettingsSource | RichTextSource<RichTextOptions>;
+export type Source = SourcePrimitive | SourceObject | SourceArray | MediaSource | JsonSource | ExternalRecordSrc | ValViewSource | SettingsSource | RichTextSource<RichTextOptions>;
 export type SourceObject = {
     [key in string]: Source;
 } & {

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

@@ -25,6 +25,33 @@ export type SettingsSource = {
     assistant?: AssistantSettingsSource;
     theme?: ThemeSettingsSource;
     locales?: LocalesSettingsSource;
+    studio?: StudioSettingsSource;
+};
+/**
+ * How the Studio behaves for the people editing this project.
+ *
+ * Not how it looks — that is {@link ThemeSettingsSource} — and not one person's
+ * own preferences, which stay in their browser. This is the project's word on
+ * what its editors are offered, which is why it is content: a team that has
+ * decided something about the way they work should not need a developer and a
+ * deploy to say so.
+ */
+export type StudioSettingsSource = {
+    /**
+     * Whether editors are offered the guided tour of the Studio.
+     *
+     * Unset means yes, because the person this exists for is the one who has not
+     * answered any question yet. Setting it to `false` turns the offer off for
+     * everyone on the project, permanently and for good — which is the point:
+     * a team that finds it noisy can be rid of it once rather than each person
+     * dismissing it on each machine they use.
+     *
+     * It governs the OFFER, not the tour. Whoever wants it can still run it from
+     * Quick actions; what goes is the glowing button and the prompt on the empty
+     * editor. Whether a given person has already been through it is a fact about
+     * that browser and is not here.
+     */
+    tour?: boolean | null;
 };
 /**
  * How the Studio looks in this project.

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

@@ -0,0 +1,41 @@
+/**
+ * Type-level-only slot carrying the SOURCE TYPE of the module a view names.
+ *
+ * Optional, and that is what makes the marker writable: `{ view: "/foo.val.ts" }`
+ * is a plain literal, and an optional symbol-keyed property costs the author
+ * nothing to satisfy. It exists so the read side can say WHAT is behind the
+ * pointer — `ValView<FooSrc>` rather than `ValView<unknown>` — without the
+ * author having to write a type they do not have.
+ */
+declare const ViewTargetSource: unique symbol;
+/**
+ * The source of a view field: a pointer to another module, and nothing else.
+ *
+ * Written as a plain object, like media and for the same reason — the same
+ * value has to work in a `.val.ts` and in a `*.val.json` entry, and a literal
+ * survives the static extraction that a constructor call does not. See
+ * `architecture/media.md`.
+ *
+ * `Id` is the target's module file path as a LITERAL type, inferred from the
+ * module handed to `s.view(...)`. So the path autocompletes at the call site,
+ * and a source naming a different module than its schema does is a type error.
+ *
+ * Nothing decides "this is a view" by looking at the value; the SCHEMA does
+ * (`type === "view"`). {@link isValViewSource} exists for the few places that have
+ * a value and no schema, and is not the normal way to ask.
+ */
+export type ValViewSource<Id extends string = string, T = unknown> = {
+    readonly view: Id;
+} & {
+    readonly [ViewTargetSource]?: T;
+};
+/**
+ * Is this value shaped like a view marker?
+ *
+ * A shape test, not an identity: `view` is a reserved object key
+ * (`ObjectSchemaProps`), so no ordinary object source can take this shape — but
+ * hand-written JSON can, which is why validation checks the value against the
+ * schema rather than trusting it.
+ */
+export declare function isValViewSource(value: unknown): value is ValViewSource;
+export {};

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

@@ -0,0 +1,69 @@
+import type { ValModule } from "../module.js";
+import { Schema } from "../schema/index.js";
+import type { GenericSelector, SelectorSource } from "../selector/index.js";
+import type { ValView } from "../selector/view.js";
+import type { Source, SourceObject } from "./index.js";
+import { ValViewSource } from "./view.js";
+/**
+ * Where a resolved view handle keeps the module it points at.
+ *
+ * A symbol, so it is invisible to `JSON.stringify`, `Object.keys`, the source
+ * SHAs and every walk that treats source as data — the handle still IS
+ * `{ view: "/foo.val.ts" }` everywhere that matters.
+ */
+declare const ViewTargetModule: unique symbol;
+/**
+ * A view's source with the module it names attached.
+ *
+ * `useVal(page.header)` needs the target's SOURCE and its SCHEMA, and the
+ * stored pointer has neither — it is a path. The app has no way to turn a path
+ * back into a module either: `val.modules` holds lazy `import()` thunks, and
+ * `<ValModulesClient>` is optional. So the module travels with the handle.
+ *
+ * Attached by the READ path (`stegaEncode`) rather than written into source,
+ * and that is the whole reason it works in draft mode: with an edit pending,
+ * the source comes from the overlay store as plain JSON that never went near a
+ * module. The schema is the module's own either way, so the encoder always has
+ * it to hand.
+ */
+export type ValViewHandle = ValViewSource & {
+    readonly [ViewTargetModule]: unknown;
+};
+/** Attach the module a view names to its pointer. */
+export declare function createViewHandle(source: ValViewSource, valModule: unknown): ValViewHandle;
+/** Is this a view pointer that carries the module it names? */
+export declare function isViewHandle(value: unknown): value is ValViewHandle;
+/** The module a handle carries, or undefined if it carries none. */
+export declare function viewHandleModule(value: unknown): unknown;
+/**
+ * What a reader that needs a MODULE accepts, rather than a value.
+ *
+ * `useValKey`, `useValRoute`, `useValRouteUrl` and their `fetch*` counterparts
+ * all read a path, a schema and a source off what they are handed, so — unlike
+ * `useVal` — they cannot take an arbitrary selector. They CAN take a view
+ * pointing at one, which is the point of a page declaring which module it
+ * shows. {@link resolveViewedModule} is the runtime half, and takes exactly
+ * this, so the two cannot drift.
+ */
+export type ResolvableModule<S extends Source = SourceObject> = ValModule<GenericSelector<S>> | ValView<S>;
+/**
+ * What a reader was actually handed: the module itself, or — when it is a view
+ * handle — the module that view points at.
+ *
+ * Every reader that needs a module rather than a value goes through this:
+ * `useValKey`, `useValRoute`, `useValRouteUrl` and their `fetch*` counterparts
+ * all pull the path, the schema and the source off the thing they are given,
+ * and a view handle has none of those. It is `{ view: "/foo.val.ts" }` with the
+ * module on a symbol, so reading `Internal.getValPath` off it gives
+ * `undefined`, and every one of those readers treats `undefined` as its own
+ * "no route matched" answer. Without this the call is not an error — it is a
+ * silently empty one.
+ *
+ * A POINTER with no module on it throws rather than being passed through, for
+ * the same reason `stegaEncode` throws on one: symbols do not survive
+ * serialization, so a handle that crossed the server/client boundary as a prop
+ * arrives looking like content and is not.
+ */
+export declare function resolveViewedModule<S extends Source>(selector: ResolvableModule<S>): ValModule<GenericSelector<S>>;
+export declare function viewModulesOf(schema: Schema<SelectorSource> | undefined): Map<string, unknown>;
+export {};