@lightspeed/crane 1.3.2 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightspeed/crane",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "type": "module",
   "bin": "bin/crane.js",
   "main": "./dist/app.mjs",
@@ -62,7 +62,7 @@
   },
   "dependencies": {
     "@jridgewell/sourcemap-codec": "^1.4.15",
-    "@lightspeed/eslint-config-crane": "1.1.1",
+    "@lightspeed/eslint-config-crane": "1.1.2",
     "@types/prompts": "^2.4.2",
     "@vitejs/plugin-vue": "^4.1.0",
     "adm-zip": "^0.5.16",
@@ -72,7 +72,7 @@
     "axios-concurrency": "^1.0.4",
     "cac": "^6.7.14",
     "cli-progress": "^3.12.0",
-    "eslint": "9.22.0",
+    "eslint": "^9.33.0",
     "fs-extra": "^11.1.1",
     "glob": "^9.3.5",
     "jsonpath-plus": "^10.3.0",

package/template/_gitignore

@@ -9,6 +9,7 @@ lerna-debug.log*
 
 node_modules
 dist
+preview
 dist-ssr
 *.local
 crane.config.json

package/template/preview/sections/preview.html

@@ -109,6 +109,8 @@
 
     // Render the showcase
     renderShowcase(sectionName, showcaseId);
+    fetch(`${window.location.origin}/chosen-section/${sectionName}`)
+      .catch(console.error);
   });
 
   // Restore saved showcase or render first available

package/template/preview/shared/mock.ts

@@ -0,0 +1,175 @@
+
+export type ExternalContentMock = ExternalContentData
+
+/**
+ * Default mock configuration
+ * Users can modify this in the compiled mock.js file
+ */
+export const externalContentMock: ExternalContentMock = {
+  site: {
+    isPreviewMode: true,
+    account: {
+      title: 'My Account',
+      url: '/account',
+      target: '_self'
+    },
+    cart: {
+      url: '/cart',
+      count: 3
+    },
+    languages: [
+      {
+        code: 'en',
+        description: 'English',
+        main: true,
+        selected: true,
+        url: '/en'
+      },
+      {
+        code: 'es',
+        description: 'Español',
+        main: false,
+        selected: false,
+        url: '/es'
+      }
+    ],
+    legalPages: [
+      {
+        title: 'Privacy Policy',
+        url: '/privacy'
+      },
+      {
+        title: 'Terms of Service',
+        url: '/terms'
+      },
+      {
+        title: 'Refund Policy',
+        url: '/refunds'
+      }
+    ],
+    reportAbuse: {
+      title: 'Report Abuse',
+      url: '/report-abuse',
+      target: '_blank'
+    },
+    madeWith: {
+      url: 'https://www.lightspeedhq.com',
+      target: '_blank',
+      icon: '/assets/lightspeed-icon.png',
+      poweredBy: 'Powered by',
+      company: 'Lightspeed'
+    }
+  },
+
+  category: {
+    categories: [
+      {
+        id: 1,
+        name: 'Electronics',
+        url: '/categories/electronics',
+        imageUrl: '/assets/electronics-category.jpg',
+        thumbnailImageUrl: '/assets/electronics-thumb.jpg',
+        alt: 'Electronics category',
+        imageBorderInfo: {
+          homogeneity: true,
+          color: {
+            r: 255,
+            g: 255,
+            b: 255,
+            a: 1
+          }
+        }
+      },
+      {
+        id: 2,
+        name: 'Clothing',
+        url: '/categories/clothing',
+        imageUrl: '/assets/clothing-category.jpg',
+        thumbnailImageUrl: '/assets/clothing-thumb.jpg',
+        alt: 'Clothing category'
+      },
+      {
+        id: 3,
+        name: 'Home & Garden',
+        url: '/categories/home-garden',
+        imageUrl: '/assets/home-garden-category.jpg',
+        thumbnailImageUrl: '/assets/home-garden-thumb.jpg',
+        alt: 'Home & Garden category'
+      }
+    ],
+    categoryTree: [
+      {
+        id: 1,
+        name: 'Electronics',
+        nameTranslated: {
+          en: 'Electronics',
+          es: 'Electrónicos'
+        },
+        urlPath: '/electronics',
+        enabled: true,
+        children: [
+          {
+            id: 11,
+            name: 'Smartphones',
+            nameTranslated: {
+              en: 'Smartphones',
+              es: 'Teléfonos inteligentes'
+            },
+            urlPath: '/electronics/smartphones',
+            enabled: true,
+            children: []
+          },
+          {
+            id: 12,
+            name: 'Laptops',
+            nameTranslated: {
+              en: 'Laptops',
+              es: 'Portátiles'
+            },
+            urlPath: '/electronics/laptops',
+            enabled: true,
+            children: []
+          }
+        ]
+      },
+      {
+        id: 2,
+        name: 'Clothing',
+        nameTranslated: {
+          en: 'Clothing',
+          es: 'Ropa'
+        },
+        urlPath: '/clothing',
+        enabled: true,
+        children: [
+          {
+            id: 21,
+            name: 'Men\'s Clothing',
+            nameTranslated: {
+              en: 'Men\'s Clothing',
+              es: 'Ropa para hombres'
+            },
+            urlPath: '/clothing/mens',
+            enabled: true,
+            children: []
+          },
+          {
+            id: 22,
+            name: 'Women\'s Clothing',
+            nameTranslated: {
+              en: 'Women\'s Clothing',
+              es: 'Ropa para mujeres'
+            },
+            urlPath: '/clothing/womens',
+            enabled: true,
+            children: []
+          }
+        ]
+      }
+    ]
+  }
+};
+
+export function getExternalContentMock(): ExternalContentMock {
+  return externalContentMock;
+}

package/template/preview/shared/preview.ts

@@ -1,8 +1,10 @@
 /* eslint-disable no-console */
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { loadModule} from "./utils.ts";
+import { getExternalContentMock } from "./mock";
 
 let distFolderPath: string | null = null;
+let currentApp: any = null;
 
 export function setDistFolderPath(path: string): void {
   distFolderPath = path;
@@ -28,13 +30,15 @@ interface ColorObject {
 }
 
 function hexToColorObject(hex: string): ColorObject {
-  const match = /^#?([0-9a-fA-F]{6})$/.exec(hex);
+  // Support both 6-digit (#RRGGBB) and 8-digit (#RRGGBBAA) hex colors
+  const match = /^#?([0-9a-fA-F]{6}([0-9a-fA-F]{2})?)$/.exec(hex);
   if (!match) throw new Error("Invalid hex color format");
   const cleanHex = match[1].toLowerCase();
   const r = parseInt(cleanHex.substring(0, 2), 16);
   const g = parseInt(cleanHex.substring(2, 4), 16);
   const b = parseInt(cleanHex.substring(4, 6), 16);
-  const a = 255;
+  // Extract alpha if present (8-digit hex), otherwise default to 255 (fully opaque)
+  const a = cleanHex.length === 8 ? parseInt(cleanHex.substring(6, 8), 16) : 255;
   const rNorm = r / 255, gNorm = g / 255, bNorm = b / 255;
   const max = Math.max(rNorm, gNorm, bNorm), min = Math.min(rNorm, gNorm, bNorm);
   const delta = max - min;
@@ -50,15 +54,15 @@ function hexToColorObject(hex: string): ColorObject {
     if (h < 0) h += 360;
   }
   return {
-    hex: `#${cleanHex}${a.toString(16).padStart(2, '0')}`,
+    hex: `#${cleanHex.substring(0, 6)}${a.toString(16).padStart(2, '0')}`,
     hsl: { h: Math.round(h), s: +(s * 100).toFixed(1), l: +(l * 100).toFixed(1) },
-    rgba: { r, g, b, a: 1 },
+    rgba: { r, g, b, a: +(a / 255).toFixed(2) },
   };
 }
 
 function updateHexColors(obj: any): any {
-  // Matches either 3-digit (#RGB) or 6-digit (#RRGGBB) hex
-  const hexRegex = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+  // Matches 3-digit (#RGB), 6-digit (#RRGGBB), or 8-digit (#RRGGBBAA) hex
+  const hexRegex = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
 
   function recurse(value: any): any {
     if (Array.isArray(value)) return value.map(recurse);
@@ -92,6 +96,77 @@ const replaceGlobalFont = (obj: any, font: string): void => {
   });
 };
 
+function createBackgroundStructure(type: 'solid' | 'gradient', config: any): any {
+  return {
+    background: {
+      background: {
+        type,
+        ...config,
+      },
+    },
+  };
+}
+
+// Helper function to create default gray background
+function createDefaultBackground(): any {
+  const defaultGrayColor = hexToColorObject('#F9F9F9');
+  return createBackgroundStructure('solid', {
+    solid: { color: defaultGrayColor },
+    color: 'global.color.background',
+  });
+}
+
+// Helper function to check if color is global reference
+function isGlobalColor(color: string): boolean {
+  return typeof color === 'string' && color.startsWith('global.');
+}
+
+function createBackgroundDesign(showcaseBackground: any): any {
+  // No background or invalid background
+  if (!showcaseBackground) {
+    return createDefaultBackground();
+  }
+
+  // Handle gradient backgrounds
+  if (showcaseBackground.style === 'GRADIENT' && Array.isArray(showcaseBackground.color)) {
+    const [fromColor, toColor] = showcaseBackground.color;
+
+    // If either color is global, use default
+    if (isGlobalColor(fromColor) || isGlobalColor(toColor)) {
+      return createDefaultBackground();
+    }
+
+    // Create gradient background
+    return createBackgroundStructure('gradient', {
+      solid: { color: hexToColorObject(fromColor) },
+      gradient: {
+        fromColor: hexToColorObject(fromColor),
+        toColor: hexToColorObject(toColor),
+      },
+      color: `gradient(${fromColor}, ${toColor})`,
+    });
+  }
+
+  // Handle solid color backgrounds
+  const solidColor = showcaseBackground.color;
+
+  // Global color reference
+  if (isGlobalColor(solidColor)) {
+    return createDefaultBackground();
+  }
+
+  // Specific hex color
+  if (typeof solidColor === 'string') {
+    return createBackgroundStructure('solid', {
+      solid: { color: hexToColorObject(solidColor) },
+      color: solidColor,
+    });
+  }
+
+  // Fallback to default
+  return createDefaultBackground();
+}
+
 function overrideSettingsFromShowcase(content: any, showcases: any): any {
   return Object.fromEntries(Object.entries(content).map(([k, v]) => [k, showcases[k] ?? v]));
 }
@@ -256,28 +331,14 @@ export async function renderShowcase(sectionName: string, showcaseId: string): P
   const showcase = await loadModule(`${distFolderPath}/sections/${sectionName}/js/showcases/${showcaseId}.mjs`);
   const design = await loadModule(`${distFolderPath}/sections/${sectionName}/js/settings/design.mjs`);
 
-  const { mount } = client.default.init();
+  // Get showcase background and create background design
+  const showcaseBackground = showcase.default?.design?.background;
+  const backgroundDesign = createBackgroundDesign(showcaseBackground);
 
   const ovveridenDesign = designTransformer(design.default, showcase.default.design || {});
 
   loadSectionCss(sectionName);
 
-  const backgroundDesign = {
-    background: {
-      background: {
-        type: 'solid',
-        solid: {
-          color: {
-            raw: '#F9F9F9',
-            hex: '#F9F9F9',
-            rgba: { r: 19, g: 19, b: 19, a: 1.0 },
-          },
-        },
-        color: 'global.color.background',
-      },
-    },
-  };
-
   const overriddenContent = getContentToRender(
     content.default,
     showcase.default.content || {},
@@ -286,15 +347,32 @@ export async function renderShowcase(sectionName: string, showcaseId: string): P
     sectionName
   );
 
-  mount('#app', {
+  // Get external content mock (can be customized in compiled mock.js)
+  const externalContentMock = getExternalContentMock();
+
+  // Ensure background design always overrides any existing background
+  const finalDesign = { ...ovveridenDesign };
+  finalDesign.background = backgroundDesign.background;
+
+  const state = {
     context: {
       globalDesign: { color: 'global.color.background' },
     },
     data: {
       content: overriddenContent,
-      design: { ...ovveridenDesign, ...backgroundDesign },
+      design: finalDesign,
       defaults: {},
       background: {},
+      externalContent: externalContentMock,
     },
-  });
+  };
+
+  // If app is already mounted, update it; otherwise mount it
+  if (currentApp) {
+    currentApp.update(state);
+  } else {
+    const { mount, update, unmount } = client.default.init();
+    currentApp = { update, unmount };
+    mount('#app', state);
+  }
 }

package/template/preview/vite.config.js

@@ -1,9 +1,11 @@
-import { defineConfig } from 'vite';
+import {defineConfig} from 'vite';
+import path from "path";
+import fs from "fs";
 
 export default defineConfig({
   root: '.',
   server: {
-    fs: { strict: false },
+    fs: {strict: false},
   },
   plugins: [
     {
@@ -19,13 +21,53 @@ export default defineConfig({
     {
       name: 'no-vite-cache',
       configureServer(server) {
-        // invalidate caches so that after build when user refreshes the page, the latest .mjs files are fetched
+        // use process.cwd() for analytics path
+        const analyticsDir = path.resolve(process.cwd(), 'preview', 'shared')
+        const analyticsFile = path.resolve(analyticsDir, 'analytics.json')
+
+        // ensure analytics folder & file exist
+        fs.mkdirSync(analyticsDir, {recursive: true})
+        if (!fs.existsSync(analyticsFile)) {
+          fs.writeFileSync(analyticsFile, JSON.stringify({}, null, 2), 'utf-8')
+        }
+
+        // helper to bump and persist counter for a given section
+        function bumpSectionCount(section) {
+          const raw = fs.readFileSync(analyticsFile, 'utf-8')
+          const data = JSON.parse(raw)
+          const next = (data[section] || 0) + 1
+          data[section] = next
+          fs.writeFileSync(analyticsFile, JSON.stringify(data, null, 2), 'utf-8')
+          return next
+        }
+
         server.middlewares.use((req, res, next) => {
-          if (req.url?.includes('/sections/')) {
-            server.moduleGraph.invalidateAll();
+            const url = req.url || ''
+
+            // cache-bust for any /sections/ URL
+            if (url.includes('/sections/')) {
+              server.moduleGraph.invalidateAll()
+              return next()
+            }
+
+            if (url.startsWith('/chosen-section')) {
+              // extract "sectionName" from "/chosen-section/<sectionName>"
+
+              const sectionName = req.url.replace(/\/$/, '').split('/').filter(Boolean).pop()
+              const newCount = bumpSectionCount(sectionName)
+
+              res.statusCode = 200
+              res.setHeader('Content-Type', 'application/json')
+              return res.end(JSON.stringify({
+                section: sectionName,
+                count: newCount
+              }))
+            }
+
+            // all other requests
+            next()
           }
-          next();
-        });
+        );
       },
     },
   ],

package/template/reference/templates/reference-template-apparel/configuration.ts

@@ -0,0 +1,22 @@
+export default {
+  metadata: {
+    name: 'Reference Template — Apparel',
+    description: 'This is a reference template geared towards apparel merchants to aid development and act as a starting point for your custom template.',
+    preview_url: 'https://reference-template-apparel.company.site/',
+    cover_image: {
+      set: {
+        ORIGINAL: {
+          url: 'reference_template_apparel_cover_image.jpg',
+        },
+      },
+    },
+  },
+  header: {
+    type: 'default',
+    id: 'header',
+  },
+  footer: {
+    type: 'default',
+    id: 'footer',
+  },
+};

package/template/reference/templates/reference-template-apparel/pages/catalog.ts

@@ -0,0 +1,10 @@
+import { StorePageConfiguration } from '@lightspeed/crane';
+
+export default {
+  sections: [
+    {
+      type: 'store',
+      id: undefined,
+    },
+  ],
+} satisfies StorePageConfiguration;

package/template/reference/templates/reference-template-apparel/pages/category.ts

@@ -0,0 +1,10 @@
+import { StorePageConfiguration } from '@lightspeed/crane';
+
+export default {
+  sections: [
+    {
+      type: 'store',
+      id: undefined,
+    },
+  ],
+} satisfies StorePageConfiguration;

package/template/reference/templates/reference-template-apparel/pages/home.ts

@@ -0,0 +1,24 @@
+export default {
+  sections: [
+    {
+      type: 'custom',
+      id: 'intro-slider',
+      showcase_id: '1',
+    },
+    {
+      type: 'custom',
+      id: 'tag-lines',
+      showcase_id: '1',
+    },
+    {
+      type: 'custom',
+      id: 'about-us',
+      showcase_id: '1',
+    },
+    {
+      type: 'custom',
+      id: 'example-section',
+      showcase_id: '1',
+    },
+  ],
+};

package/template/reference/templates/reference-template-apparel/pages/product.ts

@@ -0,0 +1,10 @@
+import { StorePageConfiguration } from '@lightspeed/crane';
+
+export default {
+  sections: [
+    {
+      type: 'store',
+      id: undefined,
+    },
+  ],
+} satisfies StorePageConfiguration;

package/template/reference/templates/reference-template-bike/configuration.ts

@@ -0,0 +1,22 @@
+export default {
+  metadata: {
+    name: 'Reference Template — Bike',
+    description: 'This is a reference template geared towards bike shops to aid development and act as a starting point for your custom template.',
+    preview_url: 'https://reference-template-bike.company.site/',
+    cover_image: {
+      set: {
+        ORIGINAL: {
+          url: 'reference_template_bike_cover_image.jpg',
+        },
+      },
+    },
+  },
+  header: {
+    type: 'default',
+    id: 'header',
+  },
+  footer: {
+    type: 'default',
+    id: 'footer',
+  },
+};

package/template/reference/templates/reference-template-bike/pages/catalog.ts

@@ -0,0 +1,10 @@
+import { StorePageConfiguration } from '@lightspeed/crane';
+
+export default {
+  sections: [
+    {
+      type: 'store',
+      id: undefined,
+    },
+  ],
+} satisfies StorePageConfiguration;

package/template/reference/templates/reference-template-bike/pages/category.ts

@@ -0,0 +1,10 @@
+import { StorePageConfiguration } from '@lightspeed/crane';
+
+export default {
+  sections: [
+    {
+      type: 'store',
+      id: undefined,
+    },
+  ],
+} satisfies StorePageConfiguration;

package/template/reference/templates/reference-template-bike/pages/home.ts

@@ -0,0 +1,24 @@
+export default {
+  sections: [
+    {
+      type: 'custom',
+      id: 'intro-slider',
+      showcase_id: '2',
+    },
+    {
+      type: 'custom',
+      id: 'example-section',
+      showcase_id: '3',
+    },
+    {
+      type: 'custom',
+      id: 'tag-lines',
+      showcase_id: '2',
+    },
+    {
+      type: 'custom',
+      id: 'about-us',
+      showcase_id: '2',
+    },
+  ],
+};

package/template/reference/templates/reference-template-bike/pages/product.ts

@@ -0,0 +1,10 @@
+import { StorePageConfiguration } from '@lightspeed/crane';
+
+export default {
+  sections: [
+    {
+      type: 'store',
+      id: undefined,
+    },
+  ],
+} satisfies StorePageConfiguration;