@lightspeed/crane 2.0.5 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 3.0.0 - 2026-02-25
+
+### Added
+
+- Add placeholder image for the Category and Product selector reference sections.
+- Add 'PRODUCT_SELECTOR' and 'CATEGORY_SELECTOR' type support for 'preview' mode.
+- Add missing properties support to 'TEXT' and 'LOGO' design editor defaults.
+- Add crane pull command to download source code for open source sections.
+- Add fetching of design settings into Instant Site for 'preview' mode.
+- Add support for previewing headers and footers.
+- Add '--blank' option to 'crane init --section' command to create empty sections with minimal files.
+- Add Section Collection support.
+- Add `--debug` flag to `preview` command for detailed debug logging.
+- Add partial build during hot reload in preview mode.
+- Add websocket to 'preview' mode for Chrome extension communication.
+
+### Changed
+
+- Unify input configuration file validation.
+- Migrate all template styles from SASS to native CSS
+- Update `featured-products` and `trending-categories` sections in reference templates.
+- Update internal import resolutions.
+- Updated dependencies
+  - @lightspeed/crane-api@2.0.0
+
+### Fixed
+
+- Fix validation of custom layout settings at the layout level instead of slots.
+- Support sections without layout files in 'preview' mode.
+
+### Removed
+
+- SCSS configuration from build system (Crane is now CSS framework agnostic)
+
 ## 2.0.5 - 2026-01-14
 
 ### Added

package/UPGRADE.md

@@ -1,5 +1,101 @@
 # Upgrades
 
+## 2.0.x to 2.1.x
+
+### Layout configuration changes
+
+1.) **Add `type` property to `selectedDesignSettings` entries**
+
+Each entry in `selectedDesignSettings` now requires a `type` property at the root level specifying the design editor type. Valid values: `TEXT`, `BUTTON`, `IMAGE`, `TOGGLE`, `SELECTBOX`, `BACKGROUND`, `COLOR_PICKER`, `LOGO`, `DIVIDER`.
+
+**Before:**
+```ts
+selectedDesignSettings: [
+  {
+    fieldName: 'image_text',
+    defaults: { font: 'global.fontFamily.body', size: 16, bold: true, italic: false, color: '#000000', visible: true },
+  },
+]
+```
+
+**After:**
+```ts
+selectedDesignSettings: [
+  {
+    type: 'TEXT',
+    fieldName: 'image_text',
+    defaults: { font: 'global.fontFamily.body', size: 16, bold: true, italic: false, color: '#000000', visible: true },
+  },
+]
+```
+
+Alternatively, use factory methods which handle the type automatically:
+```ts
+import { layout } from '@lightspeed/crane-api';
+
+selectedDesignSettings: [
+  layout.designOverride.text({
+    fieldName: 'image_text',
+    defaults: { font: 'global.fontFamily.body', size: 16, bold: true, italic: false, color: '#000000', visible: true },
+  }),
+]
+```
+
+2.) **Header content settings must match showcase content**
+
+If your header showcases include `logo` or `menu` content, you must also define these editors in your header's `content.ts` file. The schema validation ensures consistency between content settings and showcase content.
+
+The content editors defined in `content.ts` must include all keys referenced in showcase `content` objects.
+
+3.) **Define logo and menu in content.ts and design.ts when used in showcases**
+
+If you override `logo` or `menu` in a section’s showcase `content` or `design`, those keys must be defined in that section’s `content.ts` (for content) and `design.ts` (for design). Otherwise the build fails with `INVALID_SHOWCASE_CONTENT_ELEMENT` (“Element … is not defined in content.ts”) or `INVALID_SHOWCASE_DESIGN_ELEMENT` (“Element … is not defined in design.ts”). Add the missing `logo` and/or `menu` editors to the corresponding files.
+
+4.) **Migrate from single-page to multi-page template format**
+
+Single-page template descriptors are no longer supported. Templates must now use the multi-page structure with separate files for configuration and each page type.
+
+**Before (single file):**
+```
+templates/
+  example-template.ts     # Contains metadata + sections
+```
+
+```ts
+// example-template.ts
+export default {
+  metadata: { name: '...', description: '...', preview_url: '...', cover_image: { ... } },
+  sections: [ { type: 'default', id: 'header' }, { type: 'custom', id: 'example-section' }, ... ],
+};
+```
+
+**After (multi-page structure):**
+```
+templates/
+  example-template/
+    configuration.ts      # Metadata, header, footer
+    pages/
+      home.ts             # Home page sections
+      category.ts         # Category page sections
+      catalog.ts          # Catalog page sections
+      product.ts          # Product page sections
+      custom.ts           # Custom page sections (optional)
+```
+
+```ts
+// configuration.ts
+export default {
+  metadata: { name: '...', description: '...', categories: [...], preview_url: '...', cover_image: { ... } },
+  header: { type: 'default', id: 'header' },
+  footer: { type: 'default', id: 'footer' },
+};
+
+// pages/home.ts
+export default {
+  sections: [ { type: 'custom', id: 'example-section', showcase_id: '1' }, ... ],
+};
+```
+
 ## 1.x.x to 2.0.0
 
 ### Move app to new package named crane-api