@wix/zero-config-implementation 1.5.0

package/dist/schema.d.ts

@@ -0,0 +1,167 @@
+export declare const DATA: {
+    DATA_TYPE: {
+        readonly UNKNOWN_DataType: "UNKNOWN_DataType";
+        readonly text: "text";
+        readonly textEnum: "textEnum";
+        readonly number: "number";
+        readonly booleanValue: "booleanValue";
+        readonly a11y: "a11y";
+        readonly link: "link";
+        readonly image: "image";
+        readonly video: "video";
+        readonly vectorArt: "vectorArt";
+        readonly audio: "audio";
+        readonly schema: "schema";
+        readonly localDate: "localDate";
+        readonly localTime: "localTime";
+        readonly localDateTime: "localDateTime";
+        readonly webUrl: "webUrl";
+        readonly email: "email";
+        readonly phone: "phone";
+        readonly hostname: "hostname";
+        readonly regex: "regex";
+        readonly guid: "guid";
+        readonly richText: "richText";
+        readonly container: "container";
+        readonly arrayItems: "arrayItems";
+        readonly direction: "direction";
+        readonly menuItems: "menuItems";
+        readonly data: "data";
+        readonly function: "function";
+        readonly onClick: "onClick";
+        readonly onChange: "onChange";
+        readonly onKeyPress: "onKeyPress";
+        readonly onKeyUp: "onKeyUp";
+        readonly onSubmit: "onSubmit";
+    };
+    A11Y_ATTRIBUTES: {
+        readonly Unknown_AriaAttributes: "Unknown_AriaAttributes";
+        readonly tabIndex: "tabIndex";
+        readonly ariaLevel: "ariaLevel";
+        readonly ariaExpanded: "ariaExpanded";
+        readonly ariaDisabled: "ariaDisabled";
+        readonly ariaAtomic: "ariaAtomic";
+        readonly ariaHidden: "ariaHidden";
+        readonly ariaBusy: "ariaBusy";
+        readonly multiline: "multiline";
+        readonly ariaAutocomplete: "ariaAutocomplete";
+        readonly ariaPressed: "ariaPressed";
+        readonly ariaHaspopup: "ariaHaspopup";
+        readonly ariaRelevant: "ariaRelevant";
+        readonly role: "role";
+        readonly ariaLive: "ariaLive";
+        readonly ariaCurrent: "ariaCurrent";
+        readonly ariaLabel: "ariaLabel";
+        readonly ariaRoledescription: "ariaRoledescription";
+        readonly ariaDescribedby: "ariaDescribedby";
+        readonly ariaLabelledby: "ariaLabelledby";
+        readonly ariaErrormessage: "ariaErrormessage";
+        readonly ariaOwns: "ariaOwns";
+        readonly ariaControls: "ariaControls";
+        readonly tag: "tag";
+        readonly ariaMultiline: "ariaMultiline";
+        readonly ariaInvalid: "ariaInvalid";
+    };
+    LINK_TYPE: {
+        readonly UNKNOWN_LinkType: "UNKNOWN_LinkType";
+        readonly externalLink: "externalLink";
+        readonly anchorLink: "anchorLink";
+        readonly emailLink: "emailLink";
+        readonly phoneLink: "phoneLink";
+        readonly dynamicPageLink: "dynamicPageLink";
+        readonly pageLink: "pageLink";
+        readonly whatsAppLink: "whatsAppLink";
+        readonly documentLink: "documentLink";
+        readonly popupLink: "popupLink";
+        readonly addressLink: "addressLink";
+        readonly edgeAnchorLinks: "edgeAnchorLinks";
+        readonly loginToWixLink: "loginToWixLink";
+    };
+};
+export declare const MEDIA: {
+    VIDEO_CATEGORY: {
+        readonly UNKNOWN_VideoCategoryTypes: "UNKNOWN_VideoCategoryTypes";
+        readonly VIDEO: "VIDEO";
+        readonly VIDEO_TRANSPARENT: "VIDEO_TRANSPARENT";
+        readonly VIDEO_OPAQUE: "VIDEO_OPAQUE";
+    };
+    VECTOR_ART_CATEGORY: {
+        readonly UNKNOWN_VectorArtCategoryTypes: "UNKNOWN_VectorArtCategoryTypes";
+        readonly SHAPE_ALL: "SHAPE_ALL";
+        readonly SHAPE_BASIC: "SHAPE_BASIC";
+        readonly SHAPE_ART: "SHAPE_ART";
+        readonly ICON_SOCIAL: "ICON_SOCIAL";
+        readonly SHAPE_DIVIDERS: "SHAPE_DIVIDERS";
+        readonly SHAPE_LOCATION: "SHAPE_LOCATION";
+        readonly SHAPE_DOCUMENTS: "SHAPE_DOCUMENTS";
+        readonly SHAPE_SOCIAL: "SHAPE_SOCIAL";
+        readonly SHAPE_ARROWS: "SHAPE_ARROWS";
+    };
+    IMAGE_CATEGORY: {
+        readonly UNKNOWN_CategoryName: "UNKNOWN_CategoryName";
+        readonly IMAGE: "IMAGE";
+        readonly IMAGE_BACKGROUND: "IMAGE_BACKGROUND";
+    };
+};
+export declare const ELEMENTS: {
+    ELEMENT_TYPE: {
+        readonly UNKNOWN_ElementType: "UNKNOWN_ElementType";
+        readonly inlineElement: "inlineElement";
+        readonly refElement: "refElement";
+    };
+};
+export interface DataItem {
+    displayName?: string;
+    defaultValue?: unknown;
+    dataType?: string;
+    text?: Record<string, unknown>;
+    number?: Record<string, unknown>;
+    booleanValue?: unknown;
+    textEnum?: {
+        options: Array<{
+            value: string;
+            displayName?: string;
+        }>;
+    };
+    arrayItems?: {
+        dataItem?: DataItem;
+    };
+    data?: {
+        items?: Record<string, DataItem>;
+    };
+    function?: Record<string, unknown>;
+    link?: {
+        linkTypes?: string[];
+    };
+    image?: {
+        category?: string;
+    };
+}
+export interface CssPropertyItem {
+    defaultValue?: string;
+}
+export interface CssCustomPropertyItem {
+    defaultValue?: string;
+}
+export interface EditorElement {
+    selector?: string;
+    displayName?: string;
+    data?: Record<string, DataItem>;
+    elements?: Record<string, ElementItem>;
+    cssProperties?: Record<string, CssPropertyItem>;
+    cssCustomProperties?: Record<string, CssCustomPropertyItem>;
+}
+export interface ElementItem {
+    elementType?: string;
+    inlineElement?: {
+        selector?: string;
+        displayName?: string;
+        data?: Record<string, DataItem>;
+        cssProperties?: Record<string, CssPropertyItem>;
+        cssCustomProperties?: Record<string, CssCustomPropertyItem>;
+        elements?: Record<string, ElementItem>;
+    };
+}
+export interface EditorReactComponent {
+    editorElement?: EditorElement;
+}

package/dist/ts-compiler.d.ts

@@ -0,0 +1,13 @@
+import { ResultAsync } from 'neverthrow';
+import { default as ts } from 'typescript';
+import { NotFoundError, ParseError } from './errors';
+/**
+ * Compile a TypeScript file into a ts.Program.
+ *
+ * @param filePath - Path to the TypeScript source file
+ * @returns The compiled TypeScript program on success
+ * @errors
+ * - {@link NotFoundError} — Source file does not exist (phase: `compile`)
+ * - {@link ParseError} — TypeScript config could not be parsed (phase: `compile`)
+ */
+export declare function compileTsFile(filePath: string): ResultAsync<ts.Program, InstanceType<typeof NotFoundError> | InstanceType<typeof ParseError>>;

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@wix/zero-config-implementation",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "version": "1.5.0",
+  "description": "Core library for extracting component manifests from JS and CSS files",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./jsx-runtime-loader": {
+      "import": "./dist/jsx-runtime-loader.js"
+    },
+    "./jsx-runtime-interceptor": {
+      "import": "./dist/jsx-runtime-interceptor.js"
+    }
+  },
+  "scripts": {
+    "build": "vite build",
+    "lint": "biome check src/",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --passWithNoTests",
+    "docs": "typedoc"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "lightningcss": "^1.31.1"
+  },
+  "devDependencies": {
+    "@faker-js/faker": "^10.2.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.1",
+    "case-anything": "^3.1.2",
+    "cheerio": "^1.2.0",
+    "modern-errors": "^7.1.4",
+    "modern-errors-cli": "^6.0.0",
+    "neverthrow": "^8.2.0",
+    "parse5": "^7.1.2",
+    "pkg-entry-points": "^1.1.1",
+    "react-docgen-typescript": "^2.4.0",
+    "read-package-up": "^11.0.0",
+    "tsconfck": "^3.1.6",
+    "typedoc": "^0.28.16",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "vite": "^7.3.1",
+    "vite-node": "^5.3.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.17"
+  },
+  "wix": {
+    "artifact": {
+      "groupId": "com.wixpress.npm",
+      "artifactId": "zero-config-implementation",
+      "targets": {
+        "static": false,
+        "docker": false
+      }
+    },
+    "validations": {
+      "postBuild": [
+        "lint",
+        "test"
+      ]
+    }
+  },
+  "falconPackageHash": "79168aff8f115865bd48bf546e449528bbdac723a1e22c1085e10a6b"
+}

package/src/component-loader.test.ts

@@ -0,0 +1,277 @@
+import { join } from 'node:path'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mockModuleRequire = vi.fn()
+
+vi.mock('node:module', () => ({
+  createRequire: () => mockModuleRequire,
+}))
+
+vi.mock('read-package-up', () => ({
+  readPackageUpSync: vi.fn(),
+}))
+
+vi.mock('pkg-entry-points', () => ({
+  getPackageEntryPoints: vi.fn(),
+}))
+
+import { getPackageEntryPoints } from 'pkg-entry-points'
+import type { NormalizedPackageJson } from 'read-package-up'
+import { readPackageUpSync } from 'read-package-up'
+import { createComponentLoader } from './component-loader'
+
+const mockReadPackageUp = vi.mocked(readPackageUpSync)
+const mockGetEntryPoints = vi.mocked(getPackageEntryPoints)
+
+const fakePkgDir = '/fake/project'
+const fakePkgJsonPath = join(fakePkgDir, 'package.json')
+
+function mockPackage(name: string) {
+  mockReadPackageUp.mockReturnValue({
+    packageJson: { name } as NormalizedPackageJson,
+    path: fakePkgJsonPath,
+  })
+}
+
+beforeEach(() => {
+  vi.resetAllMocks()
+  mockModuleRequire.mockImplementation(() => {
+    throw new Error('Cannot find module')
+  })
+})
+
+describe('createComponentLoader', () => {
+  it('returns error when no package.json is found', async () => {
+    mockReadPackageUp.mockReturnValue(undefined)
+
+    const result = await createComponentLoader('/some/Component.tsx')
+
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toBe('No package.json found')
+    }
+  })
+
+  it('returns error when package has no resolvable entry points', async () => {
+    mockPackage('my-pkg')
+    mockGetEntryPoints.mockResolvedValue({})
+
+    const result = await createComponentLoader(join(fakePkgDir, 'src/Component.tsx'))
+
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toContain('no resolvable entry point')
+      expect(result.error.message).toContain('my-pkg')
+    }
+  })
+
+  it('returns error when only types exports exist', async () => {
+    mockPackage('types-only')
+    mockGetEntryPoints.mockResolvedValue({
+      '.': [[['types'], './dist/index.d.ts']],
+    })
+
+    const result = await createComponentLoader(join(fakePkgDir, 'src/Component.tsx'))
+
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toContain('no loadable exports')
+    }
+  })
+
+  it('returns error with path when single entry point fails to load', async () => {
+    mockPackage('bad-entry')
+    mockGetEntryPoints.mockResolvedValue({
+      '.': [[['import'], './dist/index.js']],
+    })
+
+    const result = await createComponentLoader(join(fakePkgDir, 'src/Component.tsx'))
+
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toContain('Failed to load')
+      expect(result.error.message).toContain(join(fakePkgDir, 'dist/index.js'))
+    }
+  })
+
+  it('returns error when multiple subpath exports all fail to load', async () => {
+    mockPackage('multi-fail')
+    mockGetEntryPoints.mockResolvedValue({
+      './foo': [[['import'], './dist/foo.js']],
+      './bar': [[['import'], './dist/bar.js']],
+    })
+
+    const result = await createComponentLoader(join(fakePkgDir, 'src/Component.tsx'))
+
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toContain('Failed to load')
+    }
+  })
+
+  it('skips types-only entries in multi-subpath exports', async () => {
+    mockPackage('mixed-types')
+    mockGetEntryPoints.mockResolvedValue({
+      './types': [[['types'], './dist/types.d.ts']],
+      './runtime': [[['import'], './dist/does-not-exist.js']],
+    })
+
+    const result = await createComponentLoader(join(fakePkgDir, 'src/Component.tsx'))
+
+    // ./types should be skipped (selectBestPath returns undefined), ./runtime fails to load
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toContain('Failed to load')
+    }
+  })
+})
+
+describe('selectBestPath (via createComponentLoader)', () => {
+  it('prefers import condition over node and default', async () => {
+    mockPackage('prio-test')
+    mockGetEntryPoints.mockResolvedValue({
+      '.': [
+        [['default'], './dist/default.js'],
+        [['node'], './dist/node.js'],
+        [['import'], './dist/import.js'],
+      ],
+    })
+
+    const result = await createComponentLoader(join(fakePkgDir, 'src/Component.tsx'))
+
+    // Module load will fail since these are fake paths, but entryPath is in the error
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toContain(join(fakePkgDir, 'dist/import.js'))
+    }
+  })
+
+  it('falls back to node condition when import is not available', async () => {
+    mockPackage('node-fallback')
+    mockGetEntryPoints.mockResolvedValue({
+      '.': [
+        [['default'], './dist/default.js'],
+        [['node'], './dist/node.js'],
+      ],
+    })
+
+    const result = await createComponentLoader(join(fakePkgDir, 'src/Component.tsx'))
+
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toContain(join(fakePkgDir, 'dist/node.js'))
+    }
+  })
+
+  it('falls back to default condition when import and node are not available', async () => {
+    mockPackage('default-fallback')
+    mockGetEntryPoints.mockResolvedValue({
+      '.': [[['default'], './dist/default.js']],
+    })
+
+    const result = await createComponentLoader(join(fakePkgDir, 'src/Component.tsx'))
+
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toContain(join(fakePkgDir, 'dist/default.js'))
+    }
+  })
+
+  it('skips entries that include types condition', async () => {
+    mockPackage('skip-types')
+    mockGetEntryPoints.mockResolvedValue({
+      '.': [
+        [['import', 'types'], './dist/index.d.ts'],
+        [['import'], './dist/index.js'],
+      ],
+    })
+
+    const result = await createComponentLoader(join(fakePkgDir, 'src/Component.tsx'))
+
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toContain(join(fakePkgDir, 'dist/index.js'))
+    }
+  })
+})
+
+describe('error message quality', () => {
+  it('includes package name in error messages', async () => {
+    mockPackage('@scope/my-components')
+    mockGetEntryPoints.mockResolvedValue({})
+
+    const result = await createComponentLoader(join(fakePkgDir, 'src/Component.tsx'))
+
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toContain('@scope/my-components')
+    }
+  })
+
+  it('includes package.json path in no-entry-point error', async () => {
+    mockPackage('no-entry')
+    mockGetEntryPoints.mockResolvedValue({})
+
+    const result = await createComponentLoader(join(fakePkgDir, 'src/Component.tsx'))
+
+    expect(result.isErr()).toBe(true)
+    if (result.isErr()) {
+      expect(result.error.message).toContain(fakePkgJsonPath)
+    }
+  })
+})
+
+describe('component resolution behavior', () => {
+  it('fails today for direct named export when function name is minified', async () => {
+    const packageDir = '/fake/minified-export-test'
+    const packageJsonPath = join(packageDir, 'package.json')
+
+    mockReadPackageUp.mockReturnValue({
+      packageJson: { name: 'minified-export-test' } as NormalizedPackageJson,
+      path: packageJsonPath,
+    })
+    mockGetEntryPoints.mockResolvedValue({
+      '.': [[['import'], './dist/index.js']],
+    })
+    mockModuleRequire.mockImplementation(() => ({
+      CardX: function j() {
+        return null
+      },
+    }))
+
+    const result = await createComponentLoader(join(packageDir, 'src/CardX.tsx'))
+
+    expect(result.isOk()).toBe(true)
+    if (result.isOk()) {
+      const component = result.value.loadComponent('CardX')
+      // TDD red phase: this currently returns null because function.name === "j".
+      expect(component).not.toBeNull()
+    }
+  })
+
+  it('rejects direct function exports with non-PascalCase export keys', async () => {
+    const packageDir = '/fake/lowercase-export-test'
+    const packageJsonPath = join(packageDir, 'package.json')
+
+    mockReadPackageUp.mockReturnValue({
+      packageJson: { name: 'lowercase-export-test' } as NormalizedPackageJson,
+      path: packageJsonPath,
+    })
+    mockGetEntryPoints.mockResolvedValue({
+      '.': [[['import'], './dist/index.js']],
+    })
+    mockModuleRequire.mockImplementation(() => ({
+      helper: function j() {
+        return null
+      },
+    }))
+
+    const result = await createComponentLoader(join(packageDir, 'src/helper.ts'))
+
+    expect(result.isOk()).toBe(true)
+    if (result.isOk()) {
+      const component = result.value.loadComponent('helper')
+      expect(component).toBeNull()
+    }
+  })
+})