@mandolop97/constructor-nexora 1.5.0 → 1.7.1

package/dist/types/contract.d.ts

@@ -1,6 +1,6 @@
 /**
  * ════════════════════════════════════════════════════════════════════════════
- * NEXORA VISUAL BUILDER — OFFICIAL CONTRACT
+ * NEXORA VISUAL BUILDER — OFFICIAL CONTRACT v1.7.0
  * ════════════════════════════════════════════════════════════════════════════
  *
  * This file defines the **shared contract** between the Nexora Visual Builder
@@ -9,9 +9,27 @@
  * Both systems MUST use these exact types, names, and structures to ensure
  * full compatibility and seamless data flow.
  *
- * VERSION: 1.5.0
+ * VERSION: 1.7.0
+ *
+ * ── DATA OWNERSHIP POLICY ──
+ *
+ * ┌─────────────┬────────────────────────────┬───────────────────────────┐
+ * │ Layer       │ Responsibility             │ Prohibitions              │
+ * ├─────────────┼────────────────────────────┼───────────────────────────┤
+ * │ Host/Template│ Fetch + adapt data.        │ Cannot modify schema      │
+ * │ (consumer)  │ Build RenderContext.        │ nodes directly.           │
+ * │             │ Provide hostData.           │                           │
+ * ├─────────────┼────────────────────────────┼───────────────────────────┤
+ * │ Builder     │ Schema CRUD.               │ NO fetch to external APIs │
+ * │ (editor)    │ Adapt hostData for preview. │ NO direct DB calls for    │
+ * │             │ Validate before publish.    │ business data.            │
+ * ├─────────────┼────────────────────────────┼───────────────────────────┤
+ * │ Renderer    │ Render nodes from schema + │ NO fetch. NO state        │
+ * │ (PageRender)│ resolved context. Pure.    │ mutation. Read-only.      │
+ * └─────────────┴────────────────────────────┴───────────────────────────┘
  */
 import { NodeStyle, ThemeTokens, AnimationPreset, SchemaNode, Schema } from './schema';
+import { PageType, PageMetadata } from './page-types';
 /** All built-in node types supported by the builder */
 export type BuiltInNodeType = 'Section' | 'Container' | 'Grid' | 'Stack' | 'Text' | 'Image' | 'Divider' | 'Badge' | 'Spacer' | 'Icon' | 'SocialIcons' | 'Button' | 'Card' | 'Input' | 'Accordion' | 'TabsBlock' | 'VideoEmbed' | 'FormBlock' | 'ProductCard' | 'ProductGrid' | 'CollectionGrid' | 'Navbar' | 'Footer' | 'AnnouncementBar' | 'HeroSection' | 'FeatureBar' | 'TestimonialCard' | 'NewsletterSection' | 'ImageBanner' | 'RichTextSection' | 'CTASection' | 'TestimonialSection' | 'FAQSection';
 /** Extensible node type — accepts built-in types plus any custom string */
@@ -229,25 +247,110 @@ export interface BoundSchemaNode extends SchemaNode {
     };
 }
 export type RenderMode = 'public' | 'preview' | 'edit';
+/** Runtime context for the current page */
+export interface PageContext {
+    /** Type of the current page */
+    pageType: PageType;
+    /** Current page slug */
+    slug: string;
+    /** URL parameters (e.g., product handle, collection handle) */
+    params?: Record<string, string>;
+    /** Query string parameters */
+    query?: Record<string, string>;
+    /** Render mode — replaces the old `isPreview` boolean */
+    mode: RenderMode;
+    /** The page metadata (SEO, OG, etc.) */
+    metadata?: PageMetadata;
+}
+/**
+ * RenderContext v1.7.0 — The single source of truth for all rendering data.
+ *
+ * Built by the Host/Template layer and consumed read-only by Builder and Renderer.
+ */
 export interface RenderContext {
+    /** Current render mode */
     mode: RenderMode;
-    /** Data available for binding */
+    /** Page-level context (optional — auto-built from mode if not provided) */
+    page?: PageContext;
+    /** All data available for binding resolution */
     data?: {
-        products?: any[];
-        collections?: any[];
-        pages?: any[];
-        settings?: Record<string, any>;
-        custom?: Record<string, any>;
+        /** E-commerce product data */
+        products: any[];
+        /** Product collections / categories */
+        collections: any[];
+        /** CMS / content pages */
+        pages: any[];
+        /** Global site settings (store name, currency, language, etc.) */
+        settings: Record<string, any>;
+        /** Card template schema for hydration (used by ProductGrid) */
+        cardTemplate?: {
+            nodes: Record<string, SchemaNode>;
+            rootNodeId: string;
+            themeTokens?: ThemeTokens;
+        };
+        /** Host-defined custom data sources */
+        custom: Record<string, any>;
     };
-    /** Current item when rendering inside a collection */
+    /** Iteration context — set by collection renderers (e.g., ProductGrid) */
     currentItem?: any;
-    /** Item index when rendering inside a collection */
+    /** Current item index in iteration */
     currentIndex?: number;
-    /** Theme tokens */
+    /** Theme tokens snapshot */
     theme?: ThemeTokens;
-    /** Resolve asset URLs */
+    /** Resolve asset paths to full URLs */
     resolveAssetUrl?: (path: string) => string;
 }
+/**
+ * Slot behavior determines what can be done with a slot's content:
+ * - locked:    Render as-is. Inspector disabled. Cannot delete/move.
+ * - editable:  Full inspector access. Can reorder children.
+ * - dynamic:   Data-driven. Bindings resolved at render. Children generated from data.
+ */
+export type SlotBehavior = 'locked' | 'editable' | 'dynamic';
+/**
+ * Slot assignment for template integration.
+ *
+ * Fallback rules:
+ * - If slot has no children AND fallbackNodeId is set → render fallback node.
+ * - If slot has no children AND no fallback → render empty placeholder (edit mode only).
+ */
+export interface SlotAssignment {
+    /** Slot identifier (e.g. 'header', 'footer', 'main', 'sidebar') */
+    __slot: string;
+    /** Slot behavior */
+    behavior: SlotBehavior;
+    /** Fallback node ID if slot is empty */
+    fallbackNodeId?: string;
+}
+export type PublishStage = 'draft' | 'validated' | 'preview' | 'published';
+/** Options for the validation step */
+export interface ValidatorOptions {
+    /** Treat warnings as errors */
+    strict?: boolean;
+    /** Page type for context-aware validation */
+    pageType?: PageType;
+}
+/**
+ * Publication pipeline contract.
+ *
+ * Rules:
+ * - `validate().errors.length > 0` blocks publish.
+ * - Warnings are displayed but do NOT block.
+ * - Preview is optional.
+ */
+export interface PublishPipeline {
+    /** 1. Save work-in-progress */
+    saveDraft: (schema: Schema) => Promise<void>;
+    /** 2. Run validation — must pass with 0 errors to proceed */
+    validate: (schema: Schema, opts?: ValidatorOptions) => {
+        errors: string[];
+        warnings: string[];
+    };
+    /** 3. Generate preview (optional) — returns preview URL */
+    preview?: (schema: Schema) => Promise<string>;
+    /** 4. Publish to production */
+    publish: (payload: any) => Promise<void>;
+}
 export type TemplateType = 'page' | 'header' | 'footer' | 'component' | 'single';
 export interface PageDefinition {
     slug: string;
@@ -261,7 +364,13 @@ export interface PageDefinition {
         width: number;
         height: number;
     };
+    /**
+     * Host-provided data for edit/preview binding resolution.
+     * @deprecated Use `hostData` instead. This alias is kept for backward compatibility.
+     */
     mockData?: Record<string, any>;
+    /** Host-provided data for edit/preview binding resolution */
+    hostData?: Record<string, any>;
 }
 export interface InspectorFieldDef {
     key: string;

package/dist/types/page-types.d.ts

@@ -0,0 +1,65 @@
+/**
+ * ════════════════════════════════════════════════════════════════════════════
+ * NEXORA — PAGE TYPES, METADATA, VISIBILITY & CONSTRAINTS
+ * ════════════════════════════════════════════════════════════════════════════
+ */
+import { NodeType } from './schema';
+/** Supported page types for the e-commerce builder */
+export type PageType = 'home' | 'collection' | 'product' | 'cart' | 'checkout' | 'static' | 'landing' | 'blog' | 'blog-post' | 'account' | 'search' | 'custom';
+/** Mapping of page types to human-readable labels */
+export declare const PAGE_TYPE_LABELS: Record<PageType, string>;
+export interface PageMetadata {
+    /** Page title for <title> tag and og:title */
+    title?: string;
+    /** Meta description for SEO and og:description */
+    description?: string;
+    /** Open Graph image URL */
+    ogImage?: string;
+    /** Canonical URL */
+    canonical?: string;
+    /** Additional meta tags */
+    meta?: Array<{
+        name: string;
+        content: string;
+    }>;
+    /** Whether search engines should index this page */
+    noIndex?: boolean;
+    /** JSON-LD structured data */
+    jsonLd?: Record<string, any>;
+}
+/**
+ * @deprecated Import PageContext from '@/types/contract' instead.
+ * This re-export is kept for backward compatibility.
+ */
+export type { PageContext } from './contract';
+export type DeviceVisibility = 'all' | 'desktop' | 'tablet' | 'mobile' | 'desktop+tablet' | 'tablet+mobile';
+export interface VisibilityRule {
+    /** Show/hide on specific devices */
+    device?: DeviceVisibility;
+    /** Show only on specific page types */
+    pageTypes?: PageType[];
+    /** Show only when user is authenticated */
+    requireAuth?: boolean;
+    /** Custom condition expression (future) */
+    condition?: string;
+    /** Schedule visibility */
+    schedule?: {
+        startDate?: string;
+        endDate?: string;
+    };
+}
+/** Configuration for locking specific props on a node */
+export interface LockedPropsConfig {
+    /** List of prop keys that are locked (cannot be edited) */
+    lockedProps?: string[];
+    /** List of style keys that are locked */
+    lockedStyles?: string[];
+    /** Whether the entire node is locked from deletion */
+    preventDelete?: boolean;
+    /** Whether the node can be moved/reordered */
+    preventMove?: boolean;
+}
+/** Default block-to-page-type compatibility map */
+export declare const BLOCK_PAGE_TYPE_DEFAULTS: Partial<Record<NodeType, PageType[]>>;
+/** Check if a block type is compatible with a page type */
+export declare function isBlockCompatibleWithPage(blockType: NodeType, pageType: PageType, allowedPageTypes?: PageType[]): boolean;

package/dist/types/schema.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import type { SlotAssignment } from './contract';
 export type BuiltInNodeType = 'Section' | 'Container' | 'Grid' | 'Stack' | 'Text' | 'Image' | 'Divider' | 'Badge' | 'Button' | 'Card' | 'Input' | 'ProductCard' | 'ProductGrid' | 'CollectionGrid' | 'Navbar' | 'Footer' | 'AnnouncementBar' | 'FeatureBar' | 'TestimonialCard' | 'NewsletterSection' | 'HeroSection' | 'ImageBanner' | 'RichTextSection' | 'CTASection' | 'TestimonialSection' | 'FAQSection' | 'Accordion' | 'TabsBlock' | 'VideoEmbed' | 'Spacer' | 'Icon' | 'SocialIcons' | 'FormBlock';
 /** Extensible node type — accepts all built-in types plus any custom string. */
 export type NodeType = BuiltInNodeType | (string & {});
@@ -180,6 +181,8 @@ export interface SchemaNode {
     customCSS?: string;
     /** IDs of global styles applied to this node */
     appliedGlobalStyles?: string[];
+    /** Slot assignment for template integration */
+    slot?: SlotAssignment;
 }
 export interface ThemeTokens {
     colors: {
@@ -244,7 +247,10 @@ export interface PageDefinition {
         width: number;
         height: number;
     };
+    /** @deprecated Use hostData */
     mockData?: Record<string, any>;
+    /** Host-provided data for edit/preview binding resolution */
+    hostData?: Record<string, any>;
 }
 export type RenderMode = 'public' | 'preview' | 'edit';
 export type TemplateType = 'page' | 'header' | 'footer' | 'component' | 'single';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mandolop97/constructor-nexora",
   "private": false,
-  "version": "1.5.0",
+  "version": "1.7.1",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -18,7 +18,9 @@
     "react-dom": "^18.0.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "NEXORA.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "dev": "vite",