@wix/origami-transforms 0.1.5 → 0.1.7

package/dist/cssPlugins/customEnums.d.ts

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

package/dist/cssPlugins/structureFile.d.ts

@@ -0,0 +1,4 @@
+export function structureFileOf(stylesheetPath: any): string | undefined;
+export function parseStructure(structurePath: any): any;
+export function walk(node: any, visit: any): void;
+export function literalIdOf(openingElement: any): any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/origami-transforms",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Babel and PostCSS checks and transforms for Wix origami page files.",
   "main": "./src/index.js",
   "files": [
@@ -54,5 +54,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "falconPackageHash": "ca2361f449d0870ec5720dae8f71767a7dadabb976f2ed36c1481607"
+  "falconPackageHash": "9674cee94f59f7db338de844100c7527c7eeddff5e2d58f750c8f488"
 }

package/src/cssPlugins/customEnums.js

@@ -0,0 +1,326 @@
+// Resolves a component's custom enums at build time. A site sets only the enum's value on an instance,
+// `#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`), which the page imports and the bundler inlines. The blocks are removed from the output.
+// 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
+// `id="comp-1"`, and the `@origami-wrappers/…` import it is rendered from. See customEnums.md.
+
+import { realpathSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { basename, dirname } from 'node:path'
+import postcss from 'postcss'
+import { LayoutError } from '../transform/layoutError.js'
+import { literalIdOf, parseStructure, structureFileOf, walk } from './structureFile.js'
+
+// `@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>+~]+)*)$/
+
+/** Id → the wrapper import it is rendered from, for elements with a literal `id` and an imported wrapper tag. */
+const importsById = structurePath => {
+    const program = parseStructure(structurePath)
+    const sources = new Map()
+    for (const node of program?.body ?? []) {
+        if (node.type !== 'ImportDeclaration' || !WRAPPER_IMPORT.test(node.source.value)) continue
+        for (const specifier of node.specifiers) sources.set(specifier.local.name, node.source.value)
+    }
+    const byId = new Map()
+    walk(program, node => {
+        if (node.type !== 'JSXOpeningElement' || node.name.type !== 'JSXIdentifier') return
+        const id = literalIdOf(node)
+        const source = sources.get(node.name.name)
+        if (id !== undefined && source !== undefined) byId.set(id, source)
+    })
+    return byId
+}
+
+/** A path with its symlinks resolved, so a wrapper reached through a package manager's links matches its folder. */
+const real = path => {
+    try {
+        return realpathSync(path)
+    } catch {
+        return path
+    }
+}
+
+/**
+ * Id → the enums of every wrapper instance; none for one whose component has no custom enums. An instance's enums
+ * are the `@custom-enum` blocks from its wrapper's folder.
+ */
+const enumsById = (structurePath, byFolder) => {
+    const require = createRequire(structurePath)
+    const byId = new Map()
+    for (const [id, source] of importsById(structurePath)) {
+        let folder
+        try {
+            folder = real(dirname(require.resolve(source)))
+        } catch {
+            folder = undefined
+        }
+        byId.set(id, (folder !== undefined && byFolder.get(folder)) || [])
+    }
+    return byId
+}
+
+/** `selector`, one of the rule's own, resolved through its parent rules, past any at-rules, as CSS Nesting does. */
+const resolve = (rule, selector) => {
+    let selectors = [selector]
+    for (let outer = rule.parent; outer && outer.type !== 'root'; outer = outer.parent) {
+        if (outer.type !== 'rule') continue
+        const inner = selectors
+        selectors = /** @type {import('postcss').Rule} */ (outer).selectors.flatMap(parent =>
+            inner.map(item => (item.includes('&') ? item.replaceAll('&', parent) : `${parent} ${item}`))
+        )
+    }
+    return selectors.map(item => item.trim())
+}
+
+/**
+ * Whether a declaration came from a dependency's stylesheet that the page `@import`s, which the bundler inlines: a
+ * wrapper's `defaults.css` sets its enums' defaults on `.menu`, and its presets set enum keys. Those are the
+ * wrapper's own, never an instance's.
+ */
+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, to remove; 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.
+ */
+const definitionsIn = root => {
+    const byFolder = new Map()
+    const blocks = []
+    const malformed = []
+    root.walkAtRules('custom-enum', block => {
+        blocks.push(block)
+        const keyVar = block.params.trim()
+        const file = block.source?.input.file
+        const rule = block.parent?.type === 'rule' ? /** @type {import('postcss').Rule} */ (block.parent) : undefined
+        const applied = new Map()
+        let defaultValue
+        for (const node of block.nodes ?? []) {
+            if (node.type === 'decl' && node.prop === 'default') defaultValue = node.value.trim()
+            if (node.type === 'atrule' && node.name === 'option') {
+                const values = {}
+                node.each(child => {
+                    if (child.type === 'decl') values[child.prop] = child.value
+                })
+                values[keyVar] ??= node.params.trim()
+                applied.set(node.params.trim(), values)
+            }
+        }
+        if (!keyVar.startsWith('--') || file === undefined || rule === undefined || !applied.has(defaultValue)) {
+            malformed.push(block)
+            return
+        }
+
+        const [selector] = resolve(rule, rule.selector)
+        const [editorSelector, ...inline] = selector.split(/\s+/)
+        const defaults = applied.get(defaultValue)
+        const vars = [...new Set([...applied.values()].flatMap(values => Object.keys(values)))]
+        const options = Object.fromEntries(
+            [...applied].map(([value, values]) => [
+                value,
+                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({
+            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,
+        })
+    })
+    return { byFolder, blocks, malformed }
+}
+
+/** The rule a declaration is in, through any at-rules nested in it. */
+const ruleOf = declaration => {
+    let node = declaration.parent
+    while (node && node.type === 'atrule') node = node.parent
+    return node?.type === 'rule' ? /** @type {import('postcss').Rule} */ (node) : undefined
+}
+
+/** ` (style.css:12)`: the carrier the declaration was written in, which the bundler doesn't name. */
+const where = declaration => {
+    const file = declaration.source?.input.file
+    const line = declaration.source?.start?.line
+    return file ? ` (${basename(file)}${line ? `:${line}` : ''})` : ''
+}
+
+/** The option's vars as declarations, carrying the authored one's `!important` and source. */
+const expansion = (declaration, values) =>
+    Object.entries(values).map(([prop, value]) =>
+        declaration.clone({ prop, value })
+    )
+
+/**
+ * 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.
+ */
+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)
+}
+
+/** @type {import('../transform/types.js').CssTransformPlugin} */
+export const customEnumsPlugin = {
+    name: 'custom-enums',
+    // After mixins copy their bodies in, before presets and layout move declarations out of the instance's rule.
+    order: 11,
+    transform(root, context) {
+        const { byFolder, blocks, malformed } = definitionsIn(root)
+        if (blocks.length === 0) return
+        const structurePath = structureFileOf(context.filePath)
+        if (structurePath !== undefined) context.addDependency?.(structurePath)
+        const instances = structurePath === undefined ? new Map() : enumsById(structurePath, byFolder)
+        const keys = new Set([...instances.values()].flatMap(enums => enums.map(({ key }) => key)))
+
+        /** @type {import('postcss').Declaration[]} */
+        const declarations = []
+        const collect = () =>
+            root.walkDecls(declaration => {
+                if (keys.has(declaration.prop) && !fromDependency(declaration)) declarations.push(declaration)
+            })
+        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.
+         */
+        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.`
+                )
+            }
+            // 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))
+            )
+            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.`
+            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 }
+        }
+
+        // A block comes from the wrapper package, which the site can't fix: its enum is skipped, so an instance that
+        // sets its key keeps it as authored and gets the wrapper's default.
+        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.`
+            )
+        }
+
+        // Every declaration is checked before any is rewritten: a failed run leaves the stylesheet as it was.
+        const violations = new Set()
+        /** @type {any} The first violation's source, whose position the bundler prints. */
+        let first
+        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.']
+            for (const problem of problems) {
+                first ??= declaration.source
+                violations.add(`custom-enums: ${declaration.prop}: ${declaration.value}${where(declaration)}: ${problem}`)
+            }
+        }
+        if (violations.size) {
+            throw new LayoutError([...violations], {
+                file: first?.input.file,
+                line: first?.start?.line,
+                column: first?.start?.column,
+            })
+        }
+
+        for (const block of blocks) {
+            if (block.parent) block.parent.raws.semicolon = true
+            block.remove()
+        }
+
+        // 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 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 [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] : []
+            })
+        }
+    },
+}

package/src/cssPlugins/customEnums.md

@@ -0,0 +1,98 @@
+# Custom enums resolve at build time
+
+A component's manifest can declare a custom enum: a var whose value is one of a few options, each of
+which applies its own set of vars. Menu's `labelAlign`, for example:
+
+| option | `--labelPadding_start` | `--labelPadding_end` |
+|---|---|---|
+| `start` (default) | `var(--labelPadding)` | `20` |
+| `center` | `0` | `0` |
+| `end` | `20` | `var(--labelPadding)` |
+
+A site sets only the option, on the instance:
+
+```css
+#comp-1 { --labelAlign: center; }
+@media (max-width: 750px) {
+    #comp-1 { --labelAlign: end; --labelPadding: 12px; }
+}
+```
+
+and this plugin writes the option's vars in its place:
+
+```css
+#comp-1 { --labelPadding_start: 0; --labelPadding_end: 0; --labelAlign: center; }
+@media (max-width: 750px) {
+    #comp-1 { --labelPadding_start: 20; --labelPadding_end: var(--labelPadding); --labelAlign: end; --labelPadding: 12px; }
+}
+```
+
+An instance that sets nothing gets the default option from the wrapper's `custom-enums.css`, which
+`defaults.css` imports.
+
+## Why not in the browser
+
+Native `if()` could pick the option from the key (`--labelPadding_end: if(style(--labelAlign: end): …)`),
+but Firefox doesn't support it, and an option may apply a var named like its own key (`inputAlign: end`
+applies `--inputAlign: right`). That var's `if()` would read itself, which is a cycle, so the var becomes
+invalid in every browser.
+
+## Where the options come from
+
+The component's wrapper ships them in its `custom-enums.css` (generated by component-wrapper-server), next to
+the defaults:
+
+```css
+.menu {
+    --labelPadding_start: var(--labelPadding);
+    --labelPadding_end: 20;
+    --labelAlign: start;
+
+    @custom-enum --labelAlign {
+        default: start;
+        @option start { --labelPadding_start: var(--labelPadding); --labelPadding_end: 20; }
+        @option center { --labelPadding_start: 0; --labelPadding_end: 0; }
+        @option end { --labelPadding_start: 20; --labelPadding_end: var(--labelPadding); }
+    }
+}
+```
+
+The page's generated stylesheet `@import`s each used wrapper's `defaults.css`, which imports this file, and
+the bundler inlines it, so the blocks are in the document the plugin gets. The plugin reads them and removes
+them from the output. Without the plugin, browsers ignore the unknown at-rule and the defaults still apply.
+An inline element's block sits in `{editor selector} {inline selector}` (`.menu .menu-input`).
+
+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
+import resolves to the wrapper's folder, and the blocks inlined from that folder are its enums. The plugin
+declares the structure file, so editing it re-runs the stylesheet.
+
+Each option is written as the full set of the enum's vars: the default's value wherever the option itself is
+silent, or `inherit` when the default is silent too (what an instance that picks no option gets). So a mobile
+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.
+- 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.

package/src/cssPlugins/index.js

@@ -3,16 +3,18 @@
 // list through `createSiteViteConfig({ cssPlugins })`.
 //
 // A descriptor needs a `name`, an `order`, and `transform(root, context)`, where `root` is the PostCSS Root for the
-// stylesheet; see `../transform/types.js` for the contract and `../transform/css/postcssPlugin.js` for what the
-// stage guarantees a plugin sees. The order matters once: mixin bodies are copied into their calling rules before
-// layout routes declarations to wrappers and SPX converts calls using the browser's active settings. stack-children
-// only checks, and runs between mixins and layout: it needs the mixins' declarations and the stack rules as authored,
-// before layout compiles them away. presets runs after mixins too, so a `--preset` a mixin body carries is moved
-// like an authored one. fonts appends the `@font-face` rules that load the Wix fonts the stylesheet names from Wix's
-// CDN.
+// stylesheet; see `../transform/types.js` for the contract and `../transform/css/postcssPlugin.js` for what the stage
+// guarantees a plugin sees. The order matters once: mixin bodies are copied into their calling rules before layout
+// routes declarations to wrappers and SPX converts calls using the browser's active settings. stack-children only
+// checks, and runs between mixins and layout: it needs the mixins' declarations and the stack rules as authored, before
+// layout compiles them away. presets runs after mixins too, so a `--preset` a mixin body carries is moved like an
+// 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.
 //
 // `@layer` needs no plugin: cascade layers have been in every browser since March 2022.
 
+import { customEnumsPlugin } from './customEnums.js'
 import { customMediaPlugin } from './customMedia.js'
 import { fontsPlugin } from './fonts.js'
 import { mixinsPlugin } from './mixins.js'
@@ -26,6 +28,7 @@ export const cssPlugins = Object.freeze([
     customMediaPlugin,
     fontsPlugin,
     mixinsPlugin,
+    customEnumsPlugin,
     stackChildrenPlugin,
     presetsPlugin,
     layoutPlugin,

package/src/cssPlugins/stackChildren.js

@@ -3,18 +3,14 @@
 //
 // A stack is a parent whose rule declares `--container-layout-type: StackContainerLayout`; its
 // `flex-direction` says which way it stacks (column → vertical, anything else → horizontal, as in
-// CSS). Parent and child are the JSX tree's, so the tree comes from the item's `structure.tsx` (or `.jsx`): next
-// to the stylesheet, or one folder up when the stylesheet is the generated one in `_generated/`. Elements and
-// rules meet on `id` and `#id`. The stylesheet is the page's, with its
+// CSS). Parent and child are the JSX tree's, so the tree comes from the item's structure file (see
+// structureFile.js). The stylesheet is the page's, with its
 // carriers already inlined (see ../transform/css/postcssPlugin.js), so every rule is in view.
 
-import { existsSync, readFileSync } from 'node:fs'
-import { basename, dirname, join } from 'node:path'
-import { parseSync } from '@babel/core'
+import { basename } from 'node:path'
 import { LayoutError } from '../transform/layoutError.js'
+import { literalIdOf, parseStructure, structureFileOf, walk } from './structureFile.js'
 
-const STRUCTURE_FILES = ['structure.tsx', 'structure.jsx']
-const GENERATED = '_generated'
 const STACK_CONTAINER = 'StackContainerLayout'
 const BASE = ''
 
@@ -56,46 +52,21 @@ const lengthOf = token => {
     return UNIT.exec(token)?.[1].toLowerCase()
 }
 
-/** The folder holding the structure file a stylesheet is checked against: its own, or its item's for `_generated/`. */
-const structureFolderOf = stylesheetPath => {
-    const folder = dirname(stylesheetPath)
-    return basename(folder) === GENERATED ? dirname(folder) : folder
-}
-
 /** Child id → its direct parent's id, for elements with a literal `id`. Slot props are not children. */
 const parentsIn = structurePath => {
-    const ast = parseSync(readFileSync(structurePath, 'utf8'), {
-        babelrc: false,
-        configFile: false,
-        filename: structurePath,
-        parserOpts: { plugins: structurePath.endsWith('.tsx') ? ['jsx', 'typescript'] : ['jsx'] },
-    })
     const parents = new Map()
-    const idOf = element => {
-        const attribute = element.openingElement.attributes.find(
-            node => node.type === 'JSXAttribute' && node.name.name === 'id' && node.value?.type === 'StringLiteral'
-        )
-        return attribute?.value.value
-    }
     const directChildren = node =>
         node.children.flatMap(child =>
             child.type === 'JSXElement' ? [child] : child.type === 'JSXFragment' ? directChildren(child) : []
         )
-    const visit = node => {
-        if (Array.isArray(node)) return node.forEach(visit)
-        if (!node || typeof node.type !== 'string') return
-        if (node.type === 'JSXElement') {
-            const parent = idOf(node)
-            for (const child of directChildren(node)) {
-                const id = idOf(child)
-                if (parent !== undefined && id !== undefined) parents.set(id, parent)
-            }
-        }
-        for (const [key, value] of Object.entries(node)) {
-            if (key !== 'loc' && value && typeof value === 'object') visit(value)
+    walk(parseStructure(structurePath), node => {
+        if (node.type !== 'JSXElement') return
+        const parent = literalIdOf(node.openingElement)
+        for (const child of directChildren(node)) {
+            const id = literalIdOf(child.openingElement)
+            if (parent !== undefined && id !== undefined) parents.set(id, parent)
         }
-    }
-    visit(ast?.program)
+    })
     return parents
 }
 
@@ -158,9 +129,7 @@ export const stackChildrenPlugin = {
     // After mixins copy their bodies in, before spx rewrites --spx() calls away.
     order: 12,
     transform(root, context) {
-        const structurePath = STRUCTURE_FILES.map(file => join(structureFolderOf(context.filePath), file)).find(
-            existsSync
-        )
+        const structurePath = structureFileOf(context.filePath)
         if (structurePath === undefined) return
         context.addDependency?.(structurePath)
         const parents = parentsIn(structurePath)

package/src/cssPlugins/structureFile.js

@@ -0,0 +1,43 @@
+// The item's structure file, for CSS plugins that check a stylesheet against its JSX tree: `structure.tsx` (or
+// `.jsx`) next to the stylesheet, or one folder up when the stylesheet is the generated one in `_generated/`.
+// Elements and rules meet on a literal `id` and `#id`.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { parseSync } from '@babel/core'
+
+const STRUCTURE_FILES = ['structure.tsx', 'structure.jsx']
+const GENERATED = '_generated'
+
+/** The structure file `stylesheetPath` is checked against, or undefined when its item has none. */
+export const structureFileOf = stylesheetPath => {
+    const folder = dirname(stylesheetPath)
+    const item = basename(folder) === GENERATED ? dirname(folder) : folder
+    return STRUCTURE_FILES.map(file => join(item, file)).find(existsSync)
+}
+
+/** The structure file's program. */
+export const parseStructure = structurePath =>
+    parseSync(readFileSync(structurePath, 'utf8'), {
+        babelrc: false,
+        configFile: false,
+        filename: structurePath,
+        parserOpts: { plugins: structurePath.endsWith('.tsx') ? ['jsx', 'typescript'] : ['jsx'] },
+    })?.program
+
+/** Calls `visit` on every node under `node`, parents first. */
+export const walk = (node, visit) => {
+    if (Array.isArray(node)) return node.forEach(child => walk(child, visit))
+    if (!node || typeof node.type !== 'string') return
+    visit(node)
+    for (const [key, value] of Object.entries(node)) {
+        if (key !== 'loc' && value && typeof value === 'object') walk(value, visit)
+    }
+}
+
+/** A JSX opening element's `id`, when it is a string literal. */
+export const literalIdOf = openingElement =>
+    openingElement.attributes.find(
+        attribute =>
+            attribute.type === 'JSXAttribute' && attribute.name.name === 'id' && attribute.value?.type === 'StringLiteral'
+    )?.value.value