@jsonpages/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,455 @@
+import { ClassValue } from 'clsx';
+import { default as default_2 } from 'react';
+import { JSX } from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { z } from 'zod';
+
+/**
+ * Optional config for the "Add section" library (tenant-agnostic).
+ * Section types are derived from registry/schemas; tenant can customize labels and defaults.
+ */
+export declare interface AddSectionConfig {
+    /** Section types that can be added to a page (order preserved). If omitted, derived from schemas excluding header/footer. */
+    addableSectionTypes?: string[];
+    /** Display label per section type. If omitted, type id is humanized (e.g. "feature-grid" → "Feature grid"). */
+    sectionTypeLabels?: Record<string, string>;
+    /** Default data for a new section of the given type. Required for add-section to produce valid sections. */
+    getDefaultSectionData?: (sectionType: string) => Record<string, unknown>;
+}
+
+export declare const AddSectionLibrary: default_2.FC<AddSectionLibraryProps>;
+
+declare interface AddSectionLibraryProps {
+    open: boolean;
+    onClose: () => void;
+    /** Section type ids that can be added (e.g. from config.addSection.addableSectionTypes or derived). */
+    sectionTypes: string[];
+    /** Optional display label per type; falls back to humanized type id. */
+    sectionTypeLabels?: Record<string, string>;
+    onSelect: (sectionType: string) => void;
+}
+
+export declare const AdminSidebar: default_2.FC<AdminSidebarProps>;
+
+declare interface AdminSidebarProps {
+    selectedSection: SelectedSectionInfo | null;
+    pageData: PageConfig | {
+        sections: Section[];
+    };
+    /** All sections (header + page sections + footer) for resolving modal section data. */
+    allSectionsData?: Section[];
+    onUpdate: (newData: Record<string, unknown>) => void;
+    /** Update a section by id/scope (e.g. from settings modal). When provided with allSectionsData, gear opens modal. */
+    onUpdateSection?: OnUpdateSection;
+    onClose: () => void;
+    /** Root-to-leaf path for deep focus (e.g. silos -> blocks). When null, no canvas selection. */
+    expandedItemPath?: Array<{
+        fieldKey: string;
+        itemId?: string;
+    }> | null;
+    onReorderSection?: (sectionId: string, newIndex: number) => void;
+    allLayers?: LayerItem[];
+    activeSectionId?: string | null;
+    onRequestScrollToSection?: (sectionId: string) => void;
+    onDeleteSection?: (sectionId: string) => void;
+    /** When provided, shows an "Add section" button in the inspector header that opens the section library. */
+    onAddSection?: () => void;
+    /** Whether there are unsaved changes (disables Bake HTML / Export JSON when false). */
+    hasChanges?: boolean;
+    /** Trigger Bake HTML (same as ControlBar). */
+    onExportHTML?: () => void;
+    /** Trigger Export JSON (same as ControlBar). */
+    onExportJSON?: () => void;
+}
+
+/**
+ * 🍞 BAKED STATE (Optimized subset for the static HTML artifact)
+ */
+export declare interface BakedState {
+    page: PageConfig;
+    site: Omit<SiteConfig, 'pages'>;
+    menu: MenuConfig;
+    theme: ThemeConfig;
+}
+
+export declare interface BaseSection<K extends keyof SectionDataRegistry> {
+    id: string;
+    type: K;
+    data: SectionDataRegistry[K];
+    settings?: K extends keyof SectionSettingsRegistry ? SectionSettingsRegistry[K] : BaseSectionSettings;
+}
+
+/**
+ * 🛡️ KERNEL: The Base Contract (MTRP)
+ * Core is self-contained; structural types live here.
+ */
+export declare interface BaseSectionSettings {
+    [key: string]: unknown;
+}
+
+/**
+ * Shared types between Admin Engine and Input Registry.
+ */
+export declare interface BaseWidgetProps<T = unknown> {
+    label: string;
+    value: T;
+    onChange: (val: T) => void;
+    options?: string[];
+}
+
+export declare function cn(...inputs: ClassValue[]): string;
+
+export declare interface ConfigContextValue {
+    registry: Registry;
+    schemas: Schemas;
+    /** For asset resolution (e.g. image picker preview). */
+    tenantId?: string;
+}
+
+export declare const ConfigProvider: default_2.FC<{
+    config: Pick<JsonPagesConfig, 'registry' | 'schemas' | 'tenantId'>;
+    children: default_2.ReactNode;
+}>;
+
+export declare const ControlBar: default_2.FC<ControlBarProps>;
+
+declare interface ControlBarProps {
+    hasChanges: boolean;
+    onExportJSON: () => void;
+    onExportHTML: () => void;
+    /** Optional: opens the Add section library. When provided, an "Add section" icon is shown. */
+    onAddSection?: () => void;
+}
+
+export declare const DefaultNotFound: default_2.FC;
+
+/**
+ * 🍞 BAKE HTML (The Single File Artifact)
+ */
+export declare const exportBakedHTML: (state: ProjectState, slug: string, cleanHtml: string) => void;
+
+/**
+ * 💾 EXPORT JSON (The Developer Handover)
+ */
+export declare const exportProjectJSON: (state: ProjectState, slug: string) => Promise<void>;
+
+/** Structural shape used when no tenant has augmented the registries. */
+export declare interface FallbackSection {
+    id: string;
+    type: string;
+    data: Record<string, unknown>;
+    settings?: Record<string, unknown>;
+}
+
+export declare const FormFactory: default_2.FC<FormFactoryProps>;
+
+declare interface FormFactoryProps {
+    schema: z.ZodObject<z.ZodRawShape>;
+    data: Record<string, unknown>;
+    onChange: (newData: Record<string, unknown>) => void;
+    /** When set, only render fields whose key is in this array (e.g. Content vs Settings tabs). */
+    keys?: string[] | null;
+    /** Root-to-leaf path for deep focus (e.g. silos -> blocks). First segment applies to this level. */
+    expandedItemPath?: Array<{
+        fieldKey: string;
+        itemId?: string;
+    }> | null;
+    /** When user selects an item on the Stage, expand that array item (fieldKey -> itemId). */
+    expandedItemIdByField?: Record<string, string>;
+    /** When user clicks a field on the Stage, show it at top / scroll to it (simple field key). */
+    focusedFieldKey?: string | null;
+    /** Called when user expands/collapses an array item in the sidebar (so parent can drive fade). */
+    onSidebarExpandedItemChange?: (item: {
+        fieldKey: string;
+        itemId?: string;
+    } | null) => void;
+}
+
+export declare const InputWidgets: {
+    readonly 'ui:text': ({ label, value, onChange }: BaseWidgetProps<string>) => JSX.Element;
+    readonly 'ui:textarea': ({ label, value, onChange }: BaseWidgetProps<string>) => JSX.Element;
+    readonly 'ui:select': ({ label, value, onChange, options }: BaseWidgetProps<string>) => JSX.Element;
+    readonly 'ui:checkbox': ({ label, value, onChange }: BaseWidgetProps<boolean>) => JSX.Element;
+    readonly 'ui:image-picker': ({ label, value, onChange }: BaseWidgetProps<string>) => JSX.Element;
+    readonly 'ui:icon-picker': ({ label, value, onChange }: BaseWidgetProps<string>) => JSX.Element;
+};
+
+/** Single entry point configuration for the JsonPages Engine. */
+export declare interface JsonPagesConfig {
+    /** Unique identifier for the tenant (used for asset resolution) */
+    tenantId: string;
+    /** Component map: section type -> React component. */
+    registry: Record<string, default_2.ComponentType<unknown>>;
+    /** Zod schemas map: section type -> schema. */
+    schemas: Record<string, {
+        parse: (v: unknown) => unknown;
+        shape?: Record<string, unknown>;
+    }>;
+    /** Page slug -> page config. */
+    pages: Record<string, PageConfig>;
+    siteConfig: SiteConfig;
+    themeConfig: ThemeConfig;
+    menuConfig: MenuConfig;
+    /** Optional persistence; Core provides defaults if omitted. */
+    persistence?: Partial<PersistenceConfig>;
+    /** CSS strings for ThemeLoader. */
+    themeCss: ThemeCssConfig;
+    /** Optional 404 component. */
+    NotFoundComponent?: default_2.ComponentType;
+    /** Optional "Add section" library config (labels, addable types, default data). */
+    addSection?: AddSectionConfig;
+}
+
+export declare function JsonPagesEngine({ config }: JsonPagesEngineProps): JSX.Element;
+
+declare interface JsonPagesEngineProps {
+    config: JsonPagesConfig;
+}
+
+export declare interface LayerItem {
+    id: string;
+    type: string;
+    scope: string;
+    title?: string;
+}
+
+export declare interface MenuConfig {
+    main: MenuItem[];
+}
+
+export declare interface MenuItem {
+    label: string;
+    href: string;
+    icon?: string;
+    external?: boolean;
+    isCta?: boolean;
+    children?: MenuItem[];
+}
+
+/** Used by the section-settings modal to update a section without changing Inspector selection. */
+export declare type OnUpdateSection = (sectionId: string, scope: 'global' | 'local', sectionType: string, newData: Record<string, unknown>) => void;
+
+export declare interface PageConfig {
+    id: string;
+    slug: string;
+    meta: PageMeta;
+    sections: Section[];
+}
+
+export declare interface PageMeta {
+    title: string;
+    description: string;
+}
+
+export declare const PageRenderer: default_2.FC<Props>;
+
+export declare interface PageRendererProps {
+    pageConfig: PageConfig;
+    siteConfig: SiteConfig;
+    menuConfig: MenuConfig;
+    selectedId?: string | null;
+}
+
+/** Persistence API; defaults provided by Core, overridable by Tenant. */
+export declare interface PersistenceConfig {
+    exportJSON: (state: ProjectState, slug: string) => Promise<void>;
+    exportHTML: (state: ProjectState, slug: string, cleanHtml: string) => void;
+}
+
+export declare const PreviewEntry: default_2.FC;
+
+/**
+ * 📦 PROJECT STATE (The Universal Data Bundle)
+ * Moved to Kernel to serve as SSOT for Engine and Persistence.
+ */
+export declare interface ProjectState {
+    page: PageConfig;
+    site: SiteConfig;
+    menu: MenuConfig;
+    theme: ThemeConfig;
+}
+
+declare type Props = PageRendererProps & {
+    onReorder?: (sectionId: string, newIndex: number) => void;
+    /** When set, scroll this section into view (Studio full-page). */
+    scrollToSectionId?: string | null;
+    /** Report which section is most visible in viewport (Intersection Observer). */
+    onActiveSectionChange?: (sectionId: string | null) => void;
+};
+
+declare type Registry = JsonPagesConfig['registry'];
+
+/**
+ * 🛡️ SOVEREIGN ASSET RESOLVER
+ * Centralized logic to distinguish between routes and static assets.
+ * Moved to Core to allow Standard Blocks to resolve assets consistently.
+ */
+export declare const resolveAssetUrl: (path: string, tenantId?: string) => string;
+
+declare type Schemas = JsonPagesConfig['schemas'];
+
+/** Computed union of all registered section types. */
+export declare type Section = keyof SectionDataRegistry extends never ? FallbackSection : {
+    [K in keyof SectionDataRegistry]: BaseSection<K>;
+}[keyof SectionDataRegistry];
+
+export declare interface SectionDataRegistry {
+}
+
+export declare const SectionRenderer: default_2.FC<SectionRendererProps>;
+
+declare interface SectionRendererProps {
+    section: Section;
+    menu?: MenuItem[];
+    selectedId?: string | null;
+    /** When true, show reorder (up/down) in overlay for local sections. */
+    reorderable?: boolean;
+    /** Section index in page (for reorder). Required when reorderable. */
+    sectionIndex?: number;
+    /** Total number of page sections (for disabling down at last). */
+    totalSections?: number;
+    /** Called when user triggers move up/down. newIndex is the target index for the engine. */
+    onReorder?: (sectionId: string, newIndex: number) => void;
+}
+
+export declare interface SectionSettingsRegistry {
+}
+
+export declare type SectionType = keyof SectionDataRegistry extends never ? string : keyof SectionDataRegistry;
+
+declare interface SelectedSectionInfo {
+    id: string;
+    type: string;
+    scope: string;
+}
+
+export declare interface SiteConfig {
+    identity: SiteIdentity;
+    header?: Section;
+    footer?: Section;
+    pages: SitePageEntry[];
+}
+
+export declare interface SiteIdentity {
+    title: string;
+    logoUrl?: string;
+}
+
+export declare interface SitePageEntry {
+    slug: string;
+    label: string;
+}
+
+/**
+ * 📡 STUDIO EVENT PROTOCOL
+ * Single Source of Truth for cross-frame communication.
+ */
+export declare const STUDIO_EVENTS: {
+    readonly UPDATE_DRAFTS: "jsonpages:update-drafts";
+    readonly SYNC_SELECTION: "jsonpages:sync-selection";
+    readonly REQUEST_CLEAN_HTML: "jsonpages:request-clean-html";
+    readonly SEND_CLEAN_HTML: "jsonpages:send-clean-html";
+    readonly SECTION_SELECT: "jsonpages:section-select";
+    readonly REQUEST_SCROLL_TO_SECTION: "jsonpages:request-scroll-to-section";
+    readonly ACTIVE_SECTION_CHANGED: "jsonpages:active-section-changed";
+    readonly STAGE_READY: "jsonpages:stage-ready";
+};
+
+declare interface StudioContextType {
+    mode: StudioMode;
+}
+
+declare type StudioMode = 'visitor' | 'studio';
+
+export declare const StudioProvider: default_2.FC<{
+    mode: StudioMode;
+    children: ReactNode;
+}>;
+
+/**
+ * 📺 STUDIO STAGE (Full Preview Mode)
+ * Manages the Iframe and the PostMessage protocol.
+ * NOW INCLUDES: Handshake Listener to fix the "Waiting..." race condition.
+ */
+export declare const StudioStage: default_2.FC<StudioStageProps>;
+
+declare interface StudioStageProps {
+    draft: PageConfig;
+    globalDraft: SiteConfig;
+    themeConfig: ThemeConfig;
+    slug: string;
+    selectedId?: string | null;
+    scrollToSectionId?: string | null;
+    onScrollRequested?: () => void;
+}
+
+export declare interface ThemeBorderRadius {
+    sm: string;
+    md: string;
+    lg: string;
+}
+
+export declare interface ThemeColors {
+    primary: string;
+    secondary: string;
+    accent: string;
+    background: string;
+    surface: string;
+    surfaceAlt: string;
+    text: string;
+    textMuted: string;
+    border: string;
+}
+
+export declare interface ThemeConfig {
+    name: string;
+    tokens: ThemeTokens;
+}
+
+/** Theme CSS: tenant (required), admin (optional). */
+export declare interface ThemeCssConfig {
+    tenant: string;
+    admin?: string;
+}
+
+/**
+ * Theme Loader: injects the required CSS into the <head> and removes it on unmount.
+ * CSS strings are passed as props so the Engine controls injection; Tenant does not manage Admin CSS.
+ */
+export declare const ThemeLoader: default_2.FC<ThemeLoaderProps>;
+
+declare interface ThemeLoaderProps {
+    /** Which mode is active; determines which CSS is injected. */
+    mode: 'tenant' | 'admin';
+    /** CSS string for tenant (visitor) mode. */
+    tenantCss: string;
+    /** CSS string for admin (studio) mode. Engine provides default if not passed. */
+    adminCss: string;
+    children: default_2.ReactNode;
+}
+
+export declare const themeManager: {
+    setTheme: (theme: ThemeConfig) => void;
+};
+
+export declare interface ThemeTokens {
+    colors: ThemeColors;
+    typography: ThemeTypography;
+    borderRadius: ThemeBorderRadius;
+}
+
+export declare interface ThemeTypography {
+    fontFamily: {
+        primary: string;
+        mono: string;
+        display?: string;
+    };
+}
+
+export declare function useConfig(): ConfigContextValue;
+
+export declare const useStudio: () => StudioContextType;
+
+export declare type WidgetType = keyof typeof InputWidgets;
+
+export { }