substituteFunctionsInValue() — tailwindcss Function Reference

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

Function typescript Oxide Extractor calls 4 called by 1

Entity Profile

Oxide→ Extractor→ substituteFunctionsInValue() — tailwindcss Function Reference

Dependency Diagram

graph TD
  a4ba0e6f_8062_6435_8f6d_7ec692b4801d["substituteFunctionsInValue()"]
  f6c14bbb_2e42_58cc_18f1_c89a243da9c0["canonicalize-candidates.ts"]
  a4ba0e6f_8062_6435_8f6d_7ec692b4801d -->|defined in| f6c14bbb_2e42_58cc_18f1_c89a243da9c0
  7f0ac26e_d200_2f14_4236_46ff9eed21ef["createConverterCache()"]
  7f0ac26e_d200_2f14_4236_46ff9eed21ef -->|calls| a4ba0e6f_8062_6435_8f6d_7ec692b4801d
  0e2c6f34_a0d7_e510_6033_2c569e871ee1["eventuallyUnquote()"]
  a4ba0e6f_8062_6435_8f6d_7ec692b4801d -->|calls| 0e2c6f34_a0d7_e510_6033_2c569e871ee1
  4982d9ce_98d4_85d9_44af_7cc47b93c482["walk()"]
  a4ba0e6f_8062_6435_8f6d_7ec692b4801d -->|calls| 4982d9ce_98d4_85d9_44af_7cc47b93c482
  9b49f3c6_0c8d_5c62_965c_30a1db6499f8["toCss()"]
  a4ba0e6f_8062_6435_8f6d_7ec692b4801d -->|calls| 9b49f3c6_0c8d_5c62_965c_30a1db6499f8
  117bca28_0677_ab3f_6eec_6019671b392d["parse()"]
  a4ba0e6f_8062_6435_8f6d_7ec692b4801d -->|calls| 117bca28_0677_ab3f_6eec_6019671b392d
  style a4ba0e6f_8062_6435_8f6d_7ec692b4801d fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/tailwindcss/src/canonicalize-candidates.ts lines 801–879

function substituteFunctionsInValue(
  ast: ValueParser.ValueAstNode[],
  handle: (value: string, fallback?: string) => string | null,
) {
  walk(ast, (node, ctx) => {
    if (node.kind === 'function' && node.value === 'theme') {
      if (node.nodes.length < 1) return

      // Ignore whitespace before the first argument
      if (node.nodes[0].kind === 'separator' && node.nodes[0].value.trim() === '') {
        node.nodes.shift()
      }

      let pathNode = node.nodes[0]
      if (pathNode.kind !== 'word') return

      let path = pathNode.value

      // For the theme function arguments, we require all separators to contain
      // comma (`,`), spaces alone should be merged into the previous word to
      // avoid splitting in this case:
      //
      // theme(--color-red-500 / 75%) theme(--color-red-500 / 75%, foo, bar)
      //
      // We only need to do this for the first node, as the fallback values are
      // passed through as-is.
      let skipUntilIndex = 1
      for (let i = skipUntilIndex; i < node.nodes.length; i++) {
        if (node.nodes[i].value.includes(',')) {
          break
        }
        path += ValueParser.toCss([node.nodes[i]])
        skipUntilIndex = i + 1
      }

      path = eventuallyUnquote(path)
      let fallbackValues = node.nodes.slice(skipUntilIndex + 1)

      let replacement =
        fallbackValues.length > 0 ? handle(path, ValueParser.toCss(fallbackValues)) : handle(path)
      if (replacement === null) return

      if (ctx.parent) {
        let idx = ctx.parent.nodes.indexOf(node) - 1
        while (idx !== -1) {
          let previous = ctx.parent.nodes[idx]
          // Skip the space separator
          if (previous.kind === 'separator' && previous.value.trim() === '') {
            idx -= 1
            continue
          }

          // If the previous node is a word and contains an operator, we need to
          // wrap the replacement in parentheses to make the output less
          // ambiguous.
          //
          // Input:
          // - `calc(100dvh-theme(spacing.2))`
          //
          // Output:
          // - `calc(100dvh-(--spacing(2)))`
          //
          // Not:
          // -`calc(100dvh---spacing(2))`
          //
          if (/^[-+*/]$/.test(previous.value.trim())) {
            replacement = `(${replacement})`
          }

          break
        }
      }

      return WalkAction.Replace(ValueParser.parse(replacement))
    }
  })

  return ValueParser.toCss(ast)
}