@valbuild/core 0.130.0 → 0.136.0

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 {};