@wix/origami-transforms 0.1.28 → 0.1.30

package/src/cssPlugins/spxThemeVariables/utils/copyPlanUtils.js

@@ -0,0 +1,162 @@
+import { THEME_SPX } from '../../spx/calls.js'
+import { cascadeAt, inheritedBreakpointsOf, themeBreakpointsOf, widestFirst } from './breakpointUtils.js'
+import { DESKTOP } from './cssTreeUtils.js'
+import { CONTENT_MAX_WIDTH } from './sectionUtils.js'
+
+/** @typedef {import('./breakpointUtils.js').CascadedVariable} CascadedVariable */
+/** @typedef {import('./breakpointUtils.js').ThemeVariables} ThemeVariables */
+/** @typedef {import('./breakpointUtils.js').VariableMap} VariableMap */
+/** @typedef {import('postcss').Declaration} Declaration */
+/** @typedef {Map<string, VariableMap>} ThemeCopies */
+/** @typedef {Map<string, string[]>} VariableReferences */
+/** @typedef {Map<string, string[]>} BreakpointPlan */
+
+const VAR_REFERENCE = /var\(\s*(--[\w-]+)/g
+
+/** @param {ThemeVariables} theme */
+const getPlanOrder = theme => {
+    const breakpoints = themeBreakpointsOf(theme)
+    const widest = widestFirst(breakpoints)
+    return [DESKTOP, ...widest]
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @returns {BreakpointPlan}
+ */
+export const planBreakpoints = theme => {
+    const breakpoints = getPlanOrder(theme)
+    const entries = breakpoints.map(breakpoint => {
+        const inheritedBreakpoints = inheritedBreakpointsOf(theme, breakpoint)
+        return /** @type {const} */ ([breakpoint, inheritedBreakpoints])
+    })
+    return new Map(entries)
+}
+
+/** @param {Declaration} declaration */
+const getReferencedNames = declaration => {
+    const matches = [...declaration.value.matchAll(VAR_REFERENCE)]
+    return matches.map(([, name]) => name)
+}
+
+/**
+ * @param {VariableMap} variables
+ * @returns {VariableReferences}
+ */
+const buildReferenceMap = variables => {
+    /** @type {VariableReferences} */
+    const references = new Map()
+    for (const [prop, declaration] of variables) {
+        const names = getReferencedNames(declaration)
+        references.set(prop, names)
+    }
+    return references
+}
+
+/**
+ * @param {Set<string>} targets
+ * @param {readonly string[]} names
+ */
+const readsAny = (targets, names) => names.some(name => targets.has(name))
+
+/**
+ * @param {VariableReferences} references
+ * @param {Set<string>} seeds
+ */
+const collectReaders = (references, seeds) => {
+    const reached = new Set(seeds)
+    let previousSize = -1
+    while (reached.size !== previousSize) {
+        previousSize = reached.size
+        for (const [prop, names] of references) {
+            if (readsAny(reached, names)) reached.add(prop)
+        }
+    }
+    return reached
+}
+
+/** @param {VariableMap} variables */
+const findScaleDependent = variables => {
+    const scaledVariables = [...variables].filter(([, declaration]) => declaration.value.includes(THEME_SPX))
+    const scaledProps = scaledVariables.map(([prop]) => prop)
+    const scaled = new Set(scaledProps)
+    const references = buildReferenceMap(variables)
+    return collectReaders(references, scaled)
+}
+
+/**
+ * @param {Map<string, CascadedVariable>} cascaded
+ * @returns {VariableMap}
+ */
+const mergeCascade = cascaded => {
+    const variables = [...cascaded].map(([prop, { declaration }]) => /** @type {const} */ ([prop, declaration]))
+    return new Map(variables)
+}
+
+/**
+ * @param {Map<string, CascadedVariable>} cascaded
+ * @param {string} breakpoint
+ * @returns {VariableMap}
+ */
+const ownVariablesOf = (cascaded, breakpoint) => {
+    const own = [...cascaded].filter(([, cascadedVariable]) => cascadedVariable.breakpoint === breakpoint)
+    const variables = own.map(([prop, { declaration }]) => /** @type {const} */ ([prop, declaration]))
+    return new Map(variables)
+}
+
+/**
+ * @param {ThemeCopies} themeCopies
+ * @param {readonly string[]} inheritedBreakpoints
+ */
+const getWiderCopiedNames = (themeCopies, inheritedBreakpoints) => {
+    const props = inheritedBreakpoints.flatMap(breakpoint => {
+        const copies = themeCopies.get(breakpoint) ?? new Map()
+        return [...copies.keys()]
+    })
+    return new Set(props)
+}
+
+/**
+ * @typedef {object} CopyCriteria
+ * @property {VariableMap} ownVariables
+ * @property {Set<string>} scaleDependent
+ * @property {Set<string>} widerCopied
+ */
+
+/**
+ * @param {string} prop
+ * @param {CopyCriteria} criteria
+ */
+const shouldCopy = (prop, { ownVariables, scaleDependent, widerCopied }) =>
+    ownVariables.has(prop)
+        ? scaleDependent.has(prop) || widerCopied.has(prop)
+        : scaleDependent.has(prop) && !widerCopied.has(prop)
+
+/**
+ * @param {string} prop
+ * @param {CopyCriteria} criteria
+ */
+const shouldCopyVariable = (prop, criteria) => prop !== CONTENT_MAX_WIDTH && shouldCopy(prop, criteria)
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {BreakpointPlan} breakpointPlan
+ * @returns {ThemeCopies}
+ */
+export const planThemeCopies = (theme, breakpointPlan) => {
+    /** @type {ThemeCopies} */
+    const themeCopies = new Map()
+    for (const [breakpoint, inheritedBreakpoints] of breakpointPlan) {
+        const cascadeBreakpoints = [...inheritedBreakpoints, breakpoint]
+        const cascaded = cascadeAt(theme, cascadeBreakpoints)
+        const ownVariables = ownVariablesOf(cascaded, breakpoint)
+        const effectiveVariables = mergeCascade(cascaded)
+        const scaleDependent = findScaleDependent(effectiveVariables)
+        const widerCopied = getWiderCopiedNames(themeCopies, inheritedBreakpoints)
+        const criteria = { ownVariables, scaleDependent, widerCopied }
+        const copiedEntries = [...effectiveVariables].filter(([prop]) => shouldCopyVariable(prop, criteria))
+        const copies = new Map(copiedEntries)
+        themeCopies.set(breakpoint, copies)
+    }
+    return themeCopies
+}

package/src/cssPlugins/spxThemeVariables/utils/cssTreeUtils.js

@@ -0,0 +1,58 @@
+import { DEFAULTS_LAYER } from '../../layout/contract.js'
+
+export const DESKTOP = ''
+
+/**
+ * @param {import('postcss').Node} node
+ * @returns {import('postcss').Node[]}
+ */
+export const ancestorsOf = node => {
+    /** @type {import('postcss').Node[]} */
+    const ancestors = []
+    let current = node.parent
+    while (current !== undefined && current.type !== 'root' && current.type !== 'document') {
+        ancestors.push(current)
+        current = current.parent
+    }
+    return ancestors
+}
+
+/**
+ * @param {import('postcss').Node} node
+ * @returns {node is import('postcss').AtRule}
+ */
+export const isAtRule = node => node.type === 'atrule'
+
+/** @param {string} text */
+export const collapseWhitespace = text => text.replace(/\s+/g, ' ').trim()
+
+/**
+ * @param {import('postcss').Node} node
+ * @param {string} name
+ */
+const isLayerNamed = (node, name) => isAtRule(node) && node.name === 'layer' && node.params.trim() === name
+
+/** @param {readonly import('postcss').Node[]} ancestors */
+export const isInContainerDefaults = ancestors => ancestors.some(node => isLayerNamed(node, DEFAULTS_LAYER))
+
+/** @param {readonly import('postcss').Node[]} ancestors */
+export const isTopLevel = ancestors => ancestors.every(isAtRule)
+
+/** @param {import('postcss').Rule} rule */
+export const hasRootSelector = rule => rule.selector.trim() === ':root'
+
+/** @param {string} prop */
+export const isCustomProperty = prop => prop.startsWith('--')
+
+/**
+ * @param {import('postcss').Node} node
+ * @returns {node is import('postcss').AtRule}
+ */
+export const isMedia = node => isAtRule(node) && node.name === 'media'
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @returns {import('postcss').Declaration[]}
+ */
+export const declarationsOf = rule =>
+    rule.nodes.filter(/** @returns {node is import('postcss').Declaration} */ node => node.type === 'decl')

package/src/cssPlugins/spxThemeVariables/utils/restateUtils.js

@@ -0,0 +1,134 @@
+import { cascadeAt, maxWidthOf, refWidthAt } from './breakpointUtils.js'
+import { isAtRule } from './cssTreeUtils.js'
+
+/** @typedef {import('./breakpointUtils.js').CascadedVariable} CascadedVariable */
+/** @typedef {import('./breakpointUtils.js').ThemeVariables} ThemeVariables */
+/** @typedef {import('./copyPlanUtils.js').BreakpointPlan} BreakpointPlan */
+
+/**
+ * @typedef {object} RestateTarget
+ * @property {string} breakpoint
+ * @property {number} index
+ * @property {number} refWidth
+ */
+
+const SPX_CALL = '--spx('
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {string} breakpoint
+ */
+const lastIndexAt = ({ rules }, breakpoint) => {
+    const indexes = rules.flatMap(({ scanned }, index) => (scanned.breakpoint === breakpoint ? [index] : []))
+    return indexes.at(-1)
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {RestateTarget} target
+ * @param {[string, CascadedVariable]} entry
+ */
+const needsRestate = (theme, target, [, source]) => {
+    if (source.breakpoint === target.breakpoint) return false
+    if (source.index > target.index) return false
+    if (!source.declaration.value.includes(SPX_CALL)) return false
+    const sourceRefWidth = refWidthAt(theme, source.breakpoint)
+    return sourceRefWidth !== target.refWidth
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {RestateTarget} target
+ * @param {[string, CascadedVariable]} entry
+ */
+const narrowerRuleIndexOf = ({ rules }, target, [prop, source]) => {
+    const targetWidth = maxWidthOf(target.breakpoint)
+    if (targetWidth === undefined) return -1
+    const sourceIndex = rules.findIndex(({ scanned }) => scanned.rule === source.declaration.parent)
+    const declaresNarrower = ({ scanned, variables }, index) => {
+        const width = maxWidthOf(scanned.breakpoint)
+        return index > sourceIndex && width !== undefined && width < targetWidth && variables.has(prop)
+    }
+    return rules.findIndex(declaresNarrower)
+}
+
+/**
+ * @param {import('./breakpointUtils.js').ThemeRule} target
+ * @param {[string, CascadedVariable]} entry
+ */
+const restateInto = ({ scanned, variables }, [prop, { declaration }]) => {
+    const clone = declaration.clone({ raws: {} })
+    scanned.rule.append(clone)
+    scanned.declarations.push(clone)
+    variables.set(prop, clone)
+}
+
+/**
+ * @param {import('postcss').Declaration} clone
+ * @param {import('postcss').Rule} targetRule
+ * @param {import('postcss').AtRule} targetMedia
+ */
+const wrapperOf = (clone, targetRule, targetMedia) => {
+    const rule = targetRule.clone({ raws: {} }).removeAll()
+    rule.append(clone)
+    const wrapper = targetMedia.clone({ raws: {} }).removeAll()
+    wrapper.append(rule)
+    return { rule, wrapper }
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {import('./breakpointUtils.js').ThemeRule} targetRule
+ * @param {number} index
+ * @param {[string, CascadedVariable]} entry
+ */
+const restateBefore = (theme, targetRule, index, entry) => {
+    const [prop, { declaration }] = entry
+    const targetMedia = targetRule.scanned.rule.parent
+    const narrowerMedia = theme.rules[index].scanned.rule.parent
+    if (targetMedia === undefined || narrowerMedia === undefined) return restateInto(targetRule, entry)
+    if (!isAtRule(targetMedia) || !isAtRule(narrowerMedia)) return restateInto(targetRule, entry)
+    const clone = declaration.clone({ raws: {} })
+    const { rule, wrapper } = wrapperOf(clone, targetRule.scanned.rule, targetMedia)
+    narrowerMedia.before(wrapper)
+    const { breakpoint } = targetRule.scanned
+    const scanned = { rule, breakpoint, declarations: [clone] }
+    theme.rules.splice(index, 0, { scanned, variables: new Map([[prop, clone]]) })
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {import('./breakpointUtils.js').ThemeRule} targetRule
+ * @param {RestateTarget} target
+ * @param {[string, CascadedVariable]} entry
+ */
+const restate = (theme, targetRule, target, entry) => {
+    const index = narrowerRuleIndexOf(theme, target, entry)
+    const targetIndex = theme.rules.indexOf(targetRule)
+    if (index === -1 || index >= targetIndex) return restateInto(targetRule, entry)
+    restateBefore(theme, targetRule, index, entry)
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {string} breakpoint
+ * @param {readonly string[]} inheritedBreakpoints
+ */
+const restateAt = (theme, breakpoint, inheritedBreakpoints) => {
+    const index = lastIndexAt(theme, breakpoint)
+    if (index === undefined) return
+    const refWidth = refWidthAt(theme, breakpoint)
+    const target = { breakpoint, index, refWidth }
+    const cascaded = cascadeAt(theme, [...inheritedBreakpoints, breakpoint])
+    const stale = [...cascaded].filter(entry => needsRestate(theme, target, entry))
+    const targetRule = theme.rules[index]
+    for (const entry of stale) restate(theme, targetRule, target, entry)
+}
+
+/**
+ * @param {ThemeVariables} theme
+ * @param {BreakpointPlan} breakpointPlan
+ */
+export const restateThemeVariables = (theme, breakpointPlan) => {
+    for (const [breakpoint, inheritedBreakpoints] of breakpointPlan) restateAt(theme, breakpoint, inheritedBreakpoints)
+}

package/src/cssPlugins/spxThemeVariables/utils/sectionUtils.js

@@ -0,0 +1,32 @@
+import { DESKTOP } from './cssTreeUtils.js'
+import { wrappingAtRulesOf } from './wrappingAtRuleUtils.js'
+
+/** @typedef {import('./stylesheetUtils.js').ScannedRule} ScannedRule */
+/** @typedef {import('./wrappingAtRuleUtils.js').Section} Section */
+
+export const CONTENT_MAX_WIDTH = '--content-max-width'
+
+/** @param {ScannedRule} layoutRule */
+const capsAtDesktop = ({ breakpoint, declarations }) => {
+    if (breakpoint !== DESKTOP) return false
+    return declarations.some(({ prop }) => prop === CONTENT_MAX_WIDTH)
+}
+
+/**
+ * @param {ScannedRule} layoutRule
+ * @returns {Section}
+ */
+const sectionOf = ({ rule }) => {
+    const selector = rule.selector.trim()
+    const wrappingAtRules = wrappingAtRulesOf(rule)
+    return { selector, wrappingAtRules }
+}
+
+/**
+ * @param {readonly ScannedRule[]} layoutRules
+ * @returns {Section[]}
+ */
+export const readSectionRules = layoutRules => {
+    const sectionsWithMaxWidthRules = layoutRules.filter(capsAtDesktop)
+    return sectionsWithMaxWidthRules.map(sectionOf)
+}

package/src/cssPlugins/spxThemeVariables/utils/stylesheetUtils.js

@@ -0,0 +1,98 @@
+import { breakpointOf, maxWidthOf } from './breakpointUtils.js'
+import {
+    ancestorsOf,
+    declarationsOf,
+    hasRootSelector,
+    isInContainerDefaults,
+    isMedia,
+    isTopLevel,
+} from './cssTreeUtils.js'
+import { relativeToSite } from '../../../transform/relativeToSite.js'
+
+/**
+ * @typedef {object} ScannedRule
+ * @property {import('postcss').Rule} rule
+ * @property {string} breakpoint
+ * @property {import('postcss').Declaration[]} declarations
+ */
+
+/**
+ * @typedef {object} StylesheetScan
+ * @property {ScannedRule[]} themeRules
+ * @property {ScannedRule[]} layoutRules
+ */
+
+const THEME_FILE = 'src/global/themes/theme.css'
+
+/** @param {readonly import('postcss').Node[]} ancestors */
+const isThemeContext = ancestors => {
+    const [parent] = ancestors
+    if (parent === undefined) return true
+    return ancestors.length === 1 && isMedia(parent) && maxWidthOf(parent.params) !== undefined
+}
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @param {string} siteFolder
+ */
+const isFromThemeFile = (rule, siteFolder) => {
+    const file = rule.source?.input.file
+    if (file === undefined) return false
+    const relative = relativeToSite(siteFolder, file)
+    return relative === THEME_FILE
+}
+
+/** @param {readonly import('postcss').Node[]} ancestors */
+const isLayoutRule = ancestors => isTopLevel(ancestors) && !isInContainerDefaults(ancestors)
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @param {import('postcss').Node[]} ancestors
+ * @returns {ScannedRule}
+ */
+const scannedRuleOf = (rule, ancestors) => {
+    const breakpoint = breakpointOf(ancestors)
+    const declarations = declarationsOf(rule)
+    return { rule, breakpoint, declarations }
+}
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @param {string} siteFolder
+ * @returns {ScannedRule[]}
+ */
+const themeRuleOf = (rule, siteFolder) => {
+    if (!isFromThemeFile(rule, siteFolder)) return []
+    const ancestors = ancestorsOf(rule)
+    if (!isThemeContext(ancestors)) return []
+    return [scannedRuleOf(rule, ancestors)]
+}
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @returns {ScannedRule[]}
+ */
+const layoutRuleOf = rule => {
+    const ancestors = ancestorsOf(rule)
+    return isLayoutRule(ancestors) ? [scannedRuleOf(rule, ancestors)] : []
+}
+
+/**
+ * @param {import('postcss').Root} root
+ * @param {string} siteFolder
+ * @returns {StylesheetScan}
+ */
+export const scanStylesheet = (root, siteFolder) => {
+    /** @type {StylesheetScan} */
+    const scan = { themeRules: [], layoutRules: [] }
+    root.walkRules(rule => {
+        if (hasRootSelector(rule)) {
+            const themeRules = themeRuleOf(rule, siteFolder)
+            scan.themeRules.push(...themeRules)
+            return
+        }
+        const layoutRules = layoutRuleOf(rule)
+        scan.layoutRules.push(...layoutRules)
+    })
+    return scan
+}

package/src/cssPlugins/spxThemeVariables/utils/themeUtils.js

@@ -0,0 +1,90 @@
+import { toThemeCalls } from '../../spx/calls.js'
+import { refWidthAt, resolveRefWidths } from './breakpointUtils.js'
+import { DESKTOP, isCustomProperty } from './cssTreeUtils.js'
+
+/** @typedef {import('./breakpointUtils.js').ThemeRule} ThemeRule */
+/** @typedef {import('./breakpointUtils.js').ThemeVariables} ThemeVariables */
+/** @typedef {import('./breakpointUtils.js').VariableMap} VariableMap */
+/** @typedef {import('./stylesheetUtils.js').ScannedRule} ScannedRule */
+
+const REF_WIDTH = '--spx-ref-width'
+
+const SPX_SETTINGS = new Set([
+    REF_WIDTH,
+    '--spx-resolver-type',
+    '--spx-stopper-min',
+    '--spx-stopper-max',
+    '--scaling-factor',
+    '--scrollbar-width',
+])
+
+/** @param {string} prop */
+const isThemeVariable = prop => isCustomProperty(prop) && !SPX_SETTINGS.has(prop)
+
+/** @param {number} refWidth */
+const isUsableRefWidth = refWidth => Number.isFinite(refWidth) && refWidth > 0
+
+/** @param {readonly ScannedRule[]} themeRules */
+const rootDeclarationsByBreakpointOf = themeRules => {
+    /** @type {Map<string, VariableMap>} */
+    const declarationsByBreakpoint = new Map()
+    for (const { breakpoint, declarations } of themeRules) {
+        const declarationMap = declarationsByBreakpoint.get(breakpoint) ?? new Map()
+        declarationsByBreakpoint.set(breakpoint, declarationMap)
+        for (const declaration of declarations) {
+            declarationMap.set(declaration.prop, declaration)
+        }
+    }
+    return declarationsByBreakpoint
+}
+
+/**
+ * @param {ScannedRule} scanned
+ * @returns {ThemeRule}
+ */
+const themeRuleOf = scanned => {
+    const themeVariables = scanned.declarations.filter(({ prop }) => isThemeVariable(prop))
+    const entries = themeVariables.map(declaration => /** @type {const} */ ([declaration.prop, declaration]))
+    const variables = new Map(entries)
+    return { scanned, variables }
+}
+
+/** @param {Map<string, VariableMap>} declarationsByBreakpoint */
+const breakpointsOf = declarationsByBreakpoint => {
+    const breakpoints = [...declarationsByBreakpoint.keys()]
+    return breakpoints.filter(breakpoint => breakpoint !== DESKTOP)
+}
+
+/** @param {Map<string, VariableMap>} declarationsByBreakpoint */
+const refWidthByBreakpointOf = declarationsByBreakpoint => {
+    const refWidths = [...declarationsByBreakpoint].flatMap(([breakpoint, declarationMap]) => {
+        const refWidth = Number(declarationMap.get(REF_WIDTH)?.value)
+        return isUsableRefWidth(refWidth) ? [/** @type {const} */ ([breakpoint, refWidth])] : []
+    })
+    return new Map(refWidths)
+}
+
+/**
+ * @param {readonly ScannedRule[]} themeRules
+ * @returns {ThemeVariables}
+ */
+export const readThemeVariables = themeRules => {
+    const declarationsByBreakpoint = rootDeclarationsByBreakpointOf(themeRules)
+    const rules = themeRules.map(themeRuleOf)
+    const breakpoints = breakpointsOf(declarationsByBreakpoint)
+    const ownRefWidths = refWidthByBreakpointOf(declarationsByBreakpoint)
+    const refWidthByBreakpoint = resolveRefWidths(breakpoints, ownRefWidths)
+    return { rules, breakpoints, refWidthByBreakpoint }
+}
+
+/**
+ * @param {readonly ScannedRule[]} themeRules
+ * @param {ThemeVariables} theme
+ */
+export const tagThemeVariables = (themeRules, theme) => {
+    for (const { breakpoint, declarations } of themeRules) {
+        const refWidth = refWidthAt(theme, breakpoint)
+        const variables = declarations.filter(({ prop }) => isThemeVariable(prop))
+        for (const declaration of variables) declaration.value = toThemeCalls(declaration.value, refWidth)
+    }
+}

package/src/cssPlugins/spxThemeVariables/utils/wrappingAtRuleUtils.js

@@ -0,0 +1,68 @@
+import { ancestorsOf, collapseWhitespace, isAtRule } from './cssTreeUtils.js'
+
+/**
+ * @typedef {object} Section
+ * @property {string} selector
+ * @property {import('postcss').AtRule[]} wrappingAtRules
+ */
+
+/**
+ * @typedef {object} SectionGroup
+ * @property {import('postcss').AtRule[]} wrappingAtRules
+ * @property {string[]} selectors
+ */
+
+const UNWRAPPED_KEY = ''
+
+/**
+ * @param {import('postcss').Node} node
+ * @returns {node is import('postcss').AtRule}
+ */
+const isWrappingAtRule = node => isAtRule(node) && node.name !== 'layer'
+
+/**
+ * @param {import('postcss').Rule} rule
+ * @returns {import('postcss').AtRule[]}
+ */
+export const wrappingAtRulesOf = rule => {
+    const ancestors = ancestorsOf(rule)
+    const wrappingAtRules = ancestors.filter(isWrappingAtRule)
+    return wrappingAtRules.reverse()
+}
+
+/** @param {import('postcss').AtRule} atRule */
+const atRuleLabelOf = ({ name, params }) => {
+    const collapsed = collapseWhitespace(params)
+    return `@${name} ${collapsed}`
+}
+
+/** @param {readonly import('postcss').AtRule[]} wrappingAtRules */
+const wrappingKeyOf = wrappingAtRules => {
+    const labels = wrappingAtRules.map(atRuleLabelOf)
+    return labels.join(' ')
+}
+
+/**
+ * @param {Map<string, SectionGroup>} groups
+ * @param {Section} section
+ */
+const addSectionToGroup = (groups, { selector, wrappingAtRules }) => {
+    const key = wrappingKeyOf(wrappingAtRules)
+    const group = groups.get(key) ?? { wrappingAtRules, selectors: [] }
+    if (!group.selectors.includes(selector)) group.selectors.push(selector)
+    groups.set(key, group)
+}
+
+/**
+ * @param {readonly Section[]} sections
+ * @returns {SectionGroup[]}
+ */
+export const groupSectionsByWrappingAtRules = sections => {
+    /** @type {Map<string, SectionGroup>} */
+    const groups = new Map()
+    for (const section of sections) addSectionToGroup(groups, section)
+    const unwrapped = groups.get(UNWRAPPED_KEY)
+    groups.delete(UNWRAPPED_KEY)
+    const wrapped = [...groups.values()]
+    return unwrapped === undefined ? wrapped : [unwrapped, ...wrapped]
+}