@json-render/next 0.15.0

package/dist/server.d.ts

@@ -0,0 +1,358 @@
+import * as _json_render_core from '@json-render/core';
+import { Spec } from '@json-render/core';
+export { Spec, StateStore } from '@json-render/core';
+export { ActionFn, Actions, BaseComponentProps, ComponentContext, ComponentFn, Components, EventHandle, SetState, StateModel } from '@json-render/react';
+
+/**
+ * Metadata for Next.js pages and layouts.
+ * Maps to Next.js's Metadata type.
+ */
+interface NextMetadata {
+    /** Page title — string or template config */
+    title?: string | {
+        /** Default title when no child overrides */
+        default: string;
+        /** Template string, use %s for the page title (e.g. "%s | My App") */
+        template?: string;
+        /** Absolute title that ignores parent templates */
+        absolute?: string;
+    };
+    /** Meta description */
+    description?: string;
+    /** Keywords for SEO */
+    keywords?: string[];
+    /** Open Graph metadata */
+    openGraph?: {
+        title?: string;
+        description?: string;
+        images?: string | string[];
+        type?: string;
+        url?: string;
+        siteName?: string;
+        locale?: string;
+    };
+    /** Twitter card metadata */
+    twitter?: {
+        card?: "summary" | "summary_large_image" | "app" | "player";
+        title?: string;
+        description?: string;
+        images?: string | string[];
+        creator?: string;
+        site?: string;
+    };
+    /** Robots directives */
+    robots?: string | {
+        index?: boolean;
+        follow?: boolean;
+    };
+    /** Canonical URL */
+    alternates?: {
+        canonical?: string;
+    };
+    /** Favicon and icons */
+    icons?: string | {
+        icon?: string;
+        apple?: string;
+        shortcut?: string;
+    };
+}
+/**
+ * A route definition within a NextAppSpec.
+ */
+interface NextRouteSpec {
+    /** Page content — standard json-render element tree */
+    page: Spec;
+    /** Per-route metadata for SEO */
+    metadata?: NextMetadata;
+    /** Layout key referencing an entry in NextAppSpec.layouts */
+    layout?: string;
+    /** Loading state element tree (rendered during Suspense) */
+    loading?: Spec;
+    /** Error state element tree */
+    error?: Spec;
+    /** Not-found element tree (for dynamic routes that don't match data) */
+    notFound?: Spec;
+    /** Server-side data loader name (references loaders in createNextApp) */
+    loader?: string;
+    /** Static params for generateStaticParams */
+    staticParams?: Record<string, string>[];
+}
+/**
+ * The full application spec for @json-render/next.
+ *
+ * Describes an entire Next.js application: routes, pages, layouts,
+ * metadata, and server-side data loading.
+ *
+ * Routes are keyed by URL patterns using Next.js conventions:
+ * - `"/"` — exact match
+ * - `"/blog/[slug]"` — dynamic segment
+ * - `"/docs/[...path]"` — catch-all segment
+ * - `"/settings/[[...path]]"` — optional catch-all segment
+ */
+interface NextAppSpec {
+    /** Root-level metadata applied to all routes (layouts can override) */
+    metadata?: NextMetadata;
+    /** Route definitions keyed by URL pattern */
+    routes: Record<string, NextRouteSpec>;
+    /**
+     * Reusable layout element trees. Each layout spec must include a
+     * `Slot` component type where page content will be injected.
+     */
+    layouts?: Record<string, Spec>;
+    /** Global initial state shared across all routes */
+    state?: Record<string, unknown>;
+}
+/**
+ * Result of matching a pathname against the spec's routes.
+ */
+interface MatchedRoute {
+    /** The matched route spec */
+    route: NextRouteSpec;
+    /** The URL pattern that matched (e.g. "/blog/[slug]") */
+    pattern: string;
+    /** Extracted route parameters (e.g. { slug: "hello-world" }) */
+    params: Record<string, string | string[]>;
+}
+/**
+ * Server-side data loader function signature.
+ * Receives route params and returns data to merge into initial state.
+ */
+type LoaderFn = (params: Record<string, string | string[]>) => Promise<Record<string, unknown>> | Record<string, unknown>;
+/**
+ * Options for createNextApp.
+ */
+interface CreateNextAppOptions {
+    /** The application spec */
+    spec: NextAppSpec | (() => NextAppSpec | Promise<NextAppSpec>);
+    /** Server-side data loaders keyed by name */
+    loaders?: Record<string, LoaderFn>;
+}
+/**
+ * Data returned by getPageData for client-side rendering.
+ */
+interface PageData {
+    /** Page element tree spec */
+    spec: Spec;
+    /** Initial state (merged from spec.state, global state, and loader data) */
+    initialState?: Record<string, unknown>;
+    /** Optional layout element tree spec */
+    layoutSpec?: Spec | null;
+}
+/**
+ * The result of createNextApp — exports for Next.js route files.
+ */
+interface NextAppExports {
+    /**
+     * Resolve page data for a given set of params.
+     * Returns null if no route matches (caller should call notFound()).
+     *
+     * Use this in your Server Component page.tsx alongside a client wrapper
+     * that renders PageRenderer:
+     *
+     * ```tsx
+     * // app/[[...slug]]/page.tsx
+     * import { getPageData, generateMetadata, generateStaticParams } from "@/lib/app";
+     * import { WebsiteRenderer } from "./renderer";
+     *
+     * export { generateMetadata, generateStaticParams };
+     *
+     * export default async function Page({ params }) {
+     *   const data = await getPageData({ params });
+     *   if (!data) notFound();
+     *   return <WebsiteRenderer {...data} />;
+     * }
+     * ```
+     */
+    getPageData: (props: {
+        params: Promise<{
+            slug?: string[];
+        }>;
+    }) => Promise<PageData | null>;
+    /** generateMetadata function for page.tsx */
+    generateMetadata: (props: {
+        params: Promise<{
+            slug?: string[];
+        }>;
+    }) => Promise<Record<string, unknown>>;
+    /** generateStaticParams function for page.tsx */
+    generateStaticParams: () => Promise<{
+        slug: string[];
+    }[]>;
+}
+
+/**
+ * Create a fully wired Next.js application from a json-render spec.
+ *
+ * Returns `getPageData`, `generateMetadata`, and `generateStaticParams`
+ * ready to be used in Next.js `[[...slug]]` catch-all routes.
+ *
+ * @example
+ * ```typescript
+ * // lib/app.ts
+ * import { createNextApp } from "@json-render/next/server";
+ *
+ * export const { getPageData, generateMetadata, generateStaticParams } =
+ *   createNextApp({ spec });
+ *
+ * // app/[[...slug]]/page.tsx (Server Component)
+ * import { notFound } from "next/navigation";
+ * import { getPageData, generateMetadata, generateStaticParams } from "@/lib/app";
+ * import { SiteRenderer } from "./renderer";
+ *
+ * export { generateMetadata, generateStaticParams };
+ *
+ * export default async function Page({ params }) {
+ *   const data = await getPageData({ params });
+ *   if (!data) notFound();
+ *   return <SiteRenderer {...data} />;
+ * }
+ *
+ * // app/[[...slug]]/renderer.tsx ("use client")
+ * import { PageRenderer } from "@json-render/next";
+ * export function SiteRenderer(props) {
+ *   return <PageRenderer {...props} />;
+ * }
+ * ```
+ */
+declare function createNextApp(options: CreateNextAppOptions): NextAppExports;
+
+/**
+ * The schema for @json-render/next.
+ *
+ * Defines a multi-page Next.js application structure:
+ * - Spec: Routes with pages, layouts, metadata, loading/error states
+ * - Catalog: Components with props schemas, and optional actions
+ *
+ * This schema is fundamentally different from the React element tree schema.
+ * It's page-based, designed for full Next.js applications with SSR,
+ * routing, and metadata generation.
+ */
+declare const schema: _json_render_core.Schema<{
+    spec: _json_render_core.SchemaType<"object", {
+        /** Root-level metadata applied as defaults */
+        metadata: _json_render_core.SchemaType<"object", {
+            title: _json_render_core.SchemaType<"any", unknown>;
+            description: _json_render_core.SchemaType<"string", unknown>;
+            keywords: _json_render_core.SchemaType<"array", _json_render_core.SchemaType<"string", unknown>>;
+            openGraph: _json_render_core.SchemaType<"any", unknown>;
+            twitter: _json_render_core.SchemaType<"any", unknown>;
+            robots: _json_render_core.SchemaType<"any", unknown>;
+            icons: _json_render_core.SchemaType<"any", unknown>;
+        }>;
+        /** Route definitions keyed by URL pattern */
+        routes: _json_render_core.SchemaType<"record", _json_render_core.SchemaType<"object", {
+            /** Page element tree */
+            page: _json_render_core.SchemaType<"object", {
+                root: _json_render_core.SchemaType<"string", unknown>;
+                elements: _json_render_core.SchemaType<"record", _json_render_core.SchemaType<"object", {
+                    type: _json_render_core.SchemaType<"ref", string>;
+                    props: _json_render_core.SchemaType<"propsOf", string>;
+                    children: _json_render_core.SchemaType<"array", _json_render_core.SchemaType<"string", unknown>>;
+                    visible: _json_render_core.SchemaType<"any", unknown>;
+                }>>;
+                state: _json_render_core.SchemaType<"any", unknown>;
+            }>;
+            /** Per-route metadata */
+            metadata: _json_render_core.SchemaType<"any", unknown>;
+            /** Layout key */
+            layout: _json_render_core.SchemaType<"string", unknown>;
+            /** Loading state element tree */
+            loading: _json_render_core.SchemaType<"any", unknown>;
+            /** Error state element tree */
+            error: _json_render_core.SchemaType<"any", unknown>;
+            /** Not-found element tree */
+            notFound: _json_render_core.SchemaType<"any", unknown>;
+            /** Server-side data loader name */
+            loader: _json_render_core.SchemaType<"string", unknown>;
+            /** Static params for SSG */
+            staticParams: _json_render_core.SchemaType<"any", unknown>;
+        }>>;
+        /** Reusable layout element trees */
+        layouts: _json_render_core.SchemaType<"record", _json_render_core.SchemaType<"object", {
+            root: _json_render_core.SchemaType<"string", unknown>;
+            elements: _json_render_core.SchemaType<"record", _json_render_core.SchemaType<"object", {
+                type: _json_render_core.SchemaType<"ref", string>;
+                props: _json_render_core.SchemaType<"propsOf", string>;
+                children: _json_render_core.SchemaType<"array", _json_render_core.SchemaType<"string", unknown>>;
+                visible: _json_render_core.SchemaType<"any", unknown>;
+            }>>;
+            state: _json_render_core.SchemaType<"any", unknown>;
+        }>>;
+        /** Global initial state */
+        state: _json_render_core.SchemaType<"any", unknown>;
+    }>;
+    catalog: _json_render_core.SchemaType<"object", {
+        /** Component definitions */
+        components: _json_render_core.SchemaType<"map", {
+            props: _json_render_core.SchemaType<"zod", unknown>;
+            slots: _json_render_core.SchemaType<"array", _json_render_core.SchemaType<"string", unknown>>;
+            description: _json_render_core.SchemaType<"string", unknown>;
+            example: _json_render_core.SchemaType<"any", unknown>;
+        }>;
+        /** Action definitions (optional) */
+        actions: _json_render_core.SchemaType<"map", {
+            params: _json_render_core.SchemaType<"zod", unknown>;
+            description: _json_render_core.SchemaType<"string", unknown>;
+        }>;
+    }>;
+}>;
+/**
+ * Type for the Next.js schema
+ */
+type NextSchema = typeof schema;
+/**
+ * Infer the spec type from a catalog
+ */
+type NextSpec<TCatalog> = typeof schema extends {
+    createCatalog: (catalog: TCatalog) => {
+        _specType: infer S;
+    };
+} ? S : never;
+
+/**
+ * Match a pathname against a spec's routes.
+ *
+ * Routes are matched in order of specificity:
+ * 1. Exact/static matches first (most specific)
+ * 2. Dynamic segment matches
+ * 3. Catch-all matches (least specific)
+ * 4. Optional catch-all matches (fallback)
+ *
+ * @returns The matched route with extracted params, or null if no match.
+ */
+declare function matchRoute(spec: NextAppSpec, pathname: string): MatchedRoute | null;
+/**
+ * Convert a Next.js catch-all slug array to a pathname.
+ *
+ * @example
+ * slugToPath(undefined)     // "/"
+ * slugToPath([])            // "/"
+ * slugToPath(["blog"])      // "/blog"
+ * slugToPath(["blog","hi"]) // "/blog/hi"
+ */
+declare function slugToPath(slug: string[] | undefined): string;
+/**
+ * Collect all static params from the spec for generateStaticParams.
+ * Returns params suitable for Next.js [[...slug]] catch-all routes.
+ */
+declare function collectStaticParams(spec: NextAppSpec): {
+    slug: string[];
+}[];
+
+/**
+ * Metadata result compatible with Next.js's Metadata type.
+ * Uses plain objects to avoid importing Next.js types at runtime.
+ */
+type ResolvedMetadata = Record<string, unknown>;
+/**
+ * Resolve metadata for a route by merging global spec metadata
+ * with route-specific metadata.
+ *
+ * Follows Next.js metadata merging semantics:
+ * - Route metadata overrides global metadata for scalar fields
+ * - Title templates from global metadata apply to route titles
+ * - OpenGraph and Twitter fields are shallow-merged
+ */
+declare function resolveMetadata(spec: NextAppSpec, route?: NextRouteSpec | null): ResolvedMetadata;
+
+export { type CreateNextAppOptions, type LoaderFn, type MatchedRoute, type NextAppExports, type NextAppSpec, type NextMetadata, type NextRouteSpec, type NextSchema, type NextSpec, type PageData, type ResolvedMetadata, collectStaticParams, createNextApp, matchRoute, resolveMetadata, schema, slugToPath };