Add completions for —value(…) and —modifier(…)

Author: thecrypticace

packages/tailwindcss-language-service/src/completionProvider.ts

@@ -7,6 +7,7 @@ import {
   type CompletionList,
   type Position,
   type CompletionContext,
+  InsertTextFormat,
 } from 'vscode-languageserver'
 import type { TextDocument } from 'vscode-languageserver-textdocument'
 import dlv from 'dlv'
@@ -18,7 +19,7 @@ import { findLast, matchClassAttributes } from './util/find'
 import { stringifyConfigValue, stringifyCss } from './util/stringify'
 import { stringifyScreen, Screen } from './util/screens'
 import isObject from './util/isObject'
-import braceLevel from './util/braceLevel'
+import { braceLevel, parenLevel } from './util/braceLevel'
 import * as emmetHelper from 'vscode-emmet-helper-bundled'
 import { isValidLocationForEmmetAbbreviation } from './util/isValidLocationForEmmetAbbreviation'
 import { isJsDoc, isJsxContext } from './util/js'
@@ -41,6 +42,8 @@ import { IS_SCRIPT_SOURCE, IS_TEMPLATE_SOURCE } from './metadata/extensions'
 import * as postcss from 'postcss'
 import { findFileDirective } from './completions/file-paths'
 import type { ThemeEntry } from './util/v4'
+import { posix } from 'node:path/win32'
+import { segment } from './util/segment'
 
 let isUtil = (className) =>
   Array.isArray(className.__info)
@@ -1097,6 +1100,219 @@ function provideCssHelperCompletions(
   )
 }
 
+function getCsstUtilityNameAtPosition(
+  state: State,
+  document: TextDocument,
+  position: Position,
+): { root: string; kind: 'static' | 'functional' } | null {
+  if (!isCssContext(state, document, position)) return null
+  if (!isInsideAtRule('utility', document, position)) return null
+
+  let text = document.getText({
+    start: { line: 0, character: 0 },
+    end: position,
+  })
+
+  // Make sure we're in a functional utility block
+  let block = text.lastIndexOf(`@utility`)
+  if (block === -1) return null
+
+  let curly = text.indexOf('{', block)
+  if (curly === -1) return null
+
+  let root = text.slice(block + 8, curly).trim()
+
+  if (root.length === 0) return null
+
+  if (root.endsWith('-*')) {
+    root = root.slice(0, -2)
+
+    if (root.length === 0) return null
+
+    return { root, kind: 'functional' }
+  }
+
+  return { root: root, kind: 'static' }
+}
+
+function provideUtilityFunctionCompletions(
+  state: State,
+  document: TextDocument,
+  position: Position,
+): CompletionList {
+  let utilityName = getCsstUtilityNameAtPosition(state, document, position)
+  if (!utilityName) return null
+
+  let text = document.getText({
+    start: { line: position.line, character: 0 },
+    end: position,
+  })
+
+  // Make sure we're in "value position"
+  // e.g. --foo: <cursor>
+  let pattern = /^[^:]+:[^;]*$/
+  if (!pattern.test(text)) return null
+
+  return withDefaults(
+    {
+      isIncomplete: false,
+      items: [
+        {
+          label: '--value()',
+          textEditText: '--value($1)',
+          sortText: '-00000',
+          insertTextFormat: InsertTextFormat.Snippet,
+          kind: CompletionItemKind.Function,
+          documentation: {
+            kind: 'markdown' as typeof MarkupKind.Markdown,
+            value: 'Reference a value based on the name of the utility. e.g. the `md` in `text-md`',
+          },
+          command: { command: 'editor.action.triggerSuggest', title: '' },
+        },
+        {
+          label: '--modifier()',
+          textEditText: '--modifier($1)',
+          sortText: '-00001',
+          insertTextFormat: InsertTextFormat.Snippet,
+          kind: CompletionItemKind.Function,
+          documentation: {
+            kind: 'markdown' as typeof MarkupKind.Markdown,
+            value: "Reference a value based on the utility's modifier. e.g. the `6` in `text-md/6`",
+          },
+        },
+      ],
+    },
+    {
+      data: {
+        ...(state.completionItemData ?? {}),
+      },
+      range: {
+        start: position,
+        end: position,
+      },
+    },
+    state.editor.capabilities.itemDefaults,
+  )
+}
+
+function provideUtilityFunctionArgumentCompletions(
+  state: State,
+  document: TextDocument,
+  position: Position,
+): CompletionList {
+  let utilityName = getCsstUtilityNameAtPosition(state, document, position)
+  if (!utilityName) return null
+
+  let text = document.getText({
+    start: { line: position.line, character: 0 },
+    end: position,
+  })
+
+  // Look to see if we're inside --value() or --modifier()
+  let fn = null
+  let fnStart = 0
+  let valueIdx = text.lastIndexOf('--value(')
+  let modifierIdx = text.lastIndexOf('--modifier(')
+  let fnIdx = Math.max(valueIdx, modifierIdx)
+  if (fnIdx === -1) return null
+
+  if (fnIdx === valueIdx) {
+    fn = '--value'
+  } else if (fnIdx === modifierIdx) {
+    fn = '--modifier'
+  }
+
+  fnStart = fnIdx + fn.length + 1
+
+  // Make sure we're actaully inside the function
+  if (parenLevel(text.slice(fnIdx)) === 0) return null
+
+  let items: CompletionItem[] = [
+    {
+      label: 'integer',
+      insertText: `integer`,
+      kind: CompletionItemKind.Constant,
+      documentation: {
+        kind: 'markdown' as typeof MarkupKind.Markdown,
+        value: 'Support integer values, e.g. `placeholder-6`',
+      },
+    },
+    {
+      label: 'number',
+      insertText: `number`,
+      kind: CompletionItemKind.Constant,
+      documentation: {
+        kind: 'markdown' as typeof MarkupKind.Markdown,
+        value:
+          'Support numeric values in increments of 0.25, e.g. `placeholder-6` and `placeholder-7.25`',
+      },
+    },
+    {
+      label: 'percentage',
+      insertText: `percentage`,
+      kind: CompletionItemKind.Constant,
+      documentation: {
+        kind: 'markdown' as typeof MarkupKind.Markdown,
+        value: 'Support integer percentage values, e.g. `placeholder-50%` and `placeholder-21%`',
+      },
+    },
+  ]
+
+  if (fn === '--value') {
+    items.push({
+      label: 'ratio',
+      insertText: `ratio`,
+      kind: CompletionItemKind.Constant,
+      documentation: {
+        kind: 'markdown' as typeof MarkupKind.Markdown,
+        value: 'Support fractions, e.g. `placeholder-1/5` and `placeholder-16/9`',
+      },
+    })
+  }
+
+  let parts = segment(text.slice(fnStart), ',').map((s) => s.trim())
+
+  // Only suggest at the start of the argument
+  if (parts.at(-1) !== '') return null
+
+  // Remove items that are already used
+  items = items.filter((item) => !parts.includes(item.label))
+
+  for (let [idx, item] of items.entries()) {
+    item.sortText = naturalExpand(idx, items.length)
+
+    if (typeof item.documentation === 'string') {
+      item.documentation = item.documentation.replace(/placeholder-/g, `${utilityName.root}-`)
+    } else {
+      item.documentation.value = item.documentation.value.replace(
+        /placeholder-/g,
+        `${utilityName.root}-`,
+      )
+    }
+
+    // TODO: Add a `, ` prefix to additional arguments automatically
+    // Doing so requires using `textEditText` + bookkeeping to make sure the
+    // output isn't mangled when the user has typed part of the argument
+  }
+
+  return withDefaults(
+    {
+      isIncomplete: true,
+      items,
+    },
+    {
+      data: {
+        ...(state.completionItemData ?? {}),
+      },
+      range: {
+        start: position,
+        end: position,
+      },
+    },
+    state.editor.capabilities.itemDefaults,
+  )
+}
+
 function provideTailwindDirectiveCompletions(
   state: State,
   document: TextDocument,
@@ -1871,6 +2087,8 @@ export async function doComplete(
   const result =
     (await provideClassNameCompletions(state, document, position, context)) ||
     (await provideThemeDirectiveCompletions(state, document, position)) ||
+    provideUtilityFunctionArgumentCompletions(state, document, position) ||
+    provideUtilityFunctionCompletions(state, document, position) ||
     provideCssHelperCompletions(state, document, position) ||
     provideCssDirectiveCompletions(state, document, position) ||
     provideScreenDirectiveCompletions(state, document, position) ||

packages/tailwindcss-language-service/src/util/braceLevel.ts

@@ -1,4 +1,4 @@
-export default function braceLevel(text: string) {
+export function braceLevel(text: string) {
   let count = 0
 
   for (let i = text.length - 1; i >= 0; i--) {
@@ -9,3 +9,15 @@ export default function braceLevel(text: string) {
 
   return count
 }
+
+export function parenLevel(text: string) {
+  let count = 0
+
+  for (let i = text.length - 1; i >= 0; i--) {
+    let char = text.charCodeAt(i)
+
+    count += Number(char === 0x28 /* ( */) - Number(char === 0x29 /* ) */)
+  }
+
+  return count
+}

packages/tailwindcss-language-service/src/util/segment.ts

@@ -0,0 +1,102 @@
+const BACKSLASH = 0x5c
+const OPEN_CURLY = 0x7b
+const CLOSE_CURLY = 0x7d
+const OPEN_PAREN = 0x28
+const CLOSE_PAREN = 0x29
+const OPEN_BRACKET = 0x5b
+const CLOSE_BRACKET = 0x5d
+const DOUBLE_QUOTE = 0x22
+const SINGLE_QUOTE = 0x27
+
+// This is a shared buffer that is used to keep track of the current nesting level
+// of parens, brackets, and braces. It is used to determine if a character is at
+// the top-level of a string. This is a performance optimization to avoid memory
+// allocations on every call to `segment`.
+const closingBracketStack = new Uint8Array(256)
+
+/**
+ * This splits a string on a top-level character.
+ *
+ * Regex doesn't support recursion (at least not the JS-flavored version),
+ * so we have to use a tiny state machine to keep track of paren placement.
+ *
+ * Expected behavior using commas:
+ * var(--a, 0 0 1px rgb(0, 0, 0)), 0 0 1px rgb(0, 0, 0)
+ *        ┬              ┬  ┬    ┬
+ *        x              x  x    ╰──────── Split because top-level
+ *        ╰──────────────┴──┴───────────── Ignored b/c inside >= 1 levels of parens
+ */
+export function segment(input: string, separator: string) {
+  // SAFETY: We can use an index into a shared buffer because this function is
+  // synchronous, non-recursive, and runs in a single-threaded environment.
+  let stackPos = 0
+  let parts: string[] = []
+  let lastPos = 0
+  let len = input.length
+
+  let separatorCode = separator.charCodeAt(0)
+
+  for (let idx = 0; idx < len; idx++) {
+    let char = input.charCodeAt(idx)
+
+    if (stackPos === 0 && char === separatorCode) {
+      parts.push(input.slice(lastPos, idx))
+      lastPos = idx + 1
+      continue
+    }
+
+    switch (char) {
+      case BACKSLASH:
+        // The next character is escaped, so we skip it.
+        idx += 1
+        break
+      // Strings should be handled as-is until the end of the string. No need to
+      // worry about balancing parens, brackets, or curlies inside a string.
+      case SINGLE_QUOTE:
+      case DOUBLE_QUOTE:
+        // Ensure we don't go out of bounds.
+        while (++idx < len) {
+          let nextChar = input.charCodeAt(idx)
+
+          // The next character is escaped, so we skip it.
+          if (nextChar === BACKSLASH) {
+            idx += 1
+            continue
+          }
+
+          if (nextChar === char) {
+            break
+          }
+        }
+        break
+      case OPEN_PAREN:
+        closingBracketStack[stackPos] = CLOSE_PAREN
+        stackPos++
+        break
+      case OPEN_BRACKET:
+        closingBracketStack[stackPos] = CLOSE_BRACKET
+        stackPos++
+        break
+      case OPEN_CURLY:
+        closingBracketStack[stackPos] = CLOSE_CURLY
+        stackPos++
+        break
+      case CLOSE_BRACKET:
+      case CLOSE_CURLY:
+      case CLOSE_PAREN:
+        if (stackPos > 0 && char === closingBracketStack[stackPos - 1]) {
+          // SAFETY: The buffer does not need to be mutated because the stack is
+          // only ever read from or written to its current position. Its current
+          // position is only ever incremented after writing to it. Meaning that
+          // the buffer can be dirty for the next use and still be correct since
+          // reading/writing always starts at position `0`.
+          stackPos--
+        }
+        break
+    }
+  }
+
+  parts.push(input.slice(lastPos))
+
+  return parts
+}