@wix/origami-transforms 0.1.13 → 0.1.15

package/dist/companionRegistrations.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Every registration in `files`, by its `companionApp.<Name>` type.
+ * @param {Iterable<readonly [string, string]>} files Each extension file's path and source.
+ * @returns {Map<string, CompanionRegistration>}
+ */
+export function readCompanionRegistrations(files: Iterable<readonly [string, string]>): Map<string, CompanionRegistration>;
+/**
+ * @typedef {object} CompanionModule
+ * @property {CompanionRegistration} registration
+ * @property {CompanionImport} import How a page imports it: a component as its entry exports it, a context provider
+ *   as the entry's default export.
+ */
+/**
+ * Every `@site/site-code/<name>` a page can import, by its `companionApp` name. A provider's hook is imported from
+ * the provider's module.
+ * @param {ReadonlyMap<string, CompanionRegistration>} registrations
+ * @returns {Map<string, CompanionModule>}
+ */
+export function companionModules(registrations: ReadonlyMap<string, CompanionRegistration>): Map<string, CompanionModule>;
+export function isExtensionFile(path: string): boolean;
+export function importTarget(from: string, specifier: string): string;
+export function entryTarget(registration: CompanionRegistration, srcDir: string): string;
+export function findFile(target: string, exists: (path: string) => boolean): string | undefined;
+export function companionExports(modules: ReadonlyMap<string, CompanionModule>, entry: (registration: CompanionRegistration) => string): Record<string, string>;
+export function readCompanionRegistrationsIn(srcDir: string): Map<string, CompanionRegistration>;
+export type CompanionModule = {
+    registration: CompanionRegistration;
+    /**
+     * How a page imports it: a component as its entry exports it, a context provider
+     * as the entry's default export.
+     */
+    import: CompanionImport;
+};
+export type CompanionImport = {
+    kind: "default";
+} | {
+    kind: "named";
+    exportName: string;
+};
+export type CompanionComponentRegistration = {
+    kind: "component";
+    /**
+     * The registration's file.
+     */
+    path: string;
+    /**
+     * The client entry's import as written (`./component.tsx?url`), relative to `path`.
+     */
+    source: string;
+    /**
+     * How the entry's component is exported.
+     */
+    componentImport: CompanionImport;
+};
+export type CompanionContextRegistration = {
+    kind: "contextProvider";
+    /**
+     * The registration's file.
+     */
+    path: string;
+    /**
+     * `resources.client.url`, relative to the companion app's `src`, as the Wix CLI reads it.
+     * The module's default export is the provider.
+     */
+    source: string;
+    /**
+     * `resources.contextSpecifier.hook`, the module's named export that reads the context.
+     */
+    hook: string;
+};
+export type CompanionRegistration = CompanionComponentRegistration | CompanionContextRegistration;

package/dist/cssPlugins/componentPosition.d.ts

@@ -0,0 +1,2 @@
+/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const componentPositionPlugin: import("../transform/types.js").CssTransformPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-transforms",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "Babel and PostCSS checks and transforms for Wix origami page files.",
   "main": "./src/index.js",
   "files": [
@@ -15,8 +15,10 @@
   },
   "dependencies": {
     "@babel/core": "^7.26.0",
+    "@babel/parser": "^7.25.0",
+    "@babel/types": "^7.25.2",
     "@wix/origami-fonts": "1.0.1",
-    "@wix/origami-system-components": "1.8.0",
+    "@wix/origami-system-components": "1.9.0",
     "postcss": "^8.5.3",
     "postcss-custom-media": "^12.0.1"
   },
@@ -54,9 +56,13 @@
     "./wrapper-import": {
       "types": "./dist/wrapperImport.d.ts",
       "default": "./src/wrapperImport.js"
+    },
+    "./companion-registrations": {
+      "types": "./dist/companionRegistrations.d.ts",
+      "default": "./src/companionRegistrations.js"
     }
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "falconPackageHash": "97d30a95762f9e320a620f5de79aa530f7b592e354a3d6776219c7fa"
+  "falconPackageHash": "08fa24b6d989c88b62d43cea5a959c50ee2a2212bc6cb279ecf53dc1"
 }

package/src/companionRegistrations.js

@@ -0,0 +1,200 @@
+// A companion app's `editorReactComponent` and `contextProvider` registrations, read the same way by the export
+// (origami-site-generator, from the exported files) and by the site's Vite plugin (origami-site-runtime, from disk).
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { posix } from 'node:path'
+import { parse } from '@babel/parser'
+import * as t from '@babel/types'
+
+/** @typedef {{ kind: 'default' } | { kind: 'named', exportName: string }} CompanionImport */
+/**
+ * @typedef {object} CompanionComponentRegistration
+ * @property {'component'} kind
+ * @property {string} path The registration's file.
+ * @property {string} source The client entry's import as written (`./component.tsx?url`), relative to `path`.
+ * @property {CompanionImport} componentImport How the entry's component is exported.
+ */
+/**
+ * @typedef {object} CompanionContextRegistration
+ * @property {'contextProvider'} kind
+ * @property {string} path The registration's file.
+ * @property {string} source `resources.client.url`, relative to the companion app's `src`, as the Wix CLI reads it.
+ *   The module's default export is the provider.
+ * @property {string} hook `resources.contextSpecifier.hook`, the module's named export that reads the context.
+ */
+/** @typedef {CompanionComponentRegistration | CompanionContextRegistration} CompanionRegistration */
+
+/** @param {string} path */
+export const isExtensionFile = path => /\.extension\.[cm]?[jt]sx?$/.test(path)
+
+/**
+ * Every registration in `files`, by its `companionApp.<Name>` type.
+ * @param {Iterable<readonly [string, string]>} files Each extension file's path and source.
+ * @returns {Map<string, CompanionRegistration>}
+ */
+export function readCompanionRegistrations(files) {
+    /** @type {Map<string, CompanionRegistration>} */
+    const registrations = new Map()
+    for (const [path, source] of files) {
+        const ast = parse(source, { sourceType: 'module', plugins: ['jsx', 'typescript'] })
+        t.traverseFast(ast, node => {
+            if (!t.isCallExpression(node) || !t.isMemberExpression(node.callee)) return
+            const isComponent = t.isIdentifier(node.callee.property, { name: 'editorReactComponent' })
+            if (!isComponent && !t.isIdentifier(node.callee.property, { name: 'contextProvider' })) return
+            const config = node.arguments[0]
+            const type = property(config, 'type')
+            const resources = property(config, 'resources')
+            const registration = isComponent ? component(ast, path, resources) : contextProvider(path, resources)
+            if (!t.isStringLiteral(type)) throw new Error(`Unsupported component registration: ${path}`)
+            if (!/^companionApp\.[^.]+$/.test(type.value))
+                throw new Error(`Unsupported companion component namespace: ${type.value}`)
+            if (registrations.has(type.value)) throw new Error(`Duplicate user code component: ${type.value}`)
+            registrations.set(type.value, { ...registration, path })
+        })
+    }
+    return registrations
+}
+
+/**
+ * @param {t.File} ast @param {string} path @param {t.Expression | undefined} resources
+ * @returns {Omit<CompanionComponentRegistration, 'path'>}
+ */
+const component = (ast, path, resources) => {
+    const url = property(property(resources, 'client'), 'componentUrl')
+    if (!t.isIdentifier(url)) throw new Error(`Unsupported component registration: ${path}`)
+    const declaration = ast.program.body.find(
+        statement =>
+            t.isImportDeclaration(statement) && statement.specifiers.some(specifier => specifier.local.name === url.name)
+    )
+    if (!t.isImportDeclaration(declaration)) throw new Error(`Missing component entry: ${path}`)
+    const specifier = declaration.specifiers.find(specifier => specifier.local.name === url.name)
+    if (!specifier || t.isImportNamespaceSpecifier(specifier))
+        throw new Error(`Unsupported component registration: ${path}`)
+    return {
+        kind: 'component',
+        source: declaration.source.value,
+        componentImport: t.isImportDefaultSpecifier(specifier)
+            ? { kind: 'default' }
+            : {
+                  kind: 'named',
+                  exportName: t.isIdentifier(specifier.imported) ? specifier.imported.name : specifier.imported.value,
+              },
+    }
+}
+
+/**
+ * @param {string} path @param {t.Expression | undefined} resources
+ * @returns {Omit<CompanionContextRegistration, 'path'>}
+ */
+const contextProvider = (path, resources) => {
+    const url = property(property(resources, 'client'), 'url')
+    const hook = property(property(resources, 'contextSpecifier'), 'hook')
+    if (!t.isStringLiteral(url) || !t.isStringLiteral(hook) || !/^[A-Za-z_$][\w$]*$/.test(hook.value))
+        throw new Error(`Unsupported context provider registration: ${path}`)
+    return { kind: 'contextProvider', source: url.value, hook: hook.value }
+}
+
+/**
+ * The file a relative import in `from` points at, without its query, before `findFile` fills in its extension.
+ * @param {string} from @param {string} specifier
+ */
+export const importTarget = (from, specifier) =>
+    posix.normalize(posix.join(posix.dirname(from), specifier.split(/[?#]/)[0]))
+
+/**
+ * Where a registration's client entry points, before `findFile` fills in its extension.
+ * @param {CompanionRegistration} registration @param {string} srcDir The companion app's `src`, in the same form as `path`.
+ */
+export const entryTarget = (registration, srcDir) =>
+    registration.kind === 'component'
+        ? importTarget(registration.path, registration.source)
+        : importTarget(posix.join(srcDir, 'index'), registration.source)
+
+// The files an import can mean, most likely first: as written, a `.js` import of a TypeScript source, then an added
+// extension or index.
+/** @param {string} target */
+const candidates = target => [
+    target,
+    ...(/\.[cm]?js$/.test(target)
+        ? [
+              target.replace(/\.js$/, '.ts'),
+              target.replace(/\.js$/, '.tsx'),
+              target.replace(/\.mjs$/, '.mts'),
+              target.replace(/\.cjs$/, '.cts'),
+          ]
+        : []),
+    ...['.ts', '.tsx', '.js', '.jsx', '.mjs', '.json', '/index.ts', '/index.tsx', '/index.js'].map(ext => target + ext),
+]
+
+/**
+ * The file an import target (from `importTarget` or `entryTarget`) means, or undefined when none exists.
+ * @param {string} target @param {(path: string) => boolean} exists
+ */
+export const findFile = (target, exists) => candidates(target).find(exists)
+
+/**
+ * @typedef {object} CompanionModule
+ * @property {CompanionRegistration} registration
+ * @property {CompanionImport} import How a page imports it: a component as its entry exports it, a context provider
+ *   as the entry's default export.
+ */
+
+/**
+ * Every `@site/site-code/<name>` a page can import, by its `companionApp` name. A provider's hook is imported from
+ * the provider's module.
+ * @param {ReadonlyMap<string, CompanionRegistration>} registrations
+ * @returns {Map<string, CompanionModule>}
+ */
+export function companionModules(registrations) {
+    /** @type {Map<string, CompanionModule>} */
+    const modules = new Map()
+    for (const [type, registration] of registrations) {
+        const name = type.slice('companionApp.'.length)
+        if (!/^[A-Za-z_$][\w$]*$/.test(name)) throw new Error(`Unsupported extension component name: ${name}`)
+        modules.set(name, {
+            registration,
+            import: registration.kind === 'component' ? registration.componentImport : { kind: 'default' },
+        })
+    }
+    return modules
+}
+
+/**
+ * The site-code `package.json` `exports` that TypeScript resolves `@site/site-code/<name>` through, one per module.
+ * @param {ReadonlyMap<string, CompanionModule>} modules
+ * @param {(registration: CompanionRegistration) => string} entry The registration's client entry, relative to the
+ *   companion app.
+ * @returns {Record<string, string>}
+ */
+export const companionExports = (modules, entry) =>
+    Object.fromEntries([...modules].map(([name, { registration }]) => [`./${name}`, `./${entry(registration)}`]))
+
+/**
+ * Every registration under a companion app's `src` on disk, with absolute paths; none when it has no `src`.
+ * @param {string} srcDir
+ */
+export const readCompanionRegistrationsIn = srcDir =>
+    readCompanionRegistrations(
+        extensionFiles(srcDir).map(file => /** @type {const} */ ([file, readFileSync(file, 'utf8')]))
+    )
+
+/** @param {string} directory @returns {string[]} */
+const extensionFiles = directory =>
+    existsSync(directory)
+        ? readdirSync(directory, { withFileTypes: true }).flatMap(entry => {
+              const path = posix.join(directory, entry.name)
+              if (entry.isDirectory()) return entry.name === 'node_modules' ? [] : extensionFiles(path)
+              return isExtensionFile(entry.name) ? [path] : []
+          })
+        : []
+
+/** @param {unknown} node @param {string} name @returns {t.Expression | undefined} */
+const property = (node, name) => {
+    if (!node || !t.isObjectExpression(/** @type {t.Node} */ (node))) return undefined
+    const match = /** @type {t.ObjectExpression} */ (node).properties.find(
+        candidate =>
+            t.isObjectProperty(candidate) &&
+            !candidate.computed &&
+            (t.isIdentifier(candidate.key, { name }) || t.isStringLiteral(candidate.key, { value: name }))
+    )
+    return t.isObjectProperty(match) && t.isExpression(match.value) ? match.value : undefined
+}

package/src/cssPlugins/componentPosition.js

@@ -0,0 +1,26 @@
+// Gives every component the `position: relative` Thunderbolt gives it by default, so what a component positions
+// against itself (the Menu's dropdown) is placed and sized by the component. See componentPosition.md.
+
+import { isLayoutSource } from './layout/parser.js'
+
+// One class or id: DM writes `.compId`, and layout.css still accepts `#compId` (see layout/parser.js).
+const SINGLE_CLASS_OR_ID = /^[.#][\w-]+$/
+
+/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const componentPositionPlugin = {
+    name: 'component-position',
+    order: 14,
+    transform(root, context) {
+        // A component's base rules, by selector: DM may write one class in several rules.
+        /** @type {Map<string, import('postcss').Rule[]>} */
+        const baseRules = new Map()
+        for (const node of root.nodes) {
+            if (node.type !== 'rule' || !SINGLE_CLASS_OR_ID.test(node.selector) || !isLayoutSource(node, context)) continue
+            baseRules.set(node.selector, [...(baseRules.get(node.selector) ?? []), node])
+        }
+        for (const rules of baseRules.values()) {
+            if (rules.some(rule => rule.nodes.some(node => node.type === 'decl' && node.prop === 'position'))) continue
+            rules[0].prepend({ prop: 'position', value: 'relative' })
+        }
+    },
+}

package/src/cssPlugins/componentPosition.md

@@ -0,0 +1,34 @@
+# Components are `position: relative` by default
+
+Thunderbolt writes `position: relative` into each component's layout CSS when the component's layout sets no
+position, for the default breakpoint and variant only
+([responsiveLayoutCompNode.ts](https://github.com/wix-private/thunderbolt/blob/09356e43df04152b47de507f73ce2d8e2a74a97a/packages/thunderbolt-catharsis-extensions/src/features/responsiveLayout/responsiveLayoutCompNode.ts#L165-L173)).
+A component's CSS relies on it: the Menu's dropdown is `position: absolute` and as wide as the nearest positioned
+ancestor, which is the Menu only because of this default.
+
+DM's export writes a `position` only when the layout data has one, and a `position: relative` written into
+`layout.css` is imported back as data. So the default is added at build time, never in the source:
+
+```css
+/* layout.css */
+.comp-1 { width: 100%; }
+.comp-2 { position: sticky; }
+@media (max-width: 750px) { .comp-1 { width: 50%; } }
+```
+
+builds to
+
+```css
+.comp-1 { position: relative; width: 100%; }
+.comp-2 { position: sticky; }
+@media (max-width: 750px) { .comp-1 { width: 50%; } }
+```
+
+## The rules
+
+- Only a component's base rule gets it: a top-level rule in a site-owned `layout.css` whose selector is one class
+  or id (`.comp-1`, a page's `.c1dmp`, or `#comp-1`, which layout.css still accepts). That is the default breakpoint and variant; the `@media` rules inherit it.
+- A rule that sets `position` keeps its own (sticky, or the `absolute` and `fixed` DM writes for pinned and fixed
+  items).
+- The declaration goes into the authored rule, so it has the rule's specificity and wins over the component's own
+  class rules, as Thunderbolt's `#main_MF :where(.comp-1)` does.

package/src/cssPlugins/index.js

@@ -11,10 +11,12 @@
 // authored one. custom-enums runs after mixins as well, so an enum a mixin body sets is resolved, and before presets
 // and layout move declarations out of the instance's rule. fonts appends the `@font-face` rules that load the Wix fonts
 // the stylesheet names from Wix's CDN.
+// component-position runs after mixins, so a position a mixin body sets is kept, and before layout compiles the rules.
 //
 // `@layer` needs no plugin: cascade layers have been in every browser since March 2022.
 
 import { customEnumsPlugin } from './customEnums.js'
+import { componentPositionPlugin } from './componentPosition.js'
 import { customMediaPlugin } from './customMedia.js'
 import { fontsPlugin } from './fonts.js'
 import { mixinsPlugin } from './mixins.js'
@@ -31,6 +33,7 @@ export const cssPlugins = Object.freeze([
     customEnumsPlugin,
     stackChildrenPlugin,
     presetsPlugin,
+    componentPositionPlugin,
     layoutPlugin,
     spxPlugin,
 ])