@pilotiq/pilotiq 0.1.0

package/dist/pageData.d.ts

@@ -0,0 +1,778 @@
+/**
+ * Per-page-role data builders. The framework's GET route handlers and
+ * Vike's auto-generated `+data.ts` hooks both call these to produce the
+ * exact props the page renderer needs.
+ *
+ * Why this exists: SSR runs through the rudder router (which calls
+ * `view(...)` and populates `pageContext.viewProps`). SPA navigation only
+ * triggers Vike's `+data` hook — the rudder handler doesn't run, so the
+ * data needs to come from the same builder. Routing both paths through a
+ * single builder keeps them in sync.
+ */
+import type { Pilotiq } from './Pilotiq.js';
+import type { Page } from './Page.js';
+import type { ResourceClass, NavigationBadgeColor } from './Resource.js';
+import type { GlobalClass } from './Global.js';
+import { Element, type ElementMeta } from './schema/Element.js';
+import { type RenderContext, type SchemaContext } from './schema/resolveSchema.js';
+import { Form } from './elements/Form.js';
+import { type GlobalSearchResult } from './search.js';
+import type { ThemeMeta } from './theme/types.js';
+import { type SerializedIcon } from './icons/types.js';
+import type { UserMenuItemMeta } from './UserMenuItem.js';
+import { RelationManager, safeManagerPolicy as safeManagerPolicyImpl, type ManagerCanMethod as ManagerCanMethodType } from './RelationManager.js';
+import { type RenderHookMap, type RenderHookName } from './RenderHook.js';
+import { type PageRole } from './applyPageHooks.js';
+import { type ModelLike } from './orm/modelDefaults.js';
+import { type RelationMode } from './RelationManager.js';
+/**
+ * Top-right user dropdown shipped to the renderer in `viewProps.panel`.
+ * `null` when no `Pilotiq.user(req => …)` resolver is configured or the
+ * resolver returns `null` (no logged-in user) — the renderer suppresses
+ * the dropdown entirely in that case.
+ *
+ * `user.name / user.email / user.avatar` are duck-typed off the
+ * resolver's return value; whichever fields are present round-trip into
+ * the dropdown trigger (initials fall back to the first two letters of
+ * `name` when no avatar URL is set).
+ */
+export interface UserMenuMeta {
+    user: {
+        name?: string;
+        email?: string;
+        avatar?: string;
+    };
+    items: UserMenuItemMeta[];
+    signOut?: {
+        url: string;
+        label: string;
+        method: 'POST' | 'GET';
+    };
+}
+/**
+ * Bell-icon dropdown configuration shipped under `viewProps.panel`. Sparse —
+ * absent when `Pilotiq.databaseNotifications()` wasn't called OR when no
+ * user resolves (anonymous request → no inbox to surface). Renderer mounts
+ * the bell only when this is set.
+ *
+ * Routes are absolute URLs (panel `basePath` already applied). Client
+ * substitutes `:id` per row when calling read / unread; `_widget`-style
+ * params aren't used here because the bell only ever issues these four
+ * fetch shapes.
+ *
+ * `polling` mirrors `DatabaseNotificationsConfig.polling` — `null` ships
+ * over the wire to disable client-side polling. The bell still fetches on
+ * mount + after every mark-read mutation.
+ */
+export interface DatabaseNotificationsMeta {
+    position: 'topbar' | 'sidebar';
+    polling: number | null;
+    pageSize: number;
+    badgeColor: NavigationBadgeColor;
+    trigger?: {
+        icon?: string;
+        label?: string;
+    };
+    listUrl: string;
+    readAllUrl: string;
+    /** Template URL with literal `:id` placeholder. Client replaces. */
+    readUrl: string;
+    /** Template URL with literal `:id` placeholder. Client replaces. */
+    unreadUrl: string;
+    /**
+     * Template URL for the notification-action dispatch endpoint with
+     * literal `:id` and `:actionName` placeholders. Bell client builds
+     * per-action URLs by substituting both at render time. Used only by
+     * `handler`-mode actions; `url` / `post` actions ride their own URL
+     * verbatim.
+     */
+    actionUrl: string;
+    /**
+     * Phase 2 — broadcast hint. Sparse — absent when
+     * `databaseNotifications({ broadcast: true })` wasn't set OR when no
+     * resolved user has an `id` to scope the channel to.
+     *
+     * Client connects to `wsUrl` via `@rudderjs/broadcast`'s
+     * `RudderSocket`, subscribes to the `channel` (already includes the
+     * `private-` prefix), and listens for `event` to trigger refetches.
+     */
+    broadcast?: {
+        wsUrl: string;
+        channel: string;
+        event: string;
+    };
+}
+/**
+ * Right-sidebar shipped under `viewProps.panel.rightSidebar`. Sparse —
+ * absent from `panelInfo()` when no contributions are registered, every
+ * registered contribution failed `canAccess(user)`, or every visible
+ * contribution is `hidden: true`. Renderer mounts the chrome only when
+ * this is set.
+ *
+ * The React component reference for each contribution does NOT travel
+ * here — only its tab-strip metadata. The actual body component is
+ * resolved client-side from the Vite plugin's `_components.ts` manifest
+ * keyed by contribution `id`, mirroring the icon-class round-trip.
+ *
+ * `defaultWidth` rolls up: contribution-level value when one
+ * contribution was registered with one, otherwise the panel-level
+ * baseline (`RIGHT_PANEL_DEFAULT_WIDTH`). Client also clamps
+ * localStorage values to `[minWidth, maxWidth]`.
+ */
+export interface RightPanelMeta {
+    id: string;
+    label: string;
+    icon?: SerializedIcon;
+    defaultWidth: number;
+}
+export interface RightSidebarMeta {
+    panels: RightPanelMeta[];
+    defaultWidth: number;
+    minWidth: number;
+    maxWidth: number;
+}
+/**
+ * Single nav-tree entry. `name` is the JS class name (`R.name` /
+ * `G.name` / `P.name`) — also the lookup key into the build-time
+ * `_components.ts` manifest the Vite plugin emits, so component-typed
+ * icons resolve from the same identifier.
+ */
+export interface NavItem {
+    name: string;
+    label: string;
+    url: string;
+    icon?: SerializedIcon;
+    group?: string;
+    sort?: number;
+    badge?: string;
+    badgeColor?: NavigationBadgeColor;
+    children?: NavItem[];
+}
+/**
+ * Build the panel header summary + the unified navigation tree.
+ *
+ * Pipeline:
+ *   1. flatten resources + globals + pages into raw NavItem records
+ *   2. drop items whose `canAccess(user)` (Plan #10) returns false
+ *   3. resolve `navigationParentItem` references → nest under parents
+ *      (cycles broken with a console warn; dangling parents render at top level)
+ *   4. sort within each grouping (top-level *and* every parent's children)
+ *      by `navigationSort` ascending → registration order
+ *   5. resolve every `navigationBadge()` in parallel via `Promise.all`;
+ *      handler errors are swallowed (badge omitted) so a flaky count
+ *      never blanks the page
+ *
+ * `req` is the active request; pilotiq calls `pilotiq.resolveUser(req)`
+ * once and threads the user into every Resource/Global/Page `canAccess`
+ * check. When `Pilotiq.user(fn)` isn't configured, user is `null` and the
+ * default `canAccess` returns true → no items dropped.
+ */
+/**
+ * Optional route-context for `panelInfo()`. When set, render-hook
+ * `scope: { resource | page | global }` filters fire correctly for the
+ * active route. Missing keys mean the slot has no scope-able identifier
+ * (chrome-only routes); scope-less hooks still fire either way.
+ *
+ * `url` defaults to `cfg.path` when unset. `recordId` rides through to
+ * `RenderHookContext.recordId` for hooks that need it.
+ */
+export interface PanelInfoRoute {
+    resource?: ResourceClass;
+    page?: typeof Page;
+    global?: GlobalClass;
+    recordId?: string;
+    url?: string;
+}
+export declare function panelInfo(pilotiq: Pilotiq, req?: unknown, route?: PanelInfoRoute): Promise<{
+    renderHooks?: Partial<Record<RenderHookName, ElementMeta[]>>;
+    rightSidebar?: RightSidebarMeta;
+    databaseNotifications?: DatabaseNotificationsMeta;
+    userMenu?: UserMenuMeta;
+    name: string;
+    branding: {
+        title?: string;
+        logo?: string;
+    };
+    navigation: NavItem[];
+    theme: ThemeMeta | undefined;
+    themeEditor: boolean;
+}>;
+/**
+ * Resolve a subset of page-role render hooks (e.g. `panels::page.start`
+ * + the list-records / create-record / view-record / edit-record /
+ * global-search slot families). Per-page-role data builders call this
+ * after schema resolution and stamp the result on `viewProps.renderHooks`.
+ *
+ * `names` lets each builder declare exactly which slots it serves so a
+ * list-page builder doesn't ship slots that only fire on the edit page.
+ */
+/**
+ * Per-builder one-shot — resolve the role's slot set + splice the
+ * results into the resolved schema. Wraps the two steps a per-builder
+ * data fn always does in lockstep:
+ *
+ *   1. `resolvePageHooks(pilotiq, user, pageHooksFor(role), route)`
+ *   2. `applyPageHooks(schemaData, hooks, role)`
+ *
+ * Returns the wrapped `ElementMeta[]`. No-op when the panel has no
+ * registered hooks. Pass through what you'd pass to `panelInfo()`'s
+ * route arg — same shape.
+ */
+export declare function applyRoleHooks(pilotiq: Pilotiq, user: unknown, role: PageRole, schemaData: ElementMeta[], route?: PanelInfoRoute): Promise<ElementMeta[]>;
+export declare function resolvePageHooks(pilotiq: Pilotiq, user: unknown, names: readonly RenderHookName[], route: PanelInfoRoute): Promise<RenderHookMap>;
+export declare function callPageSchema(PageClass: typeof Page, ctx: SchemaContext): Promise<Element[]>;
+/** Mark every Form on the page with its action URL so the rendered <form> posts to itself. */
+export declare function tagFormActions(elements: ReadonlyArray<Element>, action: string): void;
+/**
+ * Plan #5 — stamp the partial-resolve endpoint URL on every form whose
+ * descendants include at least one `live()` field. The client uses
+ * `FormMeta.stateUrl` to flip into controlled-state mode; forms without
+ * any live fields stay uncontrolled (zero-cost legacy path).
+ *
+ * `urlBuilder(formId)` lets the caller compose a per-form URL — the
+ * endpoint shape is `${base}/${slug}/_form/${formId}/state` so each
+ * form on a multi-form page gets its own route segment.
+ */
+export declare function tagFormStateUrls(elements: ReadonlyArray<Element>, urlBuilder: (formId: string) => string): void;
+/**
+ * Reorderable rows — stamp the POST-reorder URL on every `Table` that
+ * has `Table.reorderable()` set. The renderer reads `TableMeta.reorderUrl`
+ * to wire the drop handler; tables that aren't reorderable skip wiring
+ * entirely. Same shape as `tagFormStateUrls` so the call site stays
+ * consistent.
+ */
+export declare function tagTableReorderUrls(elements: ReadonlyArray<Element>, url: string): void;
+export declare function tagTableDeferred(elements: ReadonlyArray<Element>, url: string): void;
+/**
+ * Editable cell columns — walk every table on the page and stamp
+ * `_cellEditUrls[colName]` per row, but only on rows that already
+ * carry a `_cellEditable[colName]` marker (set by `loadTableRecords`
+ * after `R.canEdit(user, row)` passed). The dispatcher stays
+ * URL-shape-agnostic; URL building lives here parallel to
+ * `tagFormStateUrls / tagTableReorderUrls`.
+ *
+ * `idOf` extracts the per-row primary key. Defaults to reading `id` —
+ * works for the rudder ORM convention. Resources with a different
+ * primary-key column should pass an override (none in v1).
+ */
+export declare function tagCellEditUrls(elements: ReadonlyArray<Element>, resourceUrl: string, idOf?: (row: Record<string, unknown>) => unknown): void;
+/**
+ * Plan #8 — stamp the wizard step-validate endpoint URL on every form
+ * whose descendants include a `Wizard` element. `FormMeta.wizardUrl` is
+ * what the client posts to on Next-button clicks; forms without a wizard
+ * descendant skip wiring.
+ */
+export declare function tagFormWizardUrls(elements: ReadonlyArray<Element>, urlBuilder: (formId: string) => string): void;
+/**
+ * Audit row 2026-05-07 cont'd⁸ — stamp the inline-create-option endpoint
+ * URL on every `SelectField` that has called `createOptionForm()`. Walks
+ * every form on the page so the URL carries the parent form's id; URL
+ * shape `${formScopeUrl}/_form/${formId}/create-option/${fieldName}` so
+ * the route handler can pick the form by id and the field by name.
+ *
+ * Mirrors `tagFormStateUrls / tagFormWizardUrls` — operates on the
+ * un-resolved Element tree, mutates field-instance state via
+ * `field.withCreateOptionUrl(url)`, and the field's `toMeta()` reads it
+ * back to emit `createOption.url`.
+ *
+ * Stops at Repeater / Builder boundaries (parallel to the form-state /
+ * wizard walkers): inside-row schemas are dispatched per-row and the
+ * createOption shape doesn't compose with row body coercion in v1.
+ */
+export declare function tagSelectCreateOptionUrls(elements: ReadonlyArray<Element>, urlBuilder: (formId: string, fieldName: string) => string): void;
+export declare function tagRichTextMentionUrls(elements: ReadonlyArray<Element>, urlBuilder: (formId: string) => string): void;
+/**
+ * Run the edit-mode fill pipeline on a loaded record:
+ *   mutateFormDataBeforeFill  →  fillFromRecord  →  mutateFormDataAfterFill
+ *
+ * `fillFromRecord` defaults to `{ ...record }` when not configured. Both
+ * mutators are optional and may be async. `ctx.record` is the loaded
+ * record so mutators can read from fields the form doesn't surface.
+ */
+export declare function applyFillPipeline<R>(form: Form<R>, record: R): Promise<Record<string, unknown>>;
+/**
+ * Walk the form's top-level Repeaters and replace `values[fieldName]`
+ * with rows fetched from `parent.related(name)` for any
+ * relationship-backed Repeater. Each loaded row stamps `__id` to the
+ * child's primary key so the renderer can round-trip identity through
+ * a hidden input and the save-side diff can match submitted rows back
+ * to existing records.
+ *
+ * No-op when the parent record is null (create mode), when no
+ * relationship-backed Repeaters exist on the form, or when the
+ * resource has no `R.model` (relation queries need it).
+ *
+ * Mutates and returns a fresh values object — never the input.
+ */
+export declare function applyRelationshipRepeaterFill(form: Form, values: Record<string, unknown>, record: unknown, parentModel: ModelLike | undefined): Promise<Record<string, unknown>>;
+/**
+ * Walk the form's top-level Builders and replace `values[fieldName]` with
+ * rows fetched from `parent.related(name)` for any relationship-backed
+ * Builder. Each loaded row stamps `__id` (child PK) + `type` (block
+ * discriminator) + `data` (per-block JSON payload) so the renderer can
+ * round-trip the heterogeneous envelope.
+ *
+ * Mirrors `applyRelationshipRepeaterFill`. No-op when the parent record
+ * is null (create mode), the resource has no `R.model`, or no
+ * relationship-backed Builders exist on the form.
+ */
+export declare function applyRelationshipBuilderFill(form: Form, values: Record<string, unknown>, record: unknown, parentModel: ModelLike | undefined): Promise<Record<string, unknown>>;
+/** Wire-shape of the per-widget data map shipped to the client.
+ *  Lazy elements stamp `null` (renderer paints skeleton + fetches);
+ *  eager elements stamp their resolved payload. Errors stamp
+ *  `{ error: '<message>' }` so the renderer can surface a per-widget
+ *  failure without blanking the page. */
+export type ServerDataMap = Record<string, unknown>;
+/**
+ * Plan #15 — collect every `ServerDataElement` in the schema tree and
+ * resolve their `getServerData(ctx)` payloads in parallel. Returns a
+ * map keyed by element id, ready to ship as `viewProps._widgetData`.
+ *
+ * Lazy elements (default — `lazy(false)` opts out) skip the hook and
+ * stamp `null` so the renderer paints a skeleton and fetches the
+ * payload via `POST {base}/_widget/:id` on mount. Eager elements
+ * resolve synchronously and ship the data with the page.
+ *
+ * Per-widget errors are caught and surfaced as `{ error: '...' }` —
+ * one flaky `getStats()` shouldn't 500 the entire dashboard.
+ *
+ * Visibility is **not** re-evaluated here. The schema resolver
+ * (`resolveSchema → evaluateVisibility`) drops hidden layout elements
+ * before any widget code runs. Widgets inside still-rendered branches
+ * always resolve (or stamp lazy null).
+ */
+export declare function resolveServerDataElements(elements: ReadonlyArray<Element>, ctx: RenderContext): Promise<ServerDataMap>;
+/**
+ * Plan #15 — stamp the polling-endpoint URL on every `ServerDataElement`
+ * in the tree. Mirrors `tagFormStateUrls / tagTableReorderUrls`. Walks
+ * with the same boundaries as `collectServerDataElements` so the wire
+ * stays in sync (no orphan widgets without URLs and vice versa).
+ *
+ * `urlBuilder(id)` typically produces `${base}/_widget/${id}` for
+ * dashboard widgets and `${base}/${pageSlug}/_widget/${id}` for
+ * custom-page widgets — the route handlers for both shapes are wired up
+ * in `routes.ts` (see Phase A.4).
+ */
+export declare function tagWidgetUrls(elements: ReadonlyArray<Element>, urlBuilder: (id: string) => string): void;
+/** Stamp dispatchUrl on every handler-style Action so the client knows where to POST. */
+export declare function tagActionDispatch(elements: ReadonlyArray<Element>, baseUrl: string): void;
+export declare function dashboardData(pilotiq: Pilotiq, req?: unknown): Promise<Record<string, unknown>>;
+export declare function resourceIndexData(pilotiq: Pilotiq, slug: string, query?: Record<string, string>, req?: unknown): Promise<Record<string, unknown> | null>;
+export declare function resourceTableData(pilotiq: Pilotiq, slug: string, query?: Record<string, string>, req?: unknown): Promise<{
+    tables: Record<string, unknown>[];
+} | null>;
+/**
+ * Walk the schema for `ListTabs` containers, pick the active tab from
+ * `?tab=…` (defaulting to the tab marked `.default()` or the first one),
+ * stamp render-time state (`active` flag, per-tab `?tab=` URL, and
+ * resolved badge counts) onto each tab. The active tab's query/context
+ * modifier is NOT applied here — `loadTableRecords` walks for the active
+ * tab and splices in its modifier when it builds the records-handler
+ * `TableContext`.
+ *
+ * No-op when the page has no `ListTabs`.
+ */
+export declare function resolveActiveTab(elements: ReadonlyArray<Element>, query: Record<string, string>, currentPath: string): Promise<void>;
+export declare function resourceCreateData(pilotiq: Pilotiq, slug: string, prefill?: {
+    values?: Record<string, unknown>;
+    errors?: Record<string, string[]>;
+}, req?: unknown): Promise<Record<string, unknown> | null>;
+export declare function resourceEditData(pilotiq: Pilotiq, slug: string, recordId: string, prefill?: {
+    values?: Record<string, unknown>;
+    errors?: Record<string, string[]>;
+}, req?: unknown): Promise<Record<string, unknown> | null>;
+/**
+ * Plan #11 — three scopes a single relation-manager URL space resolves to:
+ *
+ *   list:    GET    {base}/{slug}/:id/{rel}
+ *   create:  GET    {base}/{slug}/:id/{rel}/create
+ *   edit:    GET    {base}/{slug}/:id/{rel}/{childId}/edit
+ *
+ * Each carries enough state for `relationManagerData` to load the right
+ * parent + (for edit) child + form/table context. Submit-side handlers
+ * live in `routes.ts` and reuse `dispatchFormSubmit`.
+ */
+export type RelationManagerScope = {
+    kind: 'relation-list';
+    slug: string;
+    recordId: string;
+    relationship: string;
+    query?: Record<string, string>;
+} | {
+    kind: 'relation-create';
+    slug: string;
+    recordId: string;
+    relationship: string;
+    prefill?: {
+        values?: Record<string, unknown>;
+        errors?: Record<string, string[]>;
+    };
+} | {
+    kind: 'relation-view';
+    slug: string;
+    recordId: string;
+    relationship: string;
+    childId: string;
+} | {
+    kind: 'relation-edit';
+    slug: string;
+    recordId: string;
+    relationship: string;
+    childId: string;
+    prefill?: {
+        values?: Record<string, unknown>;
+        errors?: Record<string, string[]>;
+    };
+} | {
+    kind: 'nested-relation-list';
+    slug: string;
+    chain: [RelationChainStep, RelationChainStep];
+    query?: Record<string, string>;
+} | {
+    kind: 'nested-relation-create';
+    slug: string;
+    chain: [RelationChainStep, RelationChainStep];
+    prefill?: {
+        values?: Record<string, unknown>;
+        errors?: Record<string, string[]>;
+    };
+} | {
+    kind: 'nested-relation-view';
+    slug: string;
+    chain: [RelationChainStep, RelationChainStep];
+    childId: string;
+} | {
+    kind: 'nested-relation-edit';
+    slug: string;
+    chain: [RelationChainStep, RelationChainStep];
+    childId: string;
+    prefill?: {
+        values?: Record<string, unknown>;
+        errors?: Record<string, string[]>;
+    };
+};
+/** Phase B — one parent layer in a nested-resources URL chain. The list
+ *  of these identifies a path through the manager tree:
+ *    `[ { recordId: '123', relationship: 'comments' } ]` picks comment
+ *    "456 under post 123" when paired with `childId: '456'`. */
+export interface RelationChainStep {
+    recordId: string;
+    relationship: string;
+}
+/**
+ * Failure outcomes the data builder discriminates back to the route
+ * handler, which decides between 403 / 404 / HTML / JSON shapes.
+ *
+ *   `null`            — unknown panel / parent / manager / child;
+ *                        route returns 404
+ *   `{ ok: false, status: 403 }` — policy denied; route returns 403
+ *
+ * Success returns the schemaData payload directly (a record, not
+ * tagged) for parity with `resourceIndexData / resourceCreateData`.
+ */
+export type RelationManagerResult = Record<string, unknown> | {
+    ok: false;
+    status: 403;
+} | null;
+/**
+ * Discover the related Resource for a manager. Order:
+ *   1. `M.relatedResource` explicit override (skip discovery).
+ *   2. Rudder ORM convention: walk
+ *      `R.model.relations[manager.relationship].model()` and find
+ *      `cfg.resources[i].model === relatedModel`.
+ *   3. Otherwise undefined — caller must error or fall back.
+ *
+ * A returned Resource is the one whose `model` backs the related
+ * table. Callers use it for `Related.model.find(childId)`,
+ * `Related.canEdit(user, child)`, and the auto-wired form save handler.
+ */
+export declare function findRelatedResource(M: typeof RelationManager, R: ResourceClass, cfg: ReturnType<Pilotiq['getConfig']>): ResourceClass | undefined;
+/** Plan #11 — authorization predicate names a `RelationManager` carries.
+ *  Re-exported from `RelationManager.ts`. */
+export type ManagerCanMethod = ManagerCanMethodType;
+/** Plan #11 — authorize a relation-manager action with sensible defaults.
+ *  Re-exported from `RelationManager.ts` so external callers (route
+ *  handlers, third-party plugins) keep their existing import path. */
+export declare const safeManagerPolicy: typeof safeManagerPolicyImpl;
+/**
+ * Plan #11 — render data for the three relation-manager URL scopes.
+ * Mirrors the resource* builders' shape so routes and Vike +data hooks
+ * consume identical props. Authorization runs inline (parent
+ * `canAccess + canEdit(parent)` then manager-scoped predicate); IDOR
+ * check on `relation-edit` runs against the parent's relation query.
+ *
+ * Returns:
+ *   - `null` when panel / parent / manager / child don't exist.
+ *   - `{ ok: false, status: 403 }` when authorization denies.
+ *   - the props record on success (route picks SSR view / SPA prop
+ *     downstream).
+ */
+export declare function relationManagerData(pilotiq: Pilotiq, scope: RelationManagerScope, req?: unknown): Promise<RelationManagerResult>;
+/**
+ * Phase B — narrow `scope` discriminator for nested-relation-*. Lets
+ * the helpers below avoid restating the union for every parameter.
+ */
+type NestedRelationScope = Extract<RelationManagerScope, {
+    kind: `nested-relation-${string}`;
+}>;
+/**
+ * Phase B — chain walk result. Resolved layer-by-layer in
+ * `resolveRelationChain`; nested builders consume it. Failures bubble
+ * up as the same `{ ok: false, status: 403 }` / `null` shape the
+ * depth-1 path uses.
+ */
+export interface ResolvedChain {
+    R: ResourceClass;
+    parentRecord: unknown;
+    M1: typeof RelationManager;
+    Related1: ResourceClass;
+    child1: unknown;
+    child1Mode: RelationMode;
+    M2: typeof RelationManager;
+    Related2: ResourceClass | undefined;
+    child2Mode: RelationMode;
+}
+/**
+ * Phase B — resolve a depth-2 chain, running every auth + IDOR layer:
+ *   Layer 0 — top-level Resource: cluster gate, R.canAccess.
+ *   Layer 1 — parent record: R.canEdit(parent) (Phase A gate to manage relations).
+ *   Layer 2 — first manager M1: relationship discovered, related resource discovered.
+ *   IDOR #1 — child1 (the leaf parent) must belong to parentRecord under chain[0].relationship.
+ *   Layer 3 — M1.canView(child1, parent) (Filament-style: must be allowed
+ *             to view the child to drill into its sub-relations).
+ *   Layer 4 — second manager M2 lookup; relation type read off Related1.model.
+ *
+ * The leaf manager's per-scope predicate (canViewAny / canCreate /
+ * canView / canEdit) runs inside the per-scope builders below, since
+ * each predicate has different arguments.
+ */
+export declare function resolveRelationChain(pilotiq: Pilotiq, scope: NestedRelationScope, user: unknown): Promise<ResolvedChain | {
+    ok: false;
+    status: 403;
+} | null>;
+export type FormStateScope = {
+    kind: 'resource-create';
+    slug: string;
+} | {
+    kind: 'resource-edit';
+    slug: string;
+    recordId: string;
+} | {
+    kind: 'global-edit';
+    slug: string;
+} | {
+    kind: 'page';
+    pageSlug: string;
+};
+export interface FormStateRequest {
+    formId: string;
+    changed: string;
+    values: Record<string, unknown>;
+}
+export interface FormStateResult {
+    ok: true;
+    form: Record<string, unknown>;
+    dirty: string[];
+}
+export interface FormStateError {
+    ok: false;
+    status: 404 | 422;
+    error: string;
+}
+/**
+ * Plan #5 — handle a partial-resolve roundtrip from a `live()` field.
+ *
+ * Locates the page's schema, finds the targeted form by `formId`, runs
+ * `applyStateUpdate` to apply the changed value + run
+ * `afterStateUpdated`, then re-resolves the form's children with the
+ * mutated values + bound `$get / $set` so dependent options /
+ * conditional visibility re-evaluate. Returns the resolved FormMeta the
+ * client uses to replace its rendered form.
+ *
+ * Returns `null` when the route prefix doesn't resolve to a real
+ * resource/global/page — the route handler turns this into a 404. The
+ * inner `{ status: 422 }` failure is for "form found but `changed`
+ * field doesn't exist on it" — also a client-side bug.
+ */
+export declare function formStateData(pilotiq: Pilotiq, scope: FormStateScope, body: FormStateRequest, req?: unknown): Promise<FormStateResult | FormStateError | null>;
+export interface FormWizardRequest {
+    formId: string;
+    step: number;
+    values: Record<string, unknown>;
+}
+export interface FormWizardSuccess {
+    ok: true;
+}
+export interface FormWizardFailure {
+    ok: false;
+    status: 404 | 422;
+    error?: string;
+    errors?: Record<string, string[]>;
+}
+/**
+ * Plan #8 — handle a Wizard step-validate POST. Locates the form by id,
+ * walks to the Wizard descendant, validates only the fields inside step
+ * `step` against `values`. Returns `{ ok: true }` on success or
+ * `{ ok: false, status: 422, errors }` when fields fail validation.
+ *
+ * Errors are keyed by field name, same shape as the form-submit 422 path,
+ * so the client (`FormStateApi.applyErrors`) can surface them in-place.
+ */
+export declare function formWizardData(pilotiq: Pilotiq, scope: FormStateScope, body: FormWizardRequest, req?: unknown): Promise<FormWizardSuccess | FormWizardFailure | null>;
+export interface FormCreateOptionRequest {
+    formId: string;
+    fieldName: string;
+    values: Record<string, unknown>;
+}
+export interface FormCreateOptionSuccess {
+    ok: true;
+    option: {
+        value: string;
+        label: string;
+    };
+}
+export interface FormCreateOptionFailure {
+    ok: false;
+    status: 403 | 404 | 422 | 500;
+    error?: string;
+    errors?: Record<string, string[]>;
+}
+/**
+ * Audit row 2026-05-07 cont'd⁸ — handle a `SelectField.createOptionForm()`
+ * modal submit. Locates the parent form by `formId`, finds the SelectField
+ * by `fieldName`, re-evaluates the `createOptionAuthorize` rule (so a
+ * tampered URL can't bypass), coerces + validates the body against the
+ * sub-form's fields, then calls `createOptionUsing(handler)` and returns
+ * `{ option }` for the client to append + select.
+ *
+ * Returns `null` when the route prefix doesn't resolve to a real
+ * resource/global/page (route handler turns into 404).
+ */
+export declare function formCreateOptionData(pilotiq: Pilotiq, scope: FormStateScope, body: FormCreateOptionRequest, req?: unknown): Promise<FormCreateOptionSuccess | FormCreateOptionFailure | null>;
+export interface MentionResolveRequest {
+    formId: string;
+    field: string;
+    trigger: string;
+    query: string;
+}
+/** Wire-side shape for a single resolved item — mirrors `MentionItem` from
+ *  `@pilotiq/tiptap`. Pilotiq core doesn't import that package, so the
+ *  duck-typed shape lives here. */
+export interface MentionResolveItem {
+    id: string;
+    label: string;
+    group?: string;
+}
+export interface MentionResolveSuccess {
+    ok: true;
+    items: MentionResolveItem[];
+}
+export interface MentionResolveError {
+    ok: false;
+    status: 404 | 422;
+    error: string;
+}
+/**
+ * Resolve one async-mention round-trip. Locates the page's schema, finds
+ * the form by `formId` and the RichTextField by `field`, calls its
+ * `resolveMention(trigger, query, ctx)`. Returns `{ ok, items }`, a 404
+ * when the form / field / trigger isn't present, or `null` for a missing
+ * page (the route handler turns `null` into a 404 too).
+ *
+ * The dispatcher is duck-typed against the contract in `@pilotiq/tiptap`'s
+ * `RichTextField` — pilotiq core never imports the adapter. Any future
+ * field-type that ships an async-resolve trigger can implement the same
+ * shape and pick up routing for free.
+ */
+export declare function mentionResolveData(pilotiq: Pilotiq, scope: FormStateScope, body: MentionResolveRequest, req?: unknown): Promise<MentionResolveSuccess | MentionResolveError | null>;
+export declare function resourceViewData(pilotiq: Pilotiq, slug: string, recordId: string, req?: unknown): Promise<Record<string, unknown> | null>;
+export declare function globalEditData(pilotiq: Pilotiq, slug: string, prefill?: {
+    values?: Record<string, unknown>;
+    errors?: Record<string, string[]>;
+}, req?: unknown): Promise<Record<string, unknown> | null>;
+export declare function globalViewData(pilotiq: Pilotiq, slug: string, req?: unknown): Promise<Record<string, unknown> | null>;
+export declare function customPageData(pilotiq: Pilotiq, pageSlug: string, req?: unknown): Promise<Record<string, unknown> | null>;
+/**
+ * Scopes the polling endpoint resolves against. Mirrors the
+ * form-state / wizard scope discriminator.
+ *
+ *   panel:    dashboard page (`POST {base}/_widget/:id`)
+ *   page:     custom page    (`POST {base}/{pageSlug}/_widget/:id`)
+ *   resource: list page      (`POST {base}/{slug}/_widget/:id`) —
+ *             resolves the resource's index `Page.schema()` so widgets
+ *             from `Resource.headerSchema()` / `footerSchema()` are
+ *             reachable. Auth runs `R.canAccess + R.canViewAny` in
+ *             front of the per-widget visibility check.
+ */
+export type WidgetScope = {
+    kind: 'panel';
+} | {
+    kind: 'page';
+    pageSlug: string;
+} | {
+    kind: 'resource';
+    slug: string;
+};
+export interface WidgetRequest {
+    id: string;
+    filter?: string;
+}
+export interface WidgetSuccess {
+    ok: true;
+    data: unknown;
+    timestamp: number;
+}
+export interface WidgetFailure {
+    ok: false;
+    status: 403 | 404 | 500;
+    error: string;
+}
+/**
+ * Plan #15 — re-resolve the active page's schema, find the widget by
+ * id, fail-closed via `evaluateVisibility`, then run
+ * `resolveServerData(ctx)` and return the payload.
+ *
+ *   - 404 when the page or widget id doesn't exist.
+ *   - 403 when the layout-level `visible(rule)` says the widget is
+ *     hidden (server doesn't show data for hidden surfaces).
+ *   - 500 when the hook itself throws.
+ *
+ * `body.filter` rides along on `RenderContext.filter` so per-chart
+ * filter dropdowns can re-fetch with the new filter value. Treated as
+ * an opaque string — widget hooks decode it however they want.
+ */
+export declare function widgetData(pilotiq: Pilotiq, scope: WidgetScope, body: WidgetRequest, req?: unknown): Promise<WidgetSuccess | WidgetFailure>;
+/**
+ * Resolve the user via `pilotiq.resolveUser(req)` and run the
+ * panel-wide search. Mirrors the formStateData/formWizardData
+ * shape so the `/_search` route handler stays a thin wrapper.
+ *
+ * Also resolves the `panels::global-search.results.before/.after`
+ * render hooks when the panel registered any — sparse, absent when
+ * neither slot has registered fns. Sent as a `RenderHookMap` so the
+ * client `<CommandPalette>` can mount `<RenderHookSlot>` above and
+ * below the result list (same pattern chrome slots use).
+ */
+export declare function searchData(pilotiq: Pilotiq, query: string, req?: unknown): Promise<{
+    ok: true;
+    results: GlobalSearchResult[];
+    renderHooks?: RenderHookMap;
+}>;
+export interface PageContextLike {
+    urlPathname?: string;
+    urlOriginal?: string;
+    urlParsed?: {
+        search?: Record<string, string>;
+        searchOriginal?: string;
+    };
+    routeParams?: Record<string, string | undefined>;
+    pageId?: string;
+}
+/**
+ * Single entry point Vike's `+data` hook calls. Inspects the page id and
+ * route params, finds the panel via `PilotiqRegistry`, and dispatches to
+ * the matching builder. Returns the same shape SSR's `viewProps` carries.
+ */
+export declare function dispatchPageData(pageContext: PageContextLike): Promise<unknown | null>;
+export {};
+//# sourceMappingURL=pageData.d.ts.map