feat(design): add component registry

feat(design): move design components out of sdk

feat(design): add messaging api

fix types

upgrade typescript to support esm modules

cleanup messenger on disconnect

make scrolling isomorphic

feat(design): add hover bounds events (#220)

feat: refine connection logic for design layer

feat(pd): add design context and wrapper @W-19432252 (#222)

* feat(pd): add design context and wrapper

feat(design): add more interactions and cleanup (#223)

feat: drag and drop from palette @W-19284238 (#226)

* feature(design): add drag and drop support for regions

* rework drag and drop

* add local dragging logic

* add drop target styles

* fix styles

* fix decorator render order

* feat: add unit test + build fixes

* fix: styling

* fix: nodeToTargetMap being empty + update tests

* fix: add back region green border

* fix: test + bad css merge

* fix: region decorator tests

---------

Co-authored-by: Steven Sojka <[email protected]>

Feature/drag and drop move (#237)

* feature(design): add drag and drop support for regions

* rework drag and drop

* add local dragging logic

* add drop target styles

* fix styles

* fix decorator render order

* polish move

* get parent id from context

update styles and add design tests

Author: steelsojka

.eslintrc.json

@@ -89,7 +89,12 @@
           "plugin:@typescript-eslint/recommended-requiring-type-checking"
         ],
         "rules": {
-          "@typescript-eslint/explicit-module-boundary-types": "error"
+          "@typescript-eslint/explicit-module-boundary-types": "error",
+          "react/jsx-filename-extension": [1, { "extensions": [".tsx"] }],
+          "no-use-before-define": "off",
+          "import/prefer-default-export": "off",
+          "@typescript-eslint/no-use-before-define": "error",
+          "import/no-unresolved": "off"
         }
       },
       {

.github/workflows/test.yml

@@ -30,4 +30,6 @@ jobs:
         if: ${{ steps.cache-nodemodules.outputs.cache-hit != 'true' }}
       - run: yarn run renderTemplates
       - run: yarn build:lib
+      - run: yarn build:design
       - run: yarn test
+      - run: yarn test:design

babel.config.jest.js

@@ -16,6 +16,7 @@ module.exports = {
       },
     ],
     '@babel/typescript',
+    '@babel/preset-react',
   ],
   ignore: ['node_modules/**'],
 };

package.json

@@ -109,7 +109,27 @@
       "import": "./lib/version.js",
       "require": "./lib/version.cjs.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./design": {
+      "import": {
+        "default": "./lib/design/esm/index.js",
+        "types": "./lib/design/esm/index.d.ts"
+      },
+      "require": {
+        "default": "./lib/design/cjs/index.js",
+        "types": "./lib/design/cjs/index.d.ts"
+      }
+    },
+    "./design/react": {
+      "import": {
+        "default": "./lib/design/esm/react/index.js",
+        "types": "./lib/design/esm/react/index.d.ts"
+      },
+      "require": {
+        "default": "./lib/design/cjs/react/index.js",
+        "types": "./lib/design/cjs/react/index.d.ts"
+      }
+    }
   },
   "main": "lib/index.cjs.js",
   "module": "lib/index.esm.js",
@@ -122,8 +142,10 @@
   "scripts": {
     "build": "react-scripts build",
     "build:lib": "ts-node --compiler-options '{\"module\": \"commonjs\", \"target\": \"ES6\" }' ./scripts/generateFileList.ts && rollup -c",
+    "build:design": "tsc -p tsconfig.design.json && tsc -p tsconfig.design.json --module commonjs --outDir lib/design/cjs && yarn build:design:copy",
+    "build:design:copy": "cpx 'src/design/**/*.css' lib/design/cjs && cpx 'src/design/**/*.css' lib/design/esm",
     "check:size": "npm-pack-all --output commerce-sdk-isomorphic-with-deps.tgz && bundlesize",
-    "check:types": "tsc --noEmit",
+    "check:types": "tsc -p tsconfig.sdk.json --noEmit",
     "ci": "rm -rf node_modules && yarn install",
     "clean": "rm -rf build lib src/lib commerce-sdk-isomorphic-with-deps.tgz",
     "depcheck": "depcheck",
@@ -135,14 +157,15 @@
     "fix:style": "yarn run lint:style -- --fix",
     "generateVersionTable": "ts-node --compiler-options '{\"module\": \"commonjs\", \"target\": \"ES6\" }' ./scripts/generateVersionTable.ts",
     "lint": "eslint --ext js,jsx,ts,tsx .",
-    "lint:style": "stylelint ./src/",
+    "lint:style": "stylelint ./src/**/*.css",
     "prepare": "snyk protect",
     "renderTemplates": "PACKAGE_VERSION=$(node -p \"require('./package.json').version\") ts-node --compiler-options '{\"module\": \"commonjs\", \"target\": \"ES6\" }' ./scripts/generate-oas.ts",
     "start": "HTTPS=true react-scripts start",
     "pretest": "yarn run lint && yarn run lint:style && depcheck && yarn run check:size",
     "test": "yarn run check:types && yarn run test:unit && CI=true yarn run test:react",
+    "test:design": "jest --config src/design/jest.config.js src/design",
     "test:react": "react-scripts test --env=jest-environment-jsdom-sixteen src/environment --setupFilesAfterEnv ./src/test/setupTests.ts",
-    "test:unit": "jest --coverage --testPathIgnorePatterns node_modules src/environment --silent",
+    "test:unit": "jest --coverage --testPathIgnorePatterns node_modules src/design src/environment --silent",
     "updateApis": "ts-node --compiler-options '{\"module\": \"commonjs\", \"target\": \"ES6\" }' ./scripts/updateApis.ts && yarn diffApis"
   },
   "husky": {
@@ -203,6 +226,7 @@
     "@typescript-eslint/parser": "^4.33.0",
     "autoprefixer": "9.8.8",
     "bundlesize2": "^0.0.31",
+    "cpx": "^1.5.0",
     "depcheck": "^1.4.3",
     "dotenv": "^16.0.3",
     "eslint": "^7.32.0",
@@ -242,6 +266,7 @@
     "stylelint": "13.13.1",
     "stylelint-config-standard": "20.0.0",
     "stylelint-order": "4.1.0",
+    "ts-jest": "26.x.x",
     "ts-node": "9.1.1",
     "typedoc": "^0.17.7",
     "typedoc-plugin-external-module-map": "1.2.1",

rollup.config.js

@@ -53,7 +53,10 @@ const sharedPlugins = [
   ts({
     transpiler: 'babel',
     // Setting noEmit directly in the tsconfig triggers a react testing bug so we override it here
-    tsconfig: resolvedConfig => ({...resolvedConfig, noEmit: false}),
+    tsconfig: {
+      fileName: 'tsconfig.sdk.json',
+      hook: resolvedConfig => ({...resolvedConfig, noEmit: false}),
+    },
     exclude: 'node_modules/**',
   }),
   babel({

src/design/componentRegistry.test.ts

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+import {ComponentRegistry} from './componentRegistry';
+import {isDesignModeActive} from './modeDetection';
+
+type TestComponent = {name: string};
+
+jest.mock('./modeDetection', () => ({
+  isDesignModeActive: jest.fn().mockReturnValue(true),
+}));
+
+describe('design/componentRegistry', () => {
+  let designMode = false;
+  let registry: ComponentRegistry<TestComponent>;
+
+  beforeEach(() => {
+    designMode = false;
+
+    (isDesignModeActive as jest.Mock).mockImplementation(() => designMode);
+
+    registry = new ComponentRegistry<TestComponent>({
+      designDecorator: component => ({
+        ...component,
+        name: `${component.name}-design`,
+      }),
+    });
+  });
+
+  describe('when registering a component', () => {
+    it('should set the component in the registry', () => {
+      registry.registerComponent('test', {name: 'test'});
+      expect(registry.getComponent('test')).toEqual({name: 'test'});
+    });
+
+    describe('when getting a component in design mode', () => {
+      beforeEach(() => {
+        designMode = true;
+      });
+
+      it('should get the decorated component', () => {
+        registry.registerComponent('test', {name: 'test'});
+        expect(registry.getComponent('test')).toEqual({
+          name: 'test-design',
+        });
+      });
+    });
+  });
+
+  describe("when getting a component that doesn't exist in the registry", () => {
+    it('should return null', () => {
+      expect(registry.getComponent('blorg')).toBeNull();
+    });
+  });
+});

src/design/componentRegistry.ts

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import {isDesignModeActive} from './modeDetection';
+/**
+ * A generic registry for managing components with support for design-time decoration.
+ * This registry allows components to be registered and retrieved in different modes,
+ * with optional decoration for design-time usage.
+ *
+ * @template TComponent - The type of components stored in this registry
+ * @example
+ * import type React from 'react';
+ * import pkg from 'commerce-sdk-isomorphic';
+ * const { design: { ComponentRegistry, createReactDesignDecorator } } = pkg;
+ *
+ * const registry = new ComponentRegistry<React.Component>({
+ *   designDecorator: createReactDesignDecorator(),
+ * });
+ *
+ * registry.registerComponent('commerce/productList', ProductListComponent);
+ *
+ * const ProductList = registry.getComponent('commerce/productList');
+ *
+ * // Get the component in design mode - the component will be decorated
+ * const ProductList = registry.getComponent('commerce/productList');
+ */
+export class ComponentRegistry<TComponent> {
+  private readonly registry = new Map<string, TComponent>();
+
+  private readonly designDecorator: (component: TComponent) => TComponent;
+
+  /**
+   * @param options - Configuration options for the registry
+   * @param options.designDecorator - Optional function to decorate components when retrieved in design mode.
+   *                                  If not provided, components are returned unchanged in design mode.
+   */
+  constructor({
+    designDecorator = component => component,
+  }: {
+    designDecorator?: (component: TComponent) => TComponent;
+  } = {}) {
+    this.designDecorator = designDecorator;
+  }
+
+  /**
+   * Registers a component in the registry with the specified name.
+   * If a component with the same name already exists, it will be overwritten.
+   *
+   * @param name - The unique identifier for the component
+   * @param component - The component to register
+   */
+  registerComponent(name: string, component: TComponent): void {
+    this.registry.set(name, component);
+  }
+
+  /**
+   * Retrieves a component from the registry by its identifier.
+   * The component may be decorated based on the specified mode.
+   *
+   * @param id - The identifier of the component to retrieve
+   * @param options - Options for component retrieval
+   * @param options.mode - The mode in which to retrieve the component. Defaults to 'runtime'.
+   * @returns The component if found, null otherwise. In design mode, the component will be decorated.
+   */
+  getComponent(id: string): TComponent | null {
+    const component = this.registry.get(id) ?? null;
+
+    return component && isDesignModeActive()
+      ? this.designDecorator(component)
+      : component;
+  }
+}

src/design/index.ts

@@ -0,0 +1,9 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: BSD-3-Clause
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+export * from './componentRegistry';
+export * from './messaging-api/index';
+export {isDesignModeActive, isPreviewModeActive} from './modeDetection';

src/design/jest.config.js

@@ -0,0 +1,13 @@
+/* eslint-disable */
+module.exports = {
+  displayName: 'design',
+  testEnvironment: 'jsdom',
+  passWithNoTests: true,
+  transform: {
+    '^.+\\.[tj]sx?$': ['ts-jest', {tsconfig: '<rootDir>/tsconfig.json'}]
+  },
+  moduleNameMapper: {
+    '\\.(css|less|scss|sass)$': '<rootDir>/test/styleMock.js',
+  },
+  moduleFileExtensions: ['ts', 'js', 'html', 'tsx', 'jsx'],
+};