canonicalizeAst() — tailwindcss Function Reference

Architecture documentation for the canonicalizeAst() function in canonicalize-candidates.ts from the tailwindcss codebase.

Function typescript CompilerEngine AstTransformation calls 6 called by 2

Entity Profile

CompilerEngine→ AstTransformation→ canonicalizeAst() — tailwindcss Function Reference

Dependency Diagram

graph TD
  84dbd847_e2eb_8fba_afa7_47012ee6086f["canonicalizeAst()"]
  00f82a70_37cd_d9d2_64c8_29c748c197c6["createUtilitySignatureCache()"]
  00f82a70_37cd_d9d2_64c8_29c748c197c6 -->|calls| 84dbd847_e2eb_8fba_afa7_47012ee6086f
  1990afd0_c36f_335a_ba33_c341aee76086["createUtilityPropertiesCache()"]
  1990afd0_c36f_335a_ba33_c341aee76086 -->|calls| 84dbd847_e2eb_8fba_afa7_47012ee6086f
  524663ee_dcd5_80b9_29bd_e2f21fc950aa["expandDeclaration()"]
  84dbd847_e2eb_8fba_afa7_47012ee6086f -->|calls| 524663ee_dcd5_80b9_29bd_e2f21fc950aa
  1d9d6293_9d1d_5445_6e1b_8f6256992b8a["resolveVariablesInValue()"]
  84dbd847_e2eb_8fba_afa7_47012ee6086f -->|calls| 1d9d6293_9d1d_5445_6e1b_8f6256992b8a
  9df707f7_aef8_37b0_5f90_edacde047f5b["constantFoldDeclaration()"]
  84dbd847_e2eb_8fba_afa7_47012ee6086f -->|calls| 9df707f7_aef8_37b0_5f90_edacde047f5b
  a28c52ab_40ed_1df4_72a0_d29fd07e7429["printArbitraryValue()"]
  84dbd847_e2eb_8fba_afa7_47012ee6086f -->|calls| a28c52ab_40ed_1df4_72a0_d29fd07e7429
  3ba19013_498f_3c9b_5c44_0eb24efc4394["add()"]
  84dbd847_e2eb_8fba_afa7_47012ee6086f -->|calls| 3ba19013_498f_3c9b_5c44_0eb24efc4394
  e9d556bc_f22d_356c_1bd2_27442c34b5c7["walk()"]
  84dbd847_e2eb_8fba_afa7_47012ee6086f -->|calls| e9d556bc_f22d_356c_1bd2_27442c34b5c7
  style 84dbd847_e2eb_8fba_afa7_47012ee6086f fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/tailwindcss/src/canonicalize-candidates.ts lines 2070–2171

function canonicalizeAst(designSystem: DesignSystem, ast: AstNode[], options: SignatureOptions) {
  let { rem } = options

  walk(ast, {
    enter(node, ctx) {
      // Optimize declarations
      if (node.kind === 'declaration') {
        if (node.value === undefined || node.property === '--tw-sort') {
          return WalkAction.Replace([])
        }

        // Ignore `--tw-{property}` if `{property}` exists with the same value
        if (node.property.startsWith('--tw-')) {
          if (
            (ctx.parent?.nodes ?? []).some(
              (sibling) =>
                sibling.kind === 'declaration' &&
                node.value === sibling.value &&
                node.important === sibling.important &&
                !sibling.property.startsWith('--tw-'),
            )
          ) {
            return WalkAction.Replace([])
          }
        }

        if (options.features & SignatureFeatures.ExpandProperties) {
          let replacement = expandDeclaration(node, options.features)
          if (replacement) return WalkAction.Replace(replacement)
        }

        // Resolve theme values to their inlined value.
        if (node.value.includes('var(')) {
          node.value = resolveVariablesInValue(node.value, designSystem)
        }

        // Very basic `calc(…)` constant folding to handle the spacing scale
        // multiplier:
        //
        // Input:  `--spacing(4)`
        //       → `calc(var(--spacing, 0.25rem) * 4)`
        //       → `calc(0.25rem * 4)`       ← this is the case we will see
        //                                     after inlining the variable
        //       → `1rem`
        node.value = constantFoldDeclaration(node.value, rem)

        // We will normalize the `node.value`, this is the same kind of logic
        // we use when printing arbitrary values. It will remove unnecessary
        // whitespace.
        //
        // Essentially normalizing the `node.value` to a canonical form.
        node.value = printArbitraryValue(node.value)
      }

      // Replace special nodes with its children
      else if (node.kind === 'context' || node.kind === 'at-root') {
        return WalkAction.Replace(node.nodes)
      }

      // Remove comments
      else if (node.kind === 'comment') {
        return WalkAction.Replace([])
      }

      // Remove at-rules that are not needed for the signature
      else if (node.kind === 'at-rule' && node.name === '@property') {
        return WalkAction.Replace([])
      }
    },
    exit(node) {
      if (node.kind === 'rule' || node.kind === 'at-rule') {
        // Remove declarations that are re-defined again later.
        //
        // This could maybe result in unwanted behavior (because similar
        // properties typically exist for backwards compatibility), but for
        // signature purposes we can assume that the last declaration wins.
        if (node.nodes.length > 1) {
          let seen = new Set<string>()
          for (let i = node.nodes.length - 1; i >= 0; i--) {
            let child = node.nodes[i]
            if (child.kind !== 'declaration') continue
            if (child.value === undefined) continue

            if (seen.has(child.property)) {
              node.nodes.splice(i, 1)
            }
            seen.add(child.property)
          }
        }

        // Sort declarations alphabetically by property name
        node.nodes.sort((a, b) => {
          if (a.kind !== 'declaration') return 0
          if (b.kind !== 'declaration') return 0
          return a.property.localeCompare(b.property)
        })
      }
    },
  })

  return ast
}