@olonjs/core 1.0.120 → 1.0.122

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ClassValue } from 'clsx';
 import { Component } from 'react';
+import { Context } from 'react';
 import { default as default_2 } from 'react';
 import { ErrorInfo } from 'react';
 import { JSX } from 'react/jsx-runtime';
@@ -118,6 +119,14 @@ export declare interface AssetsConfig {
     onAssetUpload?: (file: File) => Promise<string>;
 }
 
+export declare const BaseArrayItem: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+}, {
+    id?: string | undefined;
+}>;
+
 export declare interface BaseSection<K extends keyof SectionDataRegistry> {
     id: string;
     type: K;
@@ -125,6 +134,21 @@ export declare interface BaseSection<K extends keyof SectionDataRegistry> {
     settings?: K extends keyof SectionSettingsRegistry ? SectionSettingsRegistry[K] : BaseSectionSettings;
 }
 
+/**
+ * Base schemas shared by section capsules (CIP governance).
+ * Capsules extend these for consistent anchorId, array items, and settings.
+ */
+export declare const BaseSectionData: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    anchorId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id?: string | undefined;
+    anchorId?: string | undefined;
+}, {
+    id?: string | undefined;
+    anchorId?: string | undefined;
+}>;
+
 /**
  * KERNEL: The Base Contract (MTRP)
  * Core is self-contained; structural types live here.
@@ -133,6 +157,23 @@ export declare interface BaseSectionSettings {
     [key: string]: unknown;
 }
 
+export declare const BaseSectionSettingsSchema: z.ZodObject<{
+    paddingTop: z.ZodDefault<z.ZodEnum<["none", "sm", "md", "lg", "xl", "2xl"]>>;
+    paddingBottom: z.ZodDefault<z.ZodEnum<["none", "sm", "md", "lg", "xl", "2xl"]>>;
+    theme: z.ZodDefault<z.ZodEnum<["dark", "light", "accent"]>>;
+    container: z.ZodDefault<z.ZodEnum<["boxed", "fluid"]>>;
+}, "strip", z.ZodTypeAny, {
+    paddingTop: "none" | "sm" | "lg" | "md" | "xl" | "2xl";
+    paddingBottom: "none" | "sm" | "lg" | "md" | "xl" | "2xl";
+    theme: "dark" | "light" | "accent";
+    container: "boxed" | "fluid";
+}, {
+    paddingTop?: "none" | "sm" | "lg" | "md" | "xl" | "2xl" | undefined;
+    paddingBottom?: "none" | "sm" | "lg" | "md" | "xl" | "2xl" | undefined;
+    theme?: "dark" | "light" | "accent" | undefined;
+    container?: "boxed" | "fluid" | undefined;
+}>;
+
 /**
  * Shared types between Admin Engine and Input Registry.
  */
@@ -145,7 +186,7 @@ export declare interface BaseWidgetProps<T = unknown> {
 
 declare function buildLlmsTxt(input: BuildSiteManifestInput): string;
 
-declare function buildPageContract({ slug, pageConfig, schemas, siteConfig, }: BuildPageContractInput): OlonJsPageContract;
+declare function buildPageContract({ slug, pageConfig, schemas, submissionSchemas, siteConfig, }: BuildPageContractInput): OlonJsPageContract;
 
 export declare function buildPageContractHref(slug: string): string;
 
@@ -153,6 +194,7 @@ declare interface BuildPageContractInput {
     slug: string;
     pageConfig: PageConfig;
     schemas: JsonPagesConfig['schemas'];
+    submissionSchemas?: JsonPagesConfig['submissionSchemas'];
     siteConfig: SiteConfig;
 }
 
@@ -162,11 +204,12 @@ export declare function buildPageManifestHref(slug: string): string;
 
 declare function buildSelectionPath(root: HTMLElement, sectionEl: HTMLElement): SelectionPath;
 
-declare function buildSiteManifest({ pages, schemas, siteConfig, }: BuildSiteManifestInput): OlonJsSiteManifestIndex;
+declare function buildSiteManifest({ pages, schemas, submissionSchemas, siteConfig, }: BuildSiteManifestInput): OlonJsSiteManifestIndex;
 
 declare interface BuildSiteManifestInput {
     pages: Record<string, PageConfig>;
     schemas: JsonPagesConfig['schemas'];
+    submissionSchemas?: JsonPagesConfig['submissionSchemas'];
     siteConfig: SiteConfig;
 }
 
@@ -207,7 +250,6 @@ export declare namespace contract {
         PageMeta,
         PageConfig,
         SiteIdentity,
-        SitePageEntry,
         SiteConfig,
         ThemeTokenMap,
         ThemeColors,
@@ -252,8 +294,39 @@ export declare function createWebMcpSaveToolInputSchema(): Record<string, unknow
 
 export declare function createWebMcpToolInputSchema(): Record<string, unknown>;
 
+export declare const CtaSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    label: z.ZodString;
+    href: z.ZodString;
+    variant: z.ZodDefault<z.ZodEnum<["primary", "secondary", "accent"]>>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    href: string;
+    variant: "accent" | "primary" | "secondary";
+    id?: string | undefined;
+}, {
+    label: string;
+    href: string;
+    id?: string | undefined;
+    variant?: "accent" | "primary" | "secondary" | undefined;
+}>;
+
 export declare const DefaultNotFound: default_2.FC;
 
+export declare const DEPLOY_STEPS: readonly DeployStep[];
+
+export declare type DeployPhase = 'idle' | 'running' | 'done' | 'error';
+
+export declare interface DeployStep {
+    id: StepId;
+    label: string;
+    verb: string;
+    poem: [string, string];
+    color: string;
+    glyph: string;
+    duration: number;
+}
+
 /**
  * Engine-level error boundary: prevents black screen on any render error
  * and surfaces a visible error UI.
@@ -305,6 +378,28 @@ declare interface FormFactoryProps {
     } | null) => void;
 }
 
+export declare interface FormState {
+    status: FormStatus;
+    message: string;
+}
+
+export declare type FormStatus = 'idle' | 'submitting' | 'success' | 'error';
+
+/**
+ * Image picker field: object { url, alt? } with ui:image-picker for Form Factory.
+ * Use in section data and resolve with resolveAssetUrl(url, tenantId) in View.
+ */
+export declare const ImageSelectionSchema: z.ZodObject<{
+    url: z.ZodString;
+    alt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+    alt?: string | undefined;
+}, {
+    url: string;
+    alt?: string | undefined;
+}>;
+
 export declare const InputWidgets: {
     readonly 'ui:text': ({ label, value, onChange }: BaseWidgetProps<string>) => JSX.Element;
     readonly 'ui:textarea': ({ label, value, onChange }: BaseWidgetProps<string>) => JSX.Element;
@@ -328,6 +423,31 @@ export declare interface JsonPagesConfig {
         parse: (v: unknown) => unknown;
         shape?: Record<string, unknown>;
     }>;
+    /**
+     * Optional registry of Zod submission schemas for sections that can be filled
+     * by external agents (e.g. MCP-connected AI clients).
+     *
+     * Keyed by the same section-type strings used in `schemas`. Each value is a
+     * Zod schema describing the section's *submission payload* (what the user
+     * fills in) — distinct from `schemas` entries, which describe the section's
+     * *UI configuration* (how the tenant author configures the section).
+     *
+     * When a section type appears on a page AND has an entry here, its JSON
+     * Schema representation is emitted on the page contract as
+     * `sectionSubmissionSchemas` (see `OlonJsPageContract`).
+     *
+     * The shape mirrors `schemas` (duck-typed on `{ parse, shape? }`) so core
+     * does not force `zod` on consumers at the type level. In practice tenants
+     * pass `z.object(...)` instances; the JSON Schema serializer casts to
+     * `z.ZodTypeAny` at its own boundary.
+     *
+     * See `docs/decisions/ADR-0002-form-submission-schemas.md` for rationale,
+     * tenant convention, and the full emission contract.
+     */
+    submissionSchemas?: Record<string, {
+        parse: (v: unknown) => unknown;
+        shape?: Record<string, unknown>;
+    }>;
     pages: Record<string, PageConfig>;
     siteConfig: SiteConfig;
     themeConfig: ThemeConfig;
@@ -367,7 +487,6 @@ export declare namespace kernel {
         PageMeta,
         PageConfig,
         SiteIdentity,
-        SitePageEntry,
         SiteConfig,
         ThemeTokenMap,
         ThemeColors,
@@ -423,6 +542,13 @@ export declare function normalizeBasePath(value?: string): string;
 
 export declare function normalizeSlugSegments(value: string): string;
 
+/**
+ * Context holding the submission state of every olon-managed form,
+ * keyed by the form's id attribute (or anchorId).
+ * Provided by App.tsx via useOlonForms().
+ */
+export declare const OlonFormsContext: Context<Record<string, FormState>>;
+
 declare interface OlonJsPageContract {
     version: '1.0.0';
     kind: 'olonjs-page-contract';
@@ -434,6 +560,20 @@ declare interface OlonJsPageContract {
     sectionTypes: string[];
     sectionInstances: WebMcpSectionInstance[];
     sectionSchemas: Record<string, Record<string, unknown>>;
+    /**
+     * Optional JSON Schema representations of submission payloads for form-capable
+     * sections present on this page. Keyed by section type.
+     *
+     * Emitted only for section types that (a) actually appear on this page AND
+     * (b) have an entry in `JsonPagesConfig.submissionSchemas`. Absent (not `{}`)
+     * when no section on the page qualifies, to keep the contract tight.
+     *
+     * MCP agents consuming this contract can discover form shapes directly from
+     * reading the page, without requiring a separate tool call.
+     *
+     * See `docs/decisions/ADR-0002-form-submission-schemas.md` (emission contract).
+     */
+    sectionSubmissionSchemas?: Record<string, Record<string, unknown>>;
     tools: WebMcpToolContract[];
 }
 
@@ -644,6 +784,22 @@ declare interface RuntimeResolutionResult {
     menuConfig: MenuConfig;
 }
 
+declare interface SaveStreamDoneEvent {
+    deployUrl?: string;
+    commitSha?: string;
+}
+
+declare interface SaveStreamLogEvent {
+    stepId: StepId;
+    message: string;
+}
+
+declare interface SaveStreamStepEvent {
+    id: StepId;
+    status: 'running' | 'done';
+    label?: string;
+}
+
 declare type Schemas = JsonPagesConfig['schemas'];
 
 /** Computed union of all registered section types. */
@@ -691,7 +847,6 @@ export declare interface SiteConfig {
     identity: SiteIdentity;
     header?: Section;
     footer: Section;
-    pages: SitePageEntry[];
 }
 
 export declare interface SiteIdentity {
@@ -699,11 +854,24 @@ export declare interface SiteIdentity {
     logoUrl?: string;
 }
 
-export declare interface SitePageEntry {
-    slug: string;
-    label: string;
+export declare function startCloudSaveStream(input: StartCloudSaveStreamInput): Promise<void>;
+
+declare interface StartCloudSaveStreamInput {
+    apiBaseUrl: string;
+    apiKey: string;
+    path: string;
+    content: unknown;
+    message?: string;
+    signal?: AbortSignal;
+    onStep: (event: SaveStreamStepEvent) => void;
+    onLog?: (event: SaveStreamLogEvent) => void;
+    onDone: (event: SaveStreamDoneEvent) => void;
 }
 
+export declare type StepId = 'commit' | 'push' | 'build' | 'live';
+
+export declare type StepState = 'pending' | 'active' | 'done';
+
 export declare namespace studio {
     export {
         STUDIO_EVENTS,
@@ -835,6 +1003,12 @@ export declare function useConfig(): ConfigContextValue;
 
 export declare const useDocumentMeta: (meta: PageMeta) => void;
 
+/**
+ * Read the submission state for a specific form.
+ * @param formId - must match the id attribute on the <form> element.
+ */
+export declare function useFormState(formId: string): FormState;
+
 export declare const useStudio: () => StudioContextType;
 
 export declare const VisitorRoute: default_2.FC<VisitorRouteProps>;
@@ -918,4 +1092,18 @@ export declare type WidgetType = keyof typeof InputWidgets;
 
 export declare function withBasePath(pathname: string, basePath?: string): string;
 
+/**
+ * Mixin for any section capsule that includes a contact form.
+ * Merge into the section data schema to expose recipientEmail
+ * as an editable field in the Studio inspector.
+ * The View must set data-olon-recipient={data.recipientEmail} on the <form>.
+ */
+export declare const WithFormRecipient: z.ZodObject<{
+    recipientEmail: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    recipientEmail?: string | undefined;
+}, {
+    recipientEmail?: string | undefined;
+}>;
+
 export { }