react-layout-sdk 1.1.5 → 1.1.7

package/README.md

@@ -0,0 +1,72 @@
+# React Layout SDK (JD Layout System)
+
+The **React Layout SDK** is an enterprise-grade Frontend SDK designed to consume layout definitions from Strapi via the **Strapi Layout Plugin**. Inspired by robust headless ecosystems like Sitecore JSS, this SDK provides dynamic placeholder routing and a scaffold generator to stream-line Developer Experience (DX).
+
+## Installation
+
+Install the package using your favorite package manager:
+
+```bash
+npm install react-layout-sdk
+```
+
+## Quick Start (Project Scaffolding)
+
+To quickly set up your Next.js project to work with the JD Layout System, run the init command at the root of your project:
+
+```bash
+npx react-layout-sdk init
+```
+
+**What this does:**
+1. Creates a `src/components/factory.tsx` file for component mapping.
+2. Generates base boilerplate components like `Header.tsx` and `Footer.tsx`.
+3. Auto-configures your Next.js App Router (`app/[[...slug]]/page.tsx`) or Pages Router to catch all layout routes and fetch them dynamically using `fetchJDLayout`.
+
+## Component Scaffolding
+
+You can scaffold new React components and automatically map them to their corresponding Strapi components in `factory.tsx` using the generate command:
+
+```bash
+npx react-layout-sdk generate component <strapi-component-uid>
+```
+
+**Example:**
+```bash
+npx react-layout-sdk generate component blocks.hero-banner
+```
+*This command will:*
+- Create `src/components/HeroBanner.tsx`.
+- Automatically inject `import HeroBanner` and map `'blocks.hero-banner': HeroBanner` inside your `factory.tsx`.
+
+## API Reference
+
+### 1. `fetchJDLayout(apiUrl, slug, locale)`
+Fetches the layout structure and content from the Strapi backend.
+
+```typescript
+import { fetchJDLayout } from 'react-layout-sdk';
+
+const layoutData = await fetchJDLayout('http://localhost:1337', '/home', 'en');
+const { route } = layoutData.strapi;
+```
+
+### 2. `<Placeholder />`
+Renders a specific dynamic zone (like `header`, `main`, or `footer`) by matching the JSON data against your React components.
+
+```tsx
+import { Placeholder } from 'react-layout-sdk';
+import { componentMap } from '@/components/factory';
+
+<main>
+  <Placeholder 
+    name="main" 
+    rendering={route.placeholders.main || []} 
+    componentMap={componentMap} 
+  />
+</main>
+```
+
+## TypeScript Support
+
+This package comes with full TypeScript definitions, including `JDLayoutResponse`, `JDRoute`, and `JDContext`.

package/bin/init.js

@@ -128,7 +128,7 @@ if (command === 'init') {
 
   // 2. Create Header.tsx
   const headerPath = path.join(componentsDir, 'Header.tsx');
-  const headerContent = `import React from 'react';\n\nexport default function Header(props: any) {\n  const title = props?.title || 'Velox Header';\n  const logoUrl = props?.logoUrl;\n\n  return (\n    <header style={{ padding: '20px', background: '#f5f5f5', borderBottom: '1px solid #ddd' }}>\n      <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>\n        <div style={{ display: 'flex', alignItems: 'center', gap: '10px' }}>\n          {logoUrl && <img src={logoUrl} alt="Logo" width="40" />}\n          <h1 style={{ margin: 0, fontSize: '1.5rem' }}>{title}</h1>\n        </div>\n      </div>\n    </header>\n  );\n}\n`;
+  const headerContent = `import React from 'react';\n\nexport default function Header(props: any) {\n  const title = props?.title || 'JD Header';\n  const logoUrl = props?.logoUrl;\n\n  return (\n    <header style={{ padding: '20px', background: '#f5f5f5', borderBottom: '1px solid #ddd' }}>\n      <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>\n        <div style={{ display: 'flex', alignItems: 'center', gap: '10px' }}>\n          {logoUrl && <img src={logoUrl} alt="Logo" width="40" />}\n          <h1 style={{ margin: 0, fontSize: '1.5rem' }}>{title}</h1>\n        </div>\n      </div>\n    </header>\n  );\n}\n`;
   if (!fs.existsSync(headerPath)) {
     fs.writeFileSync(headerPath, headerContent);
     console.log('✅ Created components/Header.tsx');
@@ -136,7 +136,7 @@ if (command === 'init') {
 
   // 3. Create Footer.tsx
   const footerPath = path.join(componentsDir, 'Footer.tsx');
-  const footerContent = `import React from 'react';\n\nexport default function Footer(props: any) {\n  const text = props?.text || '© 2026 Velox Layout';\n  return (\n    <footer style={{ padding: '20px', background: '#333', color: '#fff', textAlign: 'center', marginTop: '40px' }}>\n      <p style={{ margin: 0 }}>{text}</p>\n    </footer>\n  );\n}\n`;
+  const footerContent = `import React from 'react';\n\nexport default function Footer(props: any) {\n  const text = props?.text || '© 2026 JD Layout';\n  return (\n    <footer style={{ padding: '20px', background: '#333', color: '#fff', textAlign: 'center', marginTop: '40px' }}>\n      <p style={{ margin: 0 }}>{text}</p>\n    </footer>\n  );\n}\n`;
   if (!fs.existsSync(footerPath)) {
     fs.writeFileSync(footerPath, footerContent);
     console.log('✅ Created components/Footer.tsx');
@@ -157,7 +157,7 @@ if (command === 'init') {
     ensureDirSync(pageDir);
     
     const appPagePath = path.join(pageDir, 'page.tsx');
-    const appPageContent = `import React from 'react';\nimport { fetchVeloxLayout, Placeholder } from 'react-layout-sdk';\nimport { componentMap } from '@/components/factory';\n\nexport default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {\n  const resolvedParams = await params;\n  const slugArray = resolvedParams?.slug || [];\n  const path = slugArray.join('/') || '/';\n  const STRAPI_URL = process.env.NEXT_PUBLIC_STRAPI_URL || 'http://localhost:1337';\n  \n  try {\n    const layoutData = await fetchVeloxLayout(STRAPI_URL, path, 'en');\n    if (!layoutData || !layoutData.strapi) return <h1>404 - Not Found</h1>;\n\n    const { route } = layoutData.strapi;\n\n    return (\n      <div className="layout-wrapper">\n        <Placeholder name="header" rendering={route.placeholders.header || []} componentMap={componentMap} />\n        <main style={{ minHeight: '60vh', padding: '20px' }}>\n          <Placeholder name="main" rendering={route.placeholders.main || []} componentMap={componentMap} />\n        </main>\n        <Placeholder name="footer" rendering={route.placeholders.footer || []} componentMap={componentMap} />\n      </div>\n    );\n  } catch (error) {\n    return <h1>Error Loading Layout</h1>;\n  }\n}\n`;
+    const appPageContent = `import React from 'react';\nimport { fetchJDLayout, Placeholder } from 'react-layout-sdk';\nimport { componentMap } from '@/components/factory';\n\nexport default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {\n  const resolvedParams = await params;\n  const slugArray = resolvedParams?.slug || [];\n  const path = slugArray.join('/') || '/';\n  const STRAPI_URL = process.env.NEXT_PUBLIC_STRAPI_URL || 'http://localhost:1337';\n  \n  try {\n    const layoutData = await fetchJDLayout(STRAPI_URL, path, 'en');\n    if (!layoutData || !layoutData.strapi) return <h1>404 - Not Found</h1>;\n\n    const { route } = layoutData.strapi;\n\n    return (\n      <div className="layout-wrapper">\n        <Placeholder name="header" rendering={route.placeholders.header || []} componentMap={componentMap} />\n        <main style={{ minHeight: '60vh', padding: '20px' }}>\n          <Placeholder name="main" rendering={route.placeholders.main || []} componentMap={componentMap} />\n        </main>\n        <Placeholder name="footer" rendering={route.placeholders.footer || []} componentMap={componentMap} />\n      </div>\n    );\n  } catch (error) {\n    return <h1>Error Loading Layout</h1>;\n  }\n}\n`;
     if (!fs.existsSync(appPagePath)) {
       fs.writeFileSync(appPagePath, appPageContent);
       console.log('✅ Created app/[[...slug]]/page.tsx');
@@ -173,7 +173,7 @@ if (command === 'init') {
     }
 
     const pagePath = path.join(basePath, 'pages', '[[...slug]].tsx');
-    const pagesContent = `import React from 'react';\nimport { fetchVeloxLayout, Placeholder } from 'react-layout-sdk';\nimport { componentMap } from '@/components/factory';\n\nexport default function LayoutPage({ layoutData, error }: any) {\n  if (error || !layoutData?.strapi) return <h1>404 - Layout Not Found</h1>;\n\n  const { route } = layoutData.strapi;\n  return (\n    <div className="layout-wrapper">\n      <Placeholder name="header" rendering={route.placeholders.header || []} componentMap={componentMap} />\n      <main style={{ minHeight: '60vh', padding: '20px' }}>\n        <Placeholder name="main" rendering={route.placeholders.main || []} componentMap={componentMap} />\n      </main>\n      <Placeholder name="footer" rendering={route.placeholders.footer || []} componentMap={componentMap} />\n    </div>\n  );\n}\n\nexport async function getServerSideProps(context: any) {\n  const slugArray = context.params?.slug || [];\n  const path = slugArray.join('/') || '/';\n  const STRAPI_URL = process.env.NEXT_PUBLIC_STRAPI_URL || 'http://localhost:1337';\n\n  try {\n    const layoutData = await fetchVeloxLayout(STRAPI_URL, path, 'en');\n    if (!layoutData) return { notFound: true };\n\n    return { props: { layoutData } };\n  } catch (error) {\n    return { props: { error: true } };\n  }\n}\n`;
+    const pagesContent = `import React from 'react';\nimport { fetchJDLayout, Placeholder } from 'react-layout-sdk';\nimport { componentMap } from '@/components/factory';\n\nexport default function LayoutPage({ layoutData, error }: any) {\n  if (error || !layoutData?.strapi) return <h1>404 - Layout Not Found</h1>;\n\n  const { route } = layoutData.strapi;\n  return (\n    <div className="layout-wrapper">\n      <Placeholder name="header" rendering={route.placeholders.header || []} componentMap={componentMap} />\n      <main style={{ minHeight: '60vh', padding: '20px' }}>\n        <Placeholder name="main" rendering={route.placeholders.main || []} componentMap={componentMap} />\n      </main>\n      <Placeholder name="footer" rendering={route.placeholders.footer || []} componentMap={componentMap} />\n    </div>\n  );\n}\n\nexport async function getServerSideProps(context: any) {\n  const slugArray = context.params?.slug || [];\n  const path = slugArray.join('/') || '/';\n  const STRAPI_URL = process.env.NEXT_PUBLIC_STRAPI_URL || 'http://localhost:1337';\n\n  try {\n    const layoutData = await fetchJDLayout(STRAPI_URL, path, 'en');\n    if (!layoutData) return { notFound: true };\n\n    return { props: { layoutData } };\n  } catch (error) {\n    return { props: { error: true } };\n  }\n}\n`;
     if (!fs.existsSync(pagePath)) {
       fs.writeFileSync(pagePath, pagesContent);
       console.log('✅ Created pages/[[...slug]].tsx');

package/dist/index.d.mts

@@ -16,27 +16,34 @@ interface PlaceholderProps {
 }
 declare const Placeholder: React.FC<PlaceholderProps>;
 
-interface VeloxPlaceholderData {
+interface JDPlaceholderData {
     __component: string;
     [key: string]: any;
 }
-interface VeloxRoute {
+interface JDRoute {
     name: string;
     displayName: string;
-    placeholders: Record<string, VeloxPlaceholderData[]>;
+    fields?: Record<string, any>;
+    seo?: {
+        metaTitle?: string;
+        metaDescription?: string;
+        metaImage?: any;
+        [key: string]: any;
+    };
+    placeholders: Record<string, JDPlaceholderData[]>;
 }
-interface VeloxContext {
+interface JDContext {
     pageEditing: boolean;
     site: Record<string, any>;
     language: string;
     locales: any[];
 }
-interface VeloxLayoutResponse {
+interface JDLayoutResponse {
     strapi: {
-        context: VeloxContext;
-        route: VeloxRoute;
+        context: JDContext;
+        route: JDRoute;
     };
 }
-declare const fetchVeloxLayout: (apiUrl: string, slug: string, locale?: string, options?: RequestInit) => Promise<VeloxLayoutResponse | null>;
+declare const fetchJDLayout: (apiUrl: string, slug: string, locale?: string, options?: RequestInit) => Promise<JDLayoutResponse | null>;
 
-export { ComponentFactory, type ComponentFactoryProps, Placeholder, type PlaceholderProps, type VeloxContext, type VeloxLayoutResponse, type VeloxPlaceholderData, type VeloxRoute, fetchVeloxLayout };
+export { ComponentFactory, type ComponentFactoryProps, type JDContext, type JDLayoutResponse, type JDPlaceholderData, type JDRoute, Placeholder, type PlaceholderProps, fetchJDLayout };

package/dist/index.d.ts

@@ -16,27 +16,34 @@ interface PlaceholderProps {
 }
 declare const Placeholder: React.FC<PlaceholderProps>;
 
-interface VeloxPlaceholderData {
+interface JDPlaceholderData {
     __component: string;
     [key: string]: any;
 }
-interface VeloxRoute {
+interface JDRoute {
     name: string;
     displayName: string;
-    placeholders: Record<string, VeloxPlaceholderData[]>;
+    fields?: Record<string, any>;
+    seo?: {
+        metaTitle?: string;
+        metaDescription?: string;
+        metaImage?: any;
+        [key: string]: any;
+    };
+    placeholders: Record<string, JDPlaceholderData[]>;
 }
-interface VeloxContext {
+interface JDContext {
     pageEditing: boolean;
     site: Record<string, any>;
     language: string;
     locales: any[];
 }
-interface VeloxLayoutResponse {
+interface JDLayoutResponse {
     strapi: {
-        context: VeloxContext;
-        route: VeloxRoute;
+        context: JDContext;
+        route: JDRoute;
     };
 }
-declare const fetchVeloxLayout: (apiUrl: string, slug: string, locale?: string, options?: RequestInit) => Promise<VeloxLayoutResponse | null>;
+declare const fetchJDLayout: (apiUrl: string, slug: string, locale?: string, options?: RequestInit) => Promise<JDLayoutResponse | null>;
 
-export { ComponentFactory, type ComponentFactoryProps, Placeholder, type PlaceholderProps, type VeloxContext, type VeloxLayoutResponse, type VeloxPlaceholderData, type VeloxRoute, fetchVeloxLayout };
+export { ComponentFactory, type ComponentFactoryProps, type JDContext, type JDLayoutResponse, type JDPlaceholderData, type JDRoute, Placeholder, type PlaceholderProps, fetchJDLayout };

package/dist/index.js

@@ -32,7 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   ComponentFactory: () => ComponentFactory,
   Placeholder: () => Placeholder,
-  fetchVeloxLayout: () => fetchVeloxLayout
+  fetchJDLayout: () => fetchJDLayout
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -47,7 +47,7 @@ var ComponentFactory = ({
 }) => {
   const Component = componentMap[componentName];
   if (!Component) {
-    console.warn(`[Velox SDK] Component not found for: ${componentName}`);
+    console.warn(`[JD SDK] Component not found for: ${componentName}`);
     return /* @__PURE__ */ import_react.default.createElement("div", { style: {
       padding: "2rem",
       margin: "1rem",
@@ -87,19 +87,19 @@ var Placeholder = ({ name, rendering, customProps, componentMap }) => {
 };
 
 // src/index.ts
-var fetchVeloxLayout = async (apiUrl, slug, locale = "en", options) => {
+var fetchJDLayout = async (apiUrl, slug, locale = "en", options) => {
   try {
     const querySymbol = slug.includes("?") ? "&" : "?";
     const res = await fetch(`${apiUrl}/api/layout/${slug}${querySymbol}locale=${locale}`, {
       ...options
     });
     if (!res.ok) {
-      console.error(`[Velox SDK] Failed to fetch layout: ${res.statusText}`);
+      console.error(`[JD SDK] Failed to fetch layout: ${res.statusText}`);
       return null;
     }
     return await res.json();
   } catch (error) {
-    console.error(`[Velox SDK] Network error fetching layout`, error);
+    console.error(`[JD SDK] Network error fetching layout`, error);
     return null;
   }
 };
@@ -107,5 +107,5 @@ var fetchVeloxLayout = async (apiUrl, slug, locale = "en", options) => {
 0 && (module.exports = {
   ComponentFactory,
   Placeholder,
-  fetchVeloxLayout
+  fetchJDLayout
 });

package/dist/index.mjs

@@ -9,7 +9,7 @@ var ComponentFactory = ({
 }) => {
   const Component = componentMap[componentName];
   if (!Component) {
-    console.warn(`[Velox SDK] Component not found for: ${componentName}`);
+    console.warn(`[JD SDK] Component not found for: ${componentName}`);
     return /* @__PURE__ */ React.createElement("div", { style: {
       padding: "2rem",
       margin: "1rem",
@@ -49,24 +49,24 @@ var Placeholder = ({ name, rendering, customProps, componentMap }) => {
 };
 
 // src/index.ts
-var fetchVeloxLayout = async (apiUrl, slug, locale = "en", options) => {
+var fetchJDLayout = async (apiUrl, slug, locale = "en", options) => {
   try {
     const querySymbol = slug.includes("?") ? "&" : "?";
     const res = await fetch(`${apiUrl}/api/layout/${slug}${querySymbol}locale=${locale}`, {
       ...options
     });
     if (!res.ok) {
-      console.error(`[Velox SDK] Failed to fetch layout: ${res.statusText}`);
+      console.error(`[JD SDK] Failed to fetch layout: ${res.statusText}`);
       return null;
     }
     return await res.json();
   } catch (error) {
-    console.error(`[Velox SDK] Network error fetching layout`, error);
+    console.error(`[JD SDK] Network error fetching layout`, error);
     return null;
   }
 };
 export {
   ComponentFactory,
   Placeholder,
-  fetchVeloxLayout
+  fetchJDLayout
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-layout-sdk",
-  "version": "1.1.5",
-  "description": "React components for Velox SDK (Sitecore-like routing)",
+  "version": "1.1.7",
+  "description": "React components for JD SDK (Sitecore-like routing)",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/src/Placeholder.tsx

@@ -18,7 +18,7 @@ export const ComponentFactory: React.FC<ComponentFactoryProps> = ({
   const Component = componentMap[componentName];
 
   if (!Component) {
-    console.warn(`[Velox SDK] Component not found for: ${componentName}`);
+    console.warn(`[JD SDK] Component not found for: ${componentName}`);
     return (
       <div style={{
           padding: '2rem', 

package/src/index.ts

@@ -2,38 +2,45 @@ export { Placeholder, ComponentFactory } from './Placeholder';
 export type { PlaceholderProps, ComponentFactoryProps } from './Placeholder';
 
 // Useful type definitions for the API response
-export interface VeloxPlaceholderData {
+export interface JDPlaceholderData {
   __component: string;
   [key: string]: any;
 }
 
-export interface VeloxRoute {
+export interface JDRoute {
   name: string;
   displayName: string;
-  placeholders: Record<string, VeloxPlaceholderData[]>;
+  fields?: Record<string, any>;
+  seo?: {
+    metaTitle?: string;
+    metaDescription?: string;
+    metaImage?: any;
+    [key: string]: any;
+  };
+  placeholders: Record<string, JDPlaceholderData[]>;
 }
 
-export interface VeloxContext {
+export interface JDContext {
   pageEditing: boolean;
   site: Record<string, any>;
   language: string;
   locales: any[];
 }
 
-export interface VeloxLayoutResponse {
+export interface JDLayoutResponse {
   strapi: {
-    context: VeloxContext;
-    route: VeloxRoute;
+    context: JDContext;
+    route: JDRoute;
   }
 }
 
 // Hook / Utility function to fetch layout
-export const fetchVeloxLayout = async (
+export const fetchJDLayout = async (
     apiUrl: string, 
     slug: string, 
     locale: string = 'en',
     options?: RequestInit
-): Promise<VeloxLayoutResponse | null> => {
+): Promise<JDLayoutResponse | null> => {
     try {
         const querySymbol = slug.includes('?') ? '&' : '?';
         const res = await fetch(`${apiUrl}/api/layout/${slug}${querySymbol}locale=${locale}`, {
@@ -41,13 +48,13 @@ export const fetchVeloxLayout = async (
         });
 
         if (!res.ok) {
-            console.error(`[Velox SDK] Failed to fetch layout: ${res.statusText}`);
+            console.error(`[JD SDK] Failed to fetch layout: ${res.statusText}`);
             return null;
         }
 
-        return await res.json() as VeloxLayoutResponse;
+        return await res.json() as JDLayoutResponse;
     } catch (error) {
-        console.error(`[Velox SDK] Network error fetching layout`, error);
+        console.error(`[JD SDK] Network error fetching layout`, error);
         return null;
     }
 }