@wix/origami-transforms 0.1.14 → 0.1.16

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/layout/contract.d.ts

@@ -1,5 +1,6 @@
 export const CONTENT: "internal-container-content-wrapper";
 export const OVERFLOW: "internal-container-overflow-wrapper";
+export const DEFAULTS_LAYER: "origami-container-defaults";
 export const targets: Readonly<{
     "internal-container-content-wrapper": Set<string>;
     "internal-container-overflow-wrapper": Set<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-transforms",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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.9.0",
+    "@wix/origami-system-components": "1.10.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": "dcaeecf42c720e3e9a25f95eadad7516666d783eef907ba5f39467f1"
+  "falconPackageHash": "74a88e698f17027ba6854f8a4cdcd82fb6e31bdaec6caea30a13b8ac"
 }

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/layout/README.md

@@ -32,15 +32,21 @@ the outer element.
 ## What the plugin adds
 
 The outer element and overflow wrapper get a one-cell grid so the wrappers fill
-the container. The content wrapper gets sizing and positioning styles, including
-a maximum width and left, center or right alignment. It lets pointer events pass
-through empty space while its children remain clickable.
-
-Each container starts with no content width limit and centered alignment. These
-defaults live in a separate CSS layer so authored settings can override them.
-Media queries, scopes and other surrounding conditions still apply to generated
-rules. Vertical overflow also sets `--sticky-offset` to `0px` for `scroll` and
-resets it for other values.
+the container. The content wrapper lets pointer events pass through empty space
+while its children stay clickable. Vertical overflow also sets `--sticky-offset`
+to `0px` for `scroll` and resets it for other values.
+
+Each container's alignment defaults to center in a separate first CSS layer, so
+authored values always win. Media queries and scopes around a rule still apply.
+
+### Content max width
+
+Where DM writes `--content-max-width` (usually a section's content wrapper), the
+plugin adds `max-width` and an alignment `margin-left` next to it, and nowhere else.
+
+- Those two properties do not inherit, so nested containers are not boxed in.
+- `--content-max-width` does inherit, so nested containers use it as their SPX cap
+  (see the SPX plugin README). With none above, SPX is uncapped.
 
 ## Why validation runs before transformations
 

package/src/cssPlugins/layout/compiler.js

@@ -1,9 +1,11 @@
 import postcss from 'postcss'
 import { buildContainerClasses } from '@wix/origami-system-components/layout-contract'
-import { CONTENT } from './contract.js'
+import { CONTENT, DEFAULTS_LAYER } from './contract.js'
 import { isLayoutSource, parseTargets } from './parser.js'
 
 const grid = { display: 'grid', 'grid-template-rows': '1fr', 'grid-template-columns': 'minmax(0, 1fr)' }
+const contentMargin =
+    'clamp(0px, (100% - var(--content-max-width)) * var(--origami-content-align), 100 * var(--one-unit, 1%))'
 
 /** Preserve source locations on every emitted declaration and selector. */
 const ruleFor = (owner, selector, declarations) => {
@@ -21,12 +23,12 @@ const ruleFor = (owner, selector, declarations) => {
 export const compileContainers = (root, context) => {
     const owners = parseTargets(root, context)
     if (!owners.size) return
-    // Thunderbolt writes max-width and margin-left directly; neither property inherits.
-    // We use custom properties so width and alignment can change independently at breakpoints.
-    // Those do inherit, so each container needs defaults to avoid taking its parent's settings.
+    // max-width and margin-left are written only where a content max width is set.
+    // Alignment is a custom property so it can change independently at breakpoints.
+    // That inherits, so each container needs a default to avoid taking its parent's alignment.
     // This first layer keeps defaults weaker than authored rules, including rules in later layers.
     // Clone only conditional/scope envelopes into it so the defaults apply under the same conditions.
-    const defaultsLayer = postcss.atRule({ name: 'layer', params: 'origami-container-defaults' })
+    const defaultsLayer = postcss.atRule({ name: 'layer', params: DEFAULTS_LAYER })
     if (root.source) defaultsLayer.source = root.source
     root.prepend(defaultsLayer)
     // Source identity prevents a matching selector in another carrier from becoming an owner.
@@ -64,10 +66,7 @@ export const compileContainers = (root, context) => {
                 defaultsParent = clone
             }
             defaultsParent.append(
-                ruleFor(owner, `:where(${content})`, {
-                    '--content-max-width': 'none',
-                    '--origami-content-align': '0.5',
-                })
+                ruleFor(owner, `:where(${content})`, { '--origami-content-align': '0.5' })
             )
             owner.before(ruleFor(owner, selector, grid))
             owner.before(ruleFor(owner, overflow, { ...grid, position: 'relative', 'align-self': 'stretch' }))
@@ -76,10 +75,6 @@ export const compileContainers = (root, context) => {
                     'box-sizing': 'border-box',
                     position: 'relative',
                     'pointer-events': 'none',
-                    'max-width': 'var(--content-max-width)',
-                    '--section-max-width': 'var(--content-max-width)',
-                    'margin-left':
-                        'clamp(0px, (100% - var(--content-max-width, 100%)) * var(--origami-content-align), 100 * var(--one-unit, 1%))',
                 })
             )
             owner.before(ruleFor(owner, `${content} > *`, { 'pointer-events': 'auto' }))
@@ -98,6 +93,11 @@ export const compileContainers = (root, context) => {
                         // Left margin uses none, half or all of the extra space to align the content.
                         clone.value = { left: '0', center: '0.5', right: '1' }[clone.value]
                     }
+                    if (clone.prop === '--content-max-width')
+                        generated.append(
+                            clone.clone({ prop: 'max-width', value: 'var(--content-max-width)' }),
+                            clone.clone({ prop: 'margin-left', value: contentMargin })
+                        )
                     if (clone.prop === 'overflow-y')
                         generated.append(
                             clone.clone({

package/src/cssPlugins/layout/contract.js

@@ -2,6 +2,7 @@
 // Consumer routing only: component eligibility is validated by DM against JSX.
 export const CONTENT = 'internal-container-content-wrapper'
 export const OVERFLOW = 'internal-container-overflow-wrapper'
+export const DEFAULTS_LAYER = 'origami-container-defaults'
 export const targets = Object.freeze({
     [CONTENT]: new Set([
         'position',

package/src/cssPlugins/spx/README.md

@@ -29,13 +29,21 @@ styles onto their runtime wrappers; this plugin then converts every `--spx(numbe
 In scale mode, the size is approximately:
 
 ```text
-number × (scaling-factor − scrollbar-width) / spx-ref-width
+number × (clamp(spx-stopper-min, scaling-factor, min(spx-stopper-max, content-max-width)) − scrollbar-width) / spx-ref-width
 ```
 
+This matches DM's `--spx()` in the `theme.css` preamble.
+
+- **Stoppers:** DM writes them inside `@layer spx-preamble`, so the viewer's unlayered global CSS
+  values (`0px` / `9999px`) win.
+- **Cap:** `--content-max-width`, set by DM on each section's content wrapper and inherited by its
+  descendants. With none above, the cap is 99999px. A `--content-max-width` that uses `--spx()` is
+  compiled without the cap, since a custom property can't read itself.
+
 Nonzero scaled values have a minimum magnitude of 0.5px, preserving their sign.
 In fixed mode, the number is a pixel value, including fractional pixels. Zero stays zero.
 
-The plugin keeps reference width, scaling factor and scrollbar width as `var()` reads
+The plugin keeps reference width, scaling factor, scrollbar width and stoppers as `var()` reads
 inside each expression. It translates `--spx-resolver-type: scale` to a private numeric
 switch of 1, and `fixed` to 0. That switch selects scaled lengths or fixed pixels using
 ordinary CSS arithmetic, without requiring CSS custom functions or style queries.
@@ -53,9 +61,9 @@ own effective settings. No per-container SPX reset is needed.
 
 Existing preamble declarations remain in CSS and participate in the normal cascade.
 When settings are absent, expressions fall back to reference width 1280, scale mode,
-viewport width 100vw and scrollbar width 0px. Nested components inherit settings unless
-they override them. As with any CSS custom property, an authored token containing an
-SPX expression resolves where the token is declared; inheriting the token does not
+viewport width 100vw, scrollbar width 0px, stoppers 0px / 99999px and no cap. Nested components inherit settings unless
+they override them. As with any CSS custom property, an authored variable containing an
+SPX expression resolves where the variable is declared; inheriting the variable does not
 re-evaluate it using a child's settings.
 
 ## Files and boundaries
@@ -65,9 +73,8 @@ re-evaluate it using a child's settings.
 - `calls.js` parses literal numeric SPX calls and rejects unsupported arguments.
 
 Reference widths must be positive numbers and resolver modes must be `scale` or `fixed`.
-SPX stopper clamping is still outside this plugin: it uses the effective
-`--scaling-factor` supplied by CSS and does not generate Thunderbolt's clamp formula.
+Stoppers and `--content-max-width` are not validated.
 
 `test/spx.browser.mjs` checks computed styles for the button example, nested overrides,
-settings in separate stylesheets, cascade priority, fixed fractions, signs and zero.
+settings in separate stylesheets, cascade priority, fixed fractions, signs, zero, stoppers and cap.
 Run it together with the container browser checks using the package's `test:browser` script.

package/src/cssPlugins/spx/cascade.js

@@ -3,8 +3,12 @@ import { lowerCalls } from './calls.js'
 // Keep arithmetic at the call site: an inherited derived custom property would already
 // be computed against its parent's settings. Only the numeric resolver switch inherits.
 const SCALE = 'var(--origami-spx-scale, 1)'
-const UNIT = `(${SCALE} * (var(--scaling-factor, 100vw) - var(--scrollbar-width, 0px)) / var(--spx-ref-width, 1280) + (1 - ${SCALE}) * 1px)`
 const FLOOR = `calc(0.5px * ${SCALE})`
+/** @param {string} cap */
+const unitCappedAt = cap =>
+    `(${SCALE} * (clamp(var(--spx-stopper-min, 0px), var(--scaling-factor, 100vw), min(var(--spx-stopper-max, 99999px), ${cap})) - var(--scrollbar-width, 0px)) / var(--spx-ref-width, 1280) + (1 - ${SCALE}) * 1px)`
+const UNIT = unitCappedAt('var(--content-max-width, 99999px)')
+const UNCAPPED_UNIT = unitCappedAt('99999px')
 
 /** Compile settings and calls in place, retaining their cascade and source locations.
  * @param {import('postcss').Declaration} declaration
@@ -30,11 +34,12 @@ export const compileCascadeDeclaration = declaration => {
     ) {
         throw declaration.error('SPX reference width must be positive')
     }
+    const unit = declaration.prop === '--content-max-width' ? UNCAPPED_UNIT : UNIT
     lowerCalls(
         declaration,
         number => {
             if (number === 0) return '0px'
-            return number < 0 ? `min(calc(-1 * ${FLOOR}), ${number} * ${UNIT})` : `max(${FLOOR}, ${number} * ${UNIT})`
+            return number < 0 ? `min(calc(-1 * ${FLOOR}), ${number} * ${unit})` : `max(${FLOOR}, ${number} * ${unit})`
         },
         () => declaration.error('SPX calls --spx() with a non-literal argument')
     )