schema-components 2.0.2 → 2.1.1

package/src/vue/resolver.ts

@@ -0,0 +1,45 @@
+/**
+ * Vue resolver helpers — resolver-key lookup and resolver merging.
+ *
+ * Mirrors the React adapter's `getRenderFunction` / `mergeResolvers`
+ * pair, parameterised over {@link VueComponentResolver} and
+ * {@link VueRenderFunction}. Reuses {@link RESOLVER_KEYS} and
+ * {@link typeToKey} from `core/renderer.ts` so the per-type → key
+ * mapping has one canonical definition shared by every adapter.
+ */
+
+import { RESOLVER_KEYS, typeToKey } from "../core/renderer.ts";
+import type { WalkedField } from "../core/types.ts";
+import type { VueComponentResolver, VueRenderFunction } from "./types.ts";
+
+/**
+ * Look up the {@link VueRenderFunction} for a schema type in a
+ * {@link VueComponentResolver}. Returns `undefined` when the resolver
+ * has no entry for the type — the caller (typically the dispatcher in
+ * `core/renderField.ts`) then falls through to the headless resolver.
+ */
+export function getVueRenderFunction(
+    type: WalkedField["type"],
+    resolver: VueComponentResolver
+): VueRenderFunction | undefined {
+    return resolver[typeToKey(type)];
+}
+
+/**
+ * Merge two {@link VueComponentResolver}s — user values take priority,
+ * fallback fills gaps. Iterates {@link RESOLVER_KEYS} so every field
+ * variant the walker can emit has a deterministic resolution path.
+ */
+export function mergeVueResolvers(
+    user: VueComponentResolver,
+    fallback: VueComponentResolver
+): VueComponentResolver {
+    const merged: VueComponentResolver = {};
+    for (const key of RESOLVER_KEYS) {
+        const fn = user[key] ?? fallback[key];
+        if (fn !== undefined) {
+            merged[key] = fn;
+        }
+    }
+    return merged;
+}

package/src/vue/types.ts

@@ -0,0 +1,140 @@
+/**
+ * Vue-flavoured render-prop and resolver shapes.
+ *
+ * Mirrors the React adapter's `RenderProps` / `RenderFunction` /
+ * `ComponentResolver` trio, parameterised over Vue's {@link VNode}
+ * output type. Built on top of the framework-agnostic generic
+ * `BaseRenderProps` and `RenderFunction` from `core/renderer.ts` so the
+ * Vue adapter shares a single source of truth for the per-field props
+ * shape with React, HTML, and any future framework adapter.
+ *
+ * The `onChange` callback semantics are deliberately kept identical to
+ * the React adapter — see the design note in `vue/SchemaComponent.vue`.
+ * Vue authors who prefer `v-model` / emit-based wiring use the
+ * top-level `<SchemaComponent>` and `<SchemaView>` SFCs (which translate
+ * the Vue-idiomatic surface back to the imperative `onChange`); the
+ * inner render functions consume the imperative shape directly so the
+ * dispatcher contract is uniform across adapters.
+ */
+
+import type { VNode } from "vue";
+import type { BaseRenderProps, RenderFunction } from "../core/renderer.ts";
+import type { WalkedField } from "../core/types.ts";
+
+// ---------------------------------------------------------------------------
+// VueRenderProps — per-field props passed to every Vue render function
+// ---------------------------------------------------------------------------
+
+/**
+ * Props for Vue render functions. Extends {@link BaseRenderProps} with:
+ *
+ * - `onChange` — imperative callback to propagate value changes back to
+ *   the host component. The top-level `<SchemaComponent>` SFC bridges
+ *   this to a `change` emit / `v-model` update, so consumers writing
+ *   pure render functions still operate against the same imperative
+ *   contract as the React adapter.
+ * - `renderChild` — recursively renders a child field, threading
+ *   `onChange` through the four-argument signature inherited from
+ *   `RenderProps` so theme adapters (or future widget code) can share
+ *   helpers between React and Vue with minimal adaptation.
+ */
+export interface VueRenderProps extends BaseRenderProps<VNode> {
+    /**
+     * Callback to update the field value. Wired to the Vue
+     * `@change` / `v-model` surface by the `<SchemaComponent>` SFC.
+     */
+    onChange: (value: unknown) => void;
+    /**
+     * Render a child field. Theme adapters call this to recursively
+     * render nested structures (object fields, array elements, union
+     * options).
+     *
+     * @param tree - The walked field tree for the child.
+     * @param value - The child's current value.
+     * @param onChange - Callback receiving the child's next value.
+     * @param pathSuffix - Path segment from the parent (e.g. `"city"`,
+     *   `"[0]"`). Joined to the parent's path with a dot, or
+     *   substituted when the parent acts as a transparent wrapper
+     *   (union options). Required for every container — without it
+     *   children inherit no path and `fieldDomId()` will throw.
+     */
+    renderChild: (
+        tree: WalkedField,
+        value: unknown,
+        onChange: (v: unknown) => void,
+        pathSuffix?: string
+    ) => VNode;
+}
+
+// ---------------------------------------------------------------------------
+// VueRenderFunction — render function signature
+// ---------------------------------------------------------------------------
+
+/**
+ * Signature for a Vue render function. Specialisation of the generic
+ * {@link RenderFunction} with `Output = VNode` and
+ * `Props = VueRenderProps`.
+ *
+ * Composes cleanly with the generic dispatch in `core/renderField.ts`:
+ *
+ * ```ts
+ * const r: VueRenderFunction = (props) => h("input", { value: props.value });
+ * const generic: RenderFunction<VNode, VueRenderProps> = r;  // assignable
+ * ```
+ */
+export type VueRenderFunction = RenderFunction<VNode, VueRenderProps>;
+
+// ---------------------------------------------------------------------------
+// VueComponentResolver — theme adapter interface for Vue
+// ---------------------------------------------------------------------------
+
+/**
+ * Vue theme adapter — maps every schema field type to its Vue
+ * {@link VueRenderFunction}. Structurally mirrors the React
+ * `ComponentResolver` but produces `VNode`s.
+ *
+ * Unset keys fall back to the headless resolver. Pass to the
+ * `<SchemaProvider>` SFC or directly to a `<SchemaComponent>`'s
+ * `resolver` prop to drive every schema-driven render with a specific
+ * theme.
+ */
+export interface VueComponentResolver {
+    string?: VueRenderFunction;
+    number?: VueRenderFunction;
+    boolean?: VueRenderFunction;
+    null?: VueRenderFunction;
+    enum?: VueRenderFunction;
+    object?: VueRenderFunction;
+    array?: VueRenderFunction;
+    tuple?: VueRenderFunction;
+    record?: VueRenderFunction;
+    union?: VueRenderFunction;
+    discriminatedUnion?: VueRenderFunction;
+    conditional?: VueRenderFunction;
+    negation?: VueRenderFunction;
+    literal?: VueRenderFunction;
+    file?: VueRenderFunction;
+    never?: VueRenderFunction;
+    unknown?: VueRenderFunction;
+}
+
+// ---------------------------------------------------------------------------
+// VueWidgetMap — scoped widget registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Widget map — maps component hints (from `.meta({ component })`) to
+ * {@link VueRenderFunction}s. Parallels the React `WidgetMap` but
+ * produces `VNode`s.
+ *
+ * Scoped at three levels:
+ *
+ * 1. **Per-instance** — `widgets` prop on `<SchemaComponent>`
+ * 2. **Context-scoped** — provided via {@link VueWidgetsContext}
+ * 3. **Global** — `registerWidget()` (app-wide defaults)
+ *
+ * Resolution order: instance → context → global → resolver → headless,
+ * mirroring the React resolution chain so dual-target consumers see
+ * identical fallback behaviour.
+ */
+export type VueWidgetMap = ReadonlyMap<string, VueRenderFunction>;

package/src/vue/vue-shim.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Ambient module declaration for `.vue` Single-File Component imports.
+ *
+ * TypeScript cannot natively parse `.vue` files, so we shim every
+ * `*.vue` import as a `DefineComponent`. Vue's official tooling
+ * (`vue-tsc`, Volar in editor mode) reads the actual SFC and produces
+ * a fully-typed component definition; this shim provides a sound
+ * fallback for plain `tsc --noEmit` so the existing typecheck step
+ * (`packages/core/_typecheck`) continues to pass without depending on
+ * `vue-tsc` being added to the toolchain.
+ *
+ * The catch-all generics deliberately accept any prop shape — Vitest's
+ * `mount()` and the consuming SFCs supply concrete props at the call
+ * site, and the runtime Vue compiler validates them.
+ */
+
+declare module "*.vue" {
+    import type { DefineComponent } from "vue";
+    const component: DefineComponent<
+        Record<string, unknown>,
+        Record<string, unknown>,
+        unknown
+    >;
+    export default component;
+}

package/src/vue/widget.ts

@@ -0,0 +1,51 @@
+/**
+ * Vue widget registry — custom renderers keyed by `.meta({ component })`
+ * hint.
+ *
+ * Mirrors `react/SchemaComponent.tsx`'s widget surface: a module-level
+ * map storing app-wide widget defaults plus a clear hook used by tests
+ * to isolate state between cases. Scoped registration (per-instance,
+ * per-provider) lives on the corresponding props of the
+ * `<SchemaComponent>` / `<SchemaProvider>` SFCs.
+ *
+ * Resolution order, matching the React adapter: instance → context →
+ * global → resolver → headless.
+ */
+
+import type { VueRenderFunction } from "./types.ts";
+
+/** Global widget registry — app-wide defaults. */
+const globalWidgets = new Map<string, VueRenderFunction>();
+
+/**
+ * Register a widget globally. The widget is resolved when a schema field
+ * has `.meta({ component: name })`.
+ *
+ * For scoped registration, use the `widgets` prop on `<SchemaComponent>`
+ * or `<SchemaProvider>` instead.
+ */
+export function registerWidget(name: string, render: VueRenderFunction): void {
+    globalWidgets.set(name, render);
+}
+
+/**
+ * Look up a widget in the global registry. Used by the Vue dispatcher
+ * after the per-instance and context maps have been checked.
+ */
+export function lookupGlobalWidget(
+    name: string
+): VueRenderFunction | undefined {
+    return globalWidgets.get(name);
+}
+
+/**
+ * Clear every globally registered widget. Intended for test isolation
+ * — `registerWidget` writes to module-level state and that state
+ * otherwise leaks across test cases, making the test suite
+ * order-dependent. Tests should call this from an `afterEach` hook.
+ *
+ * @internal
+ */
+export function __clearGlobalWidgets(): void {
+    globalWidgets.clear();
+}