@wix/origami-transforms 0.1.11 → 0.1.13

package/dist/cssPlugins/customEnums.d.ts

@@ -1,3 +1,3 @@
-export function removeCustomEnums(root: any): any;
+export function removeCustomEnums(root: any): void;
 /** @type {import('../transform/types.js').CssTransformPlugin} */
 export const customEnumsPlugin: import("../transform/types.js").CssTransformPlugin;

package/dist/wrapperImport.d.ts

@@ -0,0 +1,7 @@
+/** component-wrapper-server's `PACKAGE_SCOPE` (`src/wrapper/packageTarball.ts`). */
+export const WRAPPERS_SCOPE: "@origami-wrappers";
+export function wrapperPackageName(module: string): string;
+export function wrapperImport({ module, symbol }: {
+    readonly module: string;
+    readonly symbol: string;
+}): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-transforms",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Babel and PostCSS checks and transforms for Wix origami page files.",
   "main": "./src/index.js",
   "files": [
@@ -16,7 +16,7 @@
   "dependencies": {
     "@babel/core": "^7.26.0",
     "@wix/origami-fonts": "1.0.1",
-    "@wix/origami-system-components": "1.7.0",
+    "@wix/origami-system-components": "1.8.0",
     "postcss": "^8.5.3",
     "postcss-custom-media": "^12.0.1"
   },
@@ -50,9 +50,13 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./src/index.js"
+    },
+    "./wrapper-import": {
+      "types": "./dist/wrapperImport.d.ts",
+      "default": "./src/wrapperImport.js"
     }
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "falconPackageHash": "b2340e8ef9e2e52ae323397986026dcf38f3cd9a3a69fdc64a1e6736"
+  "falconPackageHash": "97d30a95762f9e320a620f5de79aa530f7b592e354a3d6776219c7fa"
 }

package/src/cssPlugins/customEnums.js

@@ -2,7 +2,9 @@
 // `#comp-1 { --labelAlign: center }`, and this writes the vars that option applies in its place, from the
 // `@custom-enum` blocks in the component wrapper's `custom-enums.css` (see component-wrapper-server's
 // `customEnums.ts`), read from the wrapper's folder: the item's JSX imports the wrapper's CSS, so the blocks aren't in
-// the stylesheet. A stylesheet that `@import`s the wrapper's CSS has them inlined; those are used and removed.
+// the stylesheet. A stylesheet that `@import`s the wrapper's CSS has them inlined; those are used and removed. A ref
+// element's enums are its type's: the wrapper names the type with `@custom-enum-ref`, and they come from that type's
+// wrapper.
 // Native `if()` can't do it: Firefox doesn't have it, and a var named like its key refers to itself.
 //
 // The instance's component comes from the item's structure file (structureFile.js): the element with
@@ -13,15 +15,49 @@ import { createRequire } from 'node:module'
 import { basename, dirname, join } from 'node:path'
 import postcss from 'postcss'
 import { LayoutError } from '../transform/layoutError.js'
+import { WRAPPERS_SCOPE, wrapperImport } from '../wrapperImport.js'
 import { literalIdOf, parseStructure, structureFileOf, walk } from './structureFile.js'
 
 const CUSTOM_ENUMS_CSS = 'custom-enums.css'
 // `@origami-wrappers/<module>/<symbol>`, and nothing that could resolve outside its package.
-const WRAPPER_IMPORT = /^@origami-wrappers\/[\w-]+\/[\w-]+$/
-// `#id` or `.id` (exports give an instance both), then only what narrows that same element: classes,
-// pseudo-classes, attributes. Then any descendants, such as an inline element's own selector. No other combinators,
-// and no pseudo-elements, which the component doesn't read vars from.
-const INSTANCE = /^[#.]([\w-]+)(?!.*::)(?:[.:[][^\s>+~]*)?((?:\s+[^\s>+~]+)*)$/
+const WRAPPER_IMPORT = new RegExp(`^${WRAPPERS_SCOPE}/[\\w-]+/[\\w-]+$`)
+// A component type, `wixEditorElements.Button`: its module and symbol.
+const COMPONENT_TYPE = /^([\w-]+)\.([\w-]+)$/
+/** The selector's compounds, split at its combinators, outside parentheses and brackets. */
+const compoundsOf = selector => {
+    const compounds = ['']
+    let depth = 0
+    for (const char of selector.trim()) {
+        if (char === '(' || char === '[') depth++
+        if (char === ')' || char === ']') depth--
+        if (depth === 0 && /[\s>+~]/.test(char)) {
+            if (compounds.at(-1) !== '') compounds.push('')
+        } else compounds[compounds.length - 1] += char
+    }
+    return compounds.filter(Boolean)
+}
+
+/** A compound's own ids and classes, `#comp-1` and `.button`, not those in its `:not(…)` or attributes. */
+const namesOf = compound => {
+    let own = compound.replace(/\[[^\]]*\]/g, '')
+    while (/\([^()]*\)/.test(own)) own = own.replace(/\([^()]*\)/g, '')
+    return own.match(/[.#][\w-]+/g) ?? []
+}
+
+/**
+ * The last of `compounds` that `element`'s compounds match, each a descendant of the one before, or -1: an element
+ * matches a compound that has all its names, `.button.hamburger-open-button` matching `.button.hamburger-open-button.x`.
+ */
+const lastMatch = (element, compounds) => {
+    const covers = (names, wanted) => wanted.every(name => names.includes(name))
+    for (let end = compounds.length - 1; end >= 0; end--) {
+        if (!covers(compounds[end], element.at(-1))) continue
+        let matched = 0
+        for (let at = 0; at < end && matched < element.length - 1; at++) if (covers(compounds[at], element[matched])) matched++
+        if (matched === element.length - 1) return end
+    }
+    return -1
+}
 
 /** Id → the wrapper import it is rendered from, for elements with a literal `id` and an imported wrapper tag. */
 const importsById = structurePath => {
@@ -50,20 +86,26 @@ const real = path => {
     }
 }
 
-/**
- * Id → the enums of every wrapper instance; none for one whose component has no custom enums. `enumsOf` gives a
- * wrapper folder's enums.
- */
-const enumsById = (structurePath, enumsOf) => {
+/** The folder an `@origami-wrappers/…` import resolves to from the structure file, or undefined when it doesn't. */
+const wrapperFolders = structurePath => {
     const require = createRequire(structurePath)
-    const byId = new Map()
-    for (const [id, source] of importsById(structurePath)) {
-        let folder
+    return source => {
         try {
-            folder = real(dirname(require.resolve(source)))
+            return real(dirname(require.resolve(source)))
         } catch {
-            folder = undefined
+            return undefined
         }
+    }
+}
+
+/**
+ * Id → the enums of every wrapper instance; none for one whose component has no custom enums. `folderOf` gives an
+ * import's wrapper folder, and `enumsOf` a wrapper folder's enums.
+ */
+const enumsById = (structurePath, folderOf, enumsOf) => {
+    const byId = new Map()
+    for (const [id, source] of importsById(structurePath)) {
+        const folder = folderOf(source)
         byId.set(id, folder === undefined ? [] : enumsOf(folder))
     }
     return byId
@@ -90,17 +132,39 @@ const resolve = (rule, selector) => {
 const fromDependency = declaration => declaration.source?.input.file?.split(/[\\/]/).includes('node_modules') ?? false
 
 /**
- * The `@custom-enum` blocks in the stylesheet: wrapper folder → its enums, with each option as the enum's full var
- * set; the blocks themselves; and the ones that can't be read.
+ * The `@custom-enum` blocks and `@custom-enum-ref` declarations in the stylesheet: wrapper folder → its enums, with
+ * each option as the enum's full var set, and its ref elements; the at-rules themselves; and the ones that can't be
+ * read.
  *
- * A block sits in its element's rule, `.menu`, or `.menu .menu-input` for an inline element. A var an option doesn't
- * set has the default option's value, or `inherit` when the default doesn't set it either, which is what an instance
- * that picks no option gets. An option that doesn't set its own key still says which option it is.
+ * A block sits in its element's rule, `.menu`, or `.menu .dropdown` for an inline element at any depth. A var an
+ * option doesn't set has the default option's value, or `inherit` when the default doesn't set it either, which is
+ * what an instance that picks no option gets. An option that doesn't set its own key still says which option it is.
+ * A ref declaration sits in its element's rule, `.menu .button.hamburger-open-button`, and names the element's type.
  */
 const definitionsIn = root => {
     const byFolder = new Map()
     const blocks = []
     const malformed = []
+    const definitionOf = file => {
+        const folder = real(dirname(file))
+        if (!byFolder.has(folder)) byFolder.set(folder, { enums: [], refs: [] })
+        return byFolder.get(folder)
+    }
+    root.walkAtRules('custom-enum-ref', declaration => {
+        blocks.push(declaration)
+        const type = COMPONENT_TYPE.exec(declaration.params.trim())
+        const file = declaration.source?.input.file
+        const rule = declaration.parent?.type === 'rule' ? /** @type {import('postcss').Rule} */ (declaration.parent) : undefined
+        const [, ...element] = rule ? resolve(rule, rule.selector)[0].split(/\s+/) : []
+        if (type === null || file === undefined || element.length === 0) {
+            malformed.push(declaration)
+            return
+        }
+        definitionOf(file).refs.push({
+            selector: element.join(' '),
+            source: wrapperImport({ module: type[1], symbol: type[2] }),
+        })
+    })
     root.walkAtRules('custom-enum', block => {
         blocks.push(block)
         const keyVar = block.params.trim()
@@ -125,7 +189,7 @@ const definitionsIn = root => {
         }
 
         const [selector] = resolve(rule, rule.selector)
-        const [editorSelector, ...inline] = selector.split(/\s+/)
+        const [, ...inline] = selector.split(/\s+/)
         const defaults = applied.get(defaultValue)
         const vars = [...new Set([...applied.values()].flatMap(values => Object.keys(values)))]
         const options = Object.fromEntries(
@@ -134,13 +198,9 @@ const definitionsIn = root => {
                 Object.fromEntries(vars.map(name => [name, values[name] ?? defaults[name] ?? 'inherit'])),
             ])
         )
-        const folder = real(dirname(file))
-        const enums = byFolder.get(folder) ?? []
-        byFolder.set(folder, enums)
-        enums.push({
+        definitionOf(file).enums.push({
             key: keyVar,
             options,
-            editorSelector,
             // An inline element's selector inside the editor element's, undefined for the editor element itself.
             inline: inline.length ? inline.join(' ') : undefined,
         })
@@ -169,33 +229,18 @@ const expansion = (declaration, values) =>
     )
 
 /**
- * An inline element's vars, as a rule of their own after the outermost node, under the same at-rules.
- * `:not()` keeps them off the same inline element of an instance nested inside this one. `inserted` maps each
- * outermost node to the last rule put after it, so the rules keep their declarations' source order.
+ * Removes the stylesheet's `@custom-enum` blocks and `@custom-enum-ref` declarations, which only this plugin reads,
+ * and a rule that held nothing else.
  */
-const inlineRule = (declaration, instance, { inline, editorSelector }, options, inserted) => {
-    let node = postcss
-        .rule({
-            selector: `${instance} ${inline}:not(${instance} ${editorSelector} ${inline})`,
-            source: declaration.source,
-            raws: { semicolon: true },
-        })
-        .append(expansion(declaration, options))
-    let outer = declaration.parent
-    for (let parent = declaration.parent; parent && parent.type !== 'root'; parent = parent.parent) {
-        if (parent.type === 'atrule') node = parent.clone({ nodes: [] }).append(node)
-        outer = parent
-    }
-    ;(inserted.get(outer) ?? outer).after(node)
-    inserted.set(outer, node)
-}
-
-/** Removes the stylesheet's `@custom-enum` blocks, which only this plugin reads. */
-export const removeCustomEnums = root =>
-    root.walkAtRules('custom-enum', block => {
-        if (block.parent) block.parent.raws.semicolon = true
-        block.remove()
+export const removeCustomEnums = root => {
+    const emptied = new Set()
+    root.walkAtRules(/^custom-enum(?:-ref)?$/, node => {
+        if (node.parent) node.parent.raws.semicolon = true
+        emptied.add(node.parent)
+        node.remove()
     })
+    for (const rule of emptied) if (rule?.type === 'rule' && rule.nodes.length === 0) rule.remove()
+}
 
 /** @type {import('../transform/types.js').CssTransformPlugin} */
 export const customEnumsPlugin = {
@@ -208,24 +253,42 @@ export const customEnumsPlugin = {
         if (structurePath === undefined && inlined.blocks.length === 0) return
         if (structurePath !== undefined) context.addDependency?.(structurePath)
         const malformed = [...inlined.malformed]
-        // A wrapper's enums are the blocks inlined from its folder, or else those in the folder's custom-enums.css.
+        // A wrapper's definitions are the ones inlined from its folder, or else those in the folder's custom-enums.css.
         const readFolders = new Map()
-        const enumsOf = folder => {
+        const definitionOf = folder => {
             if (inlined.byFolder.has(folder)) return inlined.byFolder.get(folder)
             if (!readFolders.has(folder)) {
                 const file = join(folder, CUSTOM_ENUMS_CSS)
-                let enums = []
+                let definition = { enums: [], refs: [] }
                 if (existsSync(file)) {
                     context.addDependency?.(file)
                     const definitions = definitionsIn(postcss.parse(readFileSync(file, 'utf8'), { from: file }))
                     malformed.push(...definitions.malformed)
-                    enums = definitions.byFolder.get(folder) ?? []
+                    definition = definitions.byFolder.get(folder) ?? definition
                 }
-                readFolders.set(folder, enums)
+                readFolders.set(folder, definition)
             }
             return readFolders.get(folder)
         }
-        const instances = structurePath === undefined ? new Map() : enumsById(structurePath, enumsOf)
+        const folderOf = structurePath === undefined ? () => undefined : wrapperFolders(structurePath)
+        // A wrapper's enums, and those of each ref element's type as if the ref were their inline element:
+        // `.button.hamburger-open-button` gets the Button's `.button` enums, and `.button.hamburger-open-button .label`
+        // its `.button .label` ones. `seen` stops a type that refers back to itself.
+        const enumsOf = (folder, seen = new Set()) => {
+            if (seen.has(folder)) return []
+            const { enums, refs } = definitionOf(folder)
+            const refEnums = refs.flatMap(({ selector, source }) => {
+                const refFolder = folderOf(source)
+                return refFolder === undefined
+                    ? []
+                    : enumsOf(refFolder, new Set([...seen, folder])).map(item => ({
+                          ...item,
+                          inline: item.inline === undefined ? selector : `${selector} ${item.inline}`,
+                      }))
+            })
+            return [...enums, ...refEnums]
+        }
+        const instances = structurePath === undefined ? new Map() : enumsById(structurePath, folderOf, enumsOf)
         const keys = new Set([...instances.values()].flatMap(enums => enums.map(({ key }) => key)))
 
         /** @type {import('postcss').Declaration[]} */
@@ -237,39 +300,45 @@ export const customEnumsPlugin = {
         collect()
 
         /**
-         * What `declaration` resolves to on the instance or inline element `selector` is, the reason it can't, or null
-         * when that element has no such enum, so the var is an ordinary one. `onElement` says the selector is the
-         * element the enum is on, so its vars go in place.
+         * The vars `declaration` resolves to on the element `selector` is nearest to, the reason it can't, or null when
+         * that element has no such enum, or `selector` is in no instance, so the var is an ordinary one.
          */
         const lookup = (declaration, selector) => {
-            const match = INSTANCE.exec(selector)
-            const enums = match ? instances.get(match[1]) : undefined
-            if (match === null || enums === undefined) {
-                return (
-                    `"${selector}" is not a component instance. Set a custom enum on the instance's own #id or .id (with ` +
-                    `a literal id="…" in the structure file), or on its inline element (#id .menu-input), with ` +
-                    `nothing after either but classes or pseudo-classes.`
-                )
+            const compounds = compoundsOf(selector).map(namesOf)
+            const isInstance = name => instances.has(name.slice(1))
+            // The last instance in the selector, `#comp-1` or `.comp-1`; what's before it, such as a variant's class,
+            // doesn't matter.
+            let at = compounds.length - 1
+            while (at >= 0 && !compounds[at].some(isInstance)) at--
+            if (at === -1) return null
+            const enums = instances.get(compounds[at].filter(isInstance).at(-1).slice(1))
+            const after = compounds.slice(at + 1)
+            // The element nearest the selector's end: the inline or ref element matched last, its longer selector on a
+            // tie, or the editor element when none is. Its enums alone resolve, so a key on a variant of the element
+            // (`#comp-1 .dropdown .variant-1`) resolves by it, and two elements can share a key.
+            let nearest
+            let end = -1
+            let length = 0
+            for (const inline of new Set(enums.flatMap(({ inline }) => (inline === undefined ? [] : [inline])))) {
+                const element = compoundsOf(inline).map(namesOf)
+                const found = lastMatch(element, after)
+                if (found > end || (found !== -1 && found === end && element.length > length)) {
+                    nearest = inline
+                    end = found
+                    length = element.length
+                }
             }
-            // An inline element's selector, then only what narrows it, as on the instance.
-            const descendants = match[2].trim()
-            const onInline = ({ inline }) =>
-                inline !== undefined &&
-                descendants.startsWith(inline) &&
-                /^(?:$|[.:[])/.test(descendants.slice(inline.length))
-            const matching = enums.filter(
-                item => item.key === declaration.prop && (descendants === '' || onInline(item))
-            )
+            const matching = enums.filter(item => item.key === declaration.prop && item.inline === nearest)
             if (matching.length === 0) return null
             const key = declaration.prop.slice(2)
-            if (matching.length > 1) return `two of the component's elements have a custom enum ${key}, so it can't say which.`
+            if (matching.length > 1) return `the element has custom enum ${key} more than once, so it can't say which.`
             const [found] = matching
             const value = declaration.value.trim()
             const allowed = Object.keys(found.options).join(', ')
             if (/\bvar\(/.test(value)) return `a custom enum's value must be literal, one of ${allowed}.`
             const options = found.options[value]
             if (options === undefined) return `"${value}" is not an option of ${key}; use one of ${allowed}.`
-            return { found, options, onElement: descendants !== '' || found.inline === undefined }
+            return options
         }
 
         // A block comes from the wrapper package, which the site can't fix: its enum is skipped, so an instance that
@@ -277,8 +346,12 @@ export const customEnumsPlugin = {
         for (const block of malformed) {
             context.warn?.(
                 block,
-                `custom-enums: @custom-enum ${block.params}${where(block)}: can't be read; it needs a --key, a ` +
-                    `default: that is one of its @option blocks, and an element rule around it. Its key is left as authored.`
+                block.name === 'custom-enum-ref'
+                    ? `custom-enums: @custom-enum-ref ${block.params}${where(block)}: can't be read; it needs a component ` +
+                          `type, such as wixEditorElements.Button, in an element rule under the editor element's. That ` +
+                          `element's enums are left as authored.`
+                    : `custom-enums: @custom-enum ${block.params}${where(block)}: can't be read; it needs a --key, a ` +
+                          `default: that is one of its @option blocks, and an element rule around it. Its key is left as authored.`
             )
         }
 
@@ -286,16 +359,18 @@ export const customEnumsPlugin = {
         const violations = new Set()
         /** @type {any} The first violation's source, whose position the bundler prints. */
         let first
+        // The rules with an enum that resolves, the only ones a selector list is split in.
+        const resolving = new Set()
         for (const declaration of declarations) {
             const rule = ruleOf(declaration)
-            const problems = rule
-                ? rule.selectors.flatMap(own => {
-                      const resolved = resolve(rule, own)
-                      if (resolved.length !== 1) return ['set a custom enum on one instance rule, not under a parent selector list.']
-                      const result = lookup(declaration, resolved[0])
-                      return typeof result === 'string' ? [result] : []
-                  })
-                : ['set a custom enum on one instance rule, not outside a rule.']
+            const problems = (rule?.selectors ?? []).flatMap(own => {
+                const results = resolve(rule, own).map(selector => lookup(declaration, selector))
+                if (results.some(result => result !== null)) resolving.add(rule)
+                if (results.length > 1 && results.some(result => result !== null)) {
+                    return ['set a custom enum on one instance rule, not under a parent selector list.']
+                }
+                return results.filter(result => typeof result === 'string')
+            })
             for (const problem of problems) {
                 first ??= declaration.source
                 violations.add(`custom-enums: ${declaration.prop}: ${declaration.value}${where(declaration)}: ${problem}`)
@@ -312,39 +387,20 @@ export const customEnumsPlugin = {
         removeCustomEnums(root)
 
         // A rule with a selector list is split, one rule per selector, so each instance gets its own option.
-        for (const rule of new Set(declarations.map(ruleOf))) {
-            if (rule === undefined || rule.selectors.length < 2) continue
+        for (const rule of resolving) {
+            if (rule.selectors.length < 2) continue
             for (const selector of [...rule.selectors].reverse()) rule.after(rule.clone({ selector }))
             rule.remove()
         }
         declarations.length = 0
         collect()
 
-        const emptied = new Set()
-        const inserted = new Map()
         for (const declaration of declarations) {
-            const rule = /** @type {import('postcss').Rule} */ (ruleOf(declaration))
+            const rule = ruleOf(declaration)
+            if (rule === undefined) continue
             const [selector] = resolve(rule, rule.selector)
-            const result = /** @type {Exclude<ReturnType<typeof lookup>, string>} */ (lookup(declaration, selector))
-            if (result === null) continue
-            const { found, options, onElement } = result
-            if (onElement) {
-                declaration.replaceWith(expansion(declaration, options))
-            } else {
-                emptied.add(declaration.parent)
-                inlineRule(declaration, selector, found, options, inserted)
-                declaration.remove()
-            }
-        }
-
-        // Drop the rules and at-rules the inline moves left empty, up to the outermost.
-        for (let nodes = [...emptied]; nodes.length; ) {
-            nodes = nodes.flatMap(node => {
-                if (node.nodes.length || node.type === 'root') return []
-                const parent = node.parent
-                node.remove()
-                return parent ? [parent] : []
-            })
+            const options = /** @type {Exclude<ReturnType<typeof lookup>, string>} */ (lookup(declaration, selector))
+            if (options !== null) declaration.replaceWith(expansion(declaration, options))
         }
     },
 }

package/src/cssPlugins/customEnums.md

@@ -59,10 +59,34 @@ the defaults:
 
 The item's JSX imports each used wrapper's `defaults.css`, which imports this file, so the browser loads
 it ahead of the site's stylesheets, and the blocks are not in the document the plugin gets. The plugin reads
-them from the wrapper's folder instead. The CSS stage removes them from the wrapper's own CSS, which runs no
+them from the wrapper's folder instead. The CSS stage removes them, and the ref declarations, from the wrapper's own CSS, which runs no
 other plugin; browsers would ignore the unknown at-rule anyway, and the defaults still apply. A stylesheet
 that `@import`s `defaults.css` has the blocks inlined: the plugin reads those and removes them from the output.
-An inline element's block sits in `{editor selector} {inline selector}` (`.menu .menu-input`).
+An inline element's block sits in `{editor selector} {inline selector}` (`.menu .menu-input`), flat at any depth: the
+Menu's dropdown, which sits in its navbar, is `.menu .dropdown`, as exports address it (`.comp-1 .dropdown`).
+
+## Ref elements
+
+A ref element is another component inside this one, such as the Menu's hamburger buttons, which are Buttons. Its
+enums are its type's, so the wrapper doesn't copy them; it names the type in the ref's rule:
+
+```css
+.menu .button.hamburger-open-button {
+    @custom-enum-ref wixEditorElements.Button;
+}
+```
+
+The plugin resolves the type's wrapper from the structure file, through `wrapperImport` (`src/wrapperImport.js`), the
+same name origami-site-generator imports wrappers by (`@origami-wrappers/wixEditorElements/button`), and reads that wrapper's `custom-enums.css`. The type's own enums
+(`.button`) apply on the ref's selector, and its inline elements' (`.button .label`) on the ref's selector followed by
+theirs:
+
+```css
+.comp-1 .button.hamburger-open-button { --icon-position: row-reverse; }
+.comp-1 .button.hamburger-open-button .label { --label-wrap: nowrap; }
+```
+
+A ref inside the type's wrapper is followed the same way. A type with no wrapper in the site gives the ref no enums.
 
 The item's structure file (next to the stylesheet, or one folder up for `_generated/`) says which
 component each `id` is: the element `<Menu id="comp-1" />` and its `@origami-wrappers/…` import. The
@@ -75,26 +99,31 @@ option replaces all of a desktop option's vars, not just the ones it names.
 
 ## The rules
 
-- Set the enum on the instance's own `#id` or `.id`, or on its inline element's selector under it
-  (`#comp-1 .menu-input`), which is how exports write it. Classes and pseudo-classes after either are kept
-  (`#comp-1:hover`); a combinator other than a space (`#comp-1 > .menu-input`) or a pseudo-element
-  (`#comp-1::before`) is an error. A selector list is split into one rule per instance.
-- On an inline element, the key is that element's enum, so two elements can share a key. A key on a descendant
-  with no such enum, such as an element nested in an inline element (`#comp-1 .navbar .dropdown`), is an
-  ordinary var, left as authored.
+- A key resolves by the component element nearest the selector's end, inside the selector's last instance
+  (`#comp-1` or `.comp-1`): the inline or ref element matched last, or the editor element when none is. What isn't
+  an element, such as a variant's class, a state or a combinator, doesn't change which element that is:
+
+  | selector | resolves by |
+  |---|---|
+  | `#comp-1`, `#comp-1:hover`, `#comp-1 .variant-1`, `.variant-1 #comp-1` | the Menu |
+  | `#comp-1 .dropdown`, `#comp-1 .navbar .dropdown .variant-1` | the dropdown |
+  | `#comp-1 .button.hamburger-open-button .variant-1` | the Button's enums |
+  | `.button.hamburger-open-button .variant-1`, `.card` | nothing: no instance |
+
+  Only that element's enums resolve, so two elements can share a key (the navbar's and the dropdown's
+  `items-width`). A key that element has no enum of, such as the dropdown's on the instance (`.comp-1 {
+  --items-width: fillMenu }`), or a selector in no instance, is an ordinary var, left as authored: not every var
+  with an enum's name is that enum. A selector list is split into one rule per instance.
 - The vars get the specificity of the rule the enum was set in, like any var the site sets there. An
   active preset (`.w-{id} .menu`) outranks `.comp-1`, so its values win over the option; `#comp-1`
   outranks the preset.
 - A var on an instance whose component has no enum of that name is an ordinary var, left as authored.
 - The vars are written where the enum was, so a var the site sets later in the rule wins.
-- An inline element's enum set on its selector is written in place. Set on the instance itself, it gets a rule of its own,
-  `#comp-1 .menu-input:not(#comp-1 .menu .menu-input)`, under the same `@media`, in source order. The `:not()` keeps
-  it off the inline element of another instance nested inside this one.
 - The value must be one of the options, written literally. Anything else fails the build with every
   violation in one error, and the stylesheet is left as it was.
 - A stylesheet with no structure file, or whose components have no custom enums, is left as authored.
 - Declarations inlined from `node_modules` are the wrapper's own and are skipped: its enum defaults on
   `.menu`, and the presets that set enum keys.
-- A `@custom-enum` the plugin can't read (no `default:` among its options) is a warning, not an error: it
-  comes from the wrapper package, which the site can't fix. Its key is left as authored, so the instance
-  gets the wrapper's default.
+- A `@custom-enum` the plugin can't read (no `default:` among its options), or a `@custom-enum-ref` (no
+  `module.Component` type, or no element rule around it), is a warning, not an error: it comes from the wrapper
+  package, which the site can't fix. Its keys are left as authored, so the instance gets the wrapper's default.

package/src/transform/css/postcssPlugin.js

@@ -35,8 +35,8 @@ export const createCssPostcssPlugin = ({ selectPlugins, contextFor, failures })
         if (from === undefined) return
 
         const fileContext = contextFor(from)
-        // A dependency's stylesheet runs no plugins. It only loses a wrapper's `@custom-enum` blocks, which the
-        // custom-enums plugin reads from the wrapper's folder and browsers would skip.
+        // A dependency's stylesheet runs no plugins. It only loses a wrapper's `@custom-enum` blocks and `@custom-enum-ref`
+        // declarations, which the custom-enums plugin reads from the wrapper's folder and browsers would skip.
         if (!isSiteOwned(fileContext.relativePath)) {
             removeCustomEnums(root)
             return

package/src/wrapperImport.js

@@ -0,0 +1,21 @@
+// How a site imports a component's wrapper. origami-site-generator writes these imports, and the custom-enums CSS
+// plugin finds a ref element's type's wrapper through the same names. Kept free of dependencies, so the generator's
+// bundle doesn't take the transforms with it.
+
+/** component-wrapper-server's `PACKAGE_SCOPE` (`src/wrapper/packageTarball.ts`). */
+export const WRAPPERS_SCOPE = '@origami-wrappers'
+
+/**
+ * The name the site depends on a module's wrapper package under. It keeps the module as is, so an
+ * import of it maps back to the module; the package's own name is lowercased, which yarn does not check.
+ * @param {string} module
+ */
+export const wrapperPackageName = module => `${WRAPPERS_SCOPE}/${module}`
+
+/**
+ * Where a component's wrapper is imported from: its folder in the module's package, which
+ * component-wrapper-server names by the symbol lowercased, so `wixEditorElements.WRichText` is
+ * `@origami-wrappers/wixEditorElements/wrichtext`.
+ * @param {{ readonly module: string, readonly symbol: string }} component
+ */
+export const wrapperImport = ({ module, symbol }) => `${wrapperPackageName(module)}/${symbol.toLowerCase()}`