@tamagui/language-service 0.0.0-bootstrap.0 → 3.0.0-beta.643.1

package/src/index.ts

@@ -0,0 +1,452 @@
+import { isAbsolute, resolve } from 'node:path'
+
+import type ts from 'typescript'
+import {
+  completionSortText,
+  createStyleTooling,
+  type SerializedConfigFile,
+  type StyleTooling,
+} from './core'
+import { resolveTamaguiHost } from './host'
+
+const completionSource = '@tamagui/language-service'
+const diagnosticCode = 78711
+const defaultConfigPath = '.tamagui/tamagui.config.json'
+const flatStyledModules: ReadonlySet<string> = new Set([
+  'tamagui',
+  'tamagui/unstyled',
+  '@tamagui/core',
+  '@tamagui/ui',
+  '@tamagui/web',
+])
+
+export interface TamaguiLanguageServicePluginConfig {
+  /** Path to the config JSON emitted by the Tamagui compiler. */
+  configPath?: string
+}
+
+type ImportedBindings = {
+  styled: ReadonlySet<string>
+}
+
+type LiteralSite = {
+  property: string
+  /** cooked value, identical to its authored source text */
+  value: string
+  /** file offset of the value's first character */
+  contentStart: number
+  literal: ts.StringLiteralLike
+}
+
+function loadTooling(
+  info: ts.server.PluginCreateInfo,
+  configPath: string
+): StyleTooling | null {
+  const contents = info.serverHost.readFile(configPath)
+  if (contents === undefined) return null
+  try {
+    return createStyleTooling(JSON.parse(contents) as SerializedConfigFile)
+  } catch {
+    return null
+  }
+}
+
+function findStringLiteralAtPosition(
+  typescript: typeof ts,
+  sourceFile: ts.SourceFile,
+  position: number
+): ts.StringLiteralLike | null {
+  let found: ts.StringLiteralLike | null = null
+  const visit = (node: ts.Node): void => {
+    if (position < node.getFullStart() || position > node.getEnd()) return
+    if (
+      typescript.isStringLiteralLike(node) &&
+      position >= node.getStart(sourceFile) + 1 &&
+      position <= node.getEnd() - 1
+    ) {
+      found = node
+      return
+    }
+    typescript.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+  return found
+}
+
+function importedBindings(
+  typescript: typeof ts,
+  sourceFile: ts.SourceFile
+): ImportedBindings {
+  const styled = new Set<string>()
+
+  for (const statement of sourceFile.statements) {
+    if (
+      !typescript.isImportDeclaration(statement) ||
+      !typescript.isStringLiteral(statement.moduleSpecifier)
+    ) {
+      continue
+    }
+    const source = statement.moduleSpecifier.text
+    if (!flatStyledModules.has(source)) continue
+    const bindings = statement.importClause?.namedBindings
+    if (!bindings) continue
+    if (typescript.isNamespaceImport(bindings)) continue
+    for (const element of bindings.elements) {
+      const imported = element.propertyName?.text || element.name.text
+      if (imported === 'styled') styled.add(element.name.text)
+    }
+  }
+
+  return { styled }
+}
+
+function propertyName(typescript: typeof ts, name: ts.PropertyName): string | null {
+  if (typescript.isIdentifier(name) || typescript.isStringLiteral(name)) {
+    return name.text
+  }
+  return null
+}
+
+function completionProperty(
+  typescript: typeof ts,
+  literal: ts.StringLiteralLike,
+  tooling: StyleTooling,
+  checker: ts.TypeChecker,
+  bindings: ImportedBindings
+): { property: string } | null {
+  let parent = literal.parent
+
+  if (typescript.isJsxExpression(parent)) parent = parent.parent
+  if (typescript.isJsxAttribute(parent)) {
+    if (!typescript.isIdentifier(parent.name)) return null
+    const property = parent.name.text
+    if (!tooling.styleProps.has(property)) return null
+    const opening = parent.parent.parent
+    if (!typescript.isJsxOpeningLikeElement(opening)) return null
+    const host = resolveTamaguiHost(checker, opening.tagName)
+    if (!host?.accepts(property)) return null
+    return { property }
+  }
+
+  if (!typescript.isPropertyAssignment(parent)) return null
+  const property = propertyName(typescript, parent.name)
+  if (!property || !tooling.styleProps.has(property)) return null
+
+  let current: ts.Node = parent
+  while (current.parent && !typescript.isCallExpression(current.parent)) {
+    current = current.parent
+  }
+  if (!current.parent || !typescript.isCallExpression(current.parent)) return null
+  const call = current.parent
+  if (
+    call.arguments[1] !== current ||
+    !typescript.isIdentifier(call.expression) ||
+    !bindings.styled.has(call.expression.text)
+  ) {
+    return null
+  }
+  const component = call.arguments[0]
+  const host = component && resolveTamaguiHost(checker, component)
+  if (!host?.accepts(property)) return null
+  return { property }
+}
+
+/**
+ * The literal as a style value site, or null when it is not one: wrong parent
+ * shape, not a style prop, not a tamagui host, or authored with escapes that
+ * cook differently than they read (TypeScript exposes cooked values but no
+ * cooked-to-source offset map, so exact-raw literals only).
+ */
+function siteForLiteral(
+  typescript: typeof ts,
+  sourceFile: ts.SourceFile,
+  literal: ts.StringLiteralLike,
+  tooling: StyleTooling,
+  checker: ts.TypeChecker,
+  bindings: ImportedBindings
+): LiteralSite | null {
+  const site = completionProperty(typescript, literal, tooling, checker, bindings)
+  if (!site) return null
+  const contentStart = literal.getStart(sourceFile) + 1
+  const contentEnd = literal.getEnd() - 1
+  const sourceInput = sourceFile.text.slice(contentStart, contentEnd)
+  if (literal.text !== sourceInput) return null
+  return { property: site.property, value: literal.text, contentStart, literal }
+}
+
+function collectLiteralSites(
+  typescript: typeof ts,
+  sourceFile: ts.SourceFile,
+  tooling: StyleTooling,
+  checker: ts.TypeChecker,
+  bindings: ImportedBindings
+): LiteralSite[] {
+  const sites: LiteralSite[] = []
+  const visit = (node: ts.Node): void => {
+    if (typescript.isStringLiteralLike(node)) {
+      const site = siteForLiteral(
+        typescript,
+        sourceFile,
+        node,
+        tooling,
+        checker,
+        bindings
+      )
+      if (site) sites.push(site)
+      return
+    }
+    typescript.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+  return sites
+}
+
+function copyLanguageService(service: ts.LanguageService): ts.LanguageService {
+  const proxy = Object.create(null) as ts.LanguageService
+  for (const key of Object.keys(service) as Array<keyof ts.LanguageService>) {
+    const value = service[key]
+    ;(proxy as unknown as Record<string, unknown>)[key] =
+      typeof value === 'function' ? value.bind(service) : value
+  }
+  return proxy
+}
+
+const init: ts.server.PluginModuleFactory = ({ typescript }) => ({
+  create(info) {
+    const pluginConfig = info.config as TamaguiLanguageServicePluginConfig | undefined
+    const configuredPath = pluginConfig?.configPath || defaultConfigPath
+    const configPath = isAbsolute(configuredPath)
+      ? configuredPath
+      : resolve(info.project.getCurrentDirectory(), configuredPath)
+    let tooling = loadTooling(info, configPath)
+    const watcher = info.serverHost.watchFile(configPath, () => {
+      tooling = loadTooling(info, configPath)
+    })
+
+    const proxy = copyLanguageService(info.languageService)
+    const baseCompletions = info.languageService.getCompletionsAtPosition.bind(
+      info.languageService
+    )
+    const baseDetails = info.languageService.getCompletionEntryDetails.bind(
+      info.languageService
+    )
+    const baseSemanticDiagnostics = info.languageService.getSemanticDiagnostics.bind(
+      info.languageService
+    )
+    const baseQuickInfo = info.languageService.getQuickInfoAtPosition.bind(
+      info.languageService
+    )
+    const baseDispose = info.languageService.dispose.bind(info.languageService)
+    const bindingsBySourceFile = new WeakMap<ts.SourceFile, ImportedBindings>()
+
+    const fileContext = (
+      fileName: string
+    ): {
+      sourceFile: ts.SourceFile
+      checker: ts.TypeChecker
+      bindings: ImportedBindings
+    } | null => {
+      const program = info.languageService.getProgram()
+      const sourceFile = program?.getSourceFile(fileName)
+      if (!program || !sourceFile) return null
+      let bindings = bindingsBySourceFile.get(sourceFile)
+      if (!bindings) {
+        bindings = importedBindings(typescript, sourceFile)
+        bindingsBySourceFile.set(sourceFile, bindings)
+      }
+      return { sourceFile, checker: program.getTypeChecker(), bindings }
+    }
+
+    proxy.getCompletionsAtPosition = (
+      fileName,
+      position,
+      options,
+      formattingSettings
+    ) => {
+      const getBaseCompletions = () =>
+        baseCompletions(fileName, position, options, formattingSettings)
+      if (!tooling) return getBaseCompletions()
+      const context = fileContext(fileName)
+      if (!context) return getBaseCompletions()
+      const { sourceFile, checker, bindings } = context
+      const literal = findStringLiteralAtPosition(typescript, sourceFile, position)
+      if (!literal) return getBaseCompletions()
+      const site = siteForLiteral(
+        typescript,
+        sourceFile,
+        literal,
+        tooling,
+        checker,
+        bindings
+      )
+      if (!site) return getBaseCompletions()
+
+      const cursorCompletions = tooling.completions(
+        site.property,
+        site.value,
+        position - site.contentStart
+      )
+      if (!cursorCompletions) return getBaseCompletions()
+      const replacementSpan = {
+        start: site.contentStart + cursorCompletions.replaceStart,
+        length: cursorCompletions.replaceLength,
+      }
+      const entries: ts.CompletionEntry[] = []
+      let contextualType: ts.Type | undefined
+      for (const completion of cursorCompletions.completions) {
+        const insertText = completion.insertText || completion.value
+        const modifierKind =
+          completion.kind === 'modifier'
+            ? tooling.modifierKind(completion.value)
+            : undefined
+        if (completion.kind === 'keyword') {
+          contextualType ||= checker.getContextualType(literal)
+          if (
+            !contextualType ||
+            !checker.isTypeAssignableTo(
+              checker.getStringLiteralType(insertText),
+              contextualType
+            )
+          ) {
+            continue
+          }
+        }
+        entries.push({
+          name: completion.value,
+          kind: typescript.ScriptElementKind.string,
+          kindModifiers: '',
+          sortText: completionSortText(completion, modifierKind),
+          insertText,
+          replacementSpan,
+          source: completionSource,
+          labelDetails: {
+            description: modifierKind
+              ? `Tamagui ${modifierKind} modifier`
+              : completion.kind === 'configured'
+                ? 'Tamagui configured value'
+                : 'Tamagui style keyword',
+          },
+        })
+      }
+      if (entries.length === 0) return getBaseCompletions()
+      return {
+        isGlobalCompletion: false,
+        isMemberCompletion: false,
+        isNewIdentifierLocation: true,
+        // A completion requested immediately after whitespace has an empty
+        // replacement span. Ask the editor to request again as the modifier
+        // prefix grows instead of dismissing suggestions when the cursor
+        // moves beyond that initial span.
+        isIncomplete: true,
+        entries,
+      }
+    }
+
+    proxy.getCompletionEntryDetails = (
+      fileName,
+      position,
+      entryName,
+      formatOptions,
+      source,
+      preferences,
+      data
+    ) => {
+      if (source === completionSource) {
+        return {
+          name: entryName,
+          kind: typescript.ScriptElementKind.string,
+          kindModifiers: '',
+          displayParts: [
+            {
+              text: entryName,
+              kind: 'stringLiteral',
+            },
+          ],
+          documentation: [
+            {
+              text: 'Resolved from the active Tamagui config.',
+              kind: 'text',
+            },
+          ],
+          tags: [],
+        }
+      }
+      return baseDetails(
+        fileName,
+        position,
+        entryName,
+        formatOptions,
+        source,
+        preferences,
+        data
+      )
+    }
+
+    proxy.getSemanticDiagnostics = (fileName) => {
+      const diagnostics = [...baseSemanticDiagnostics(fileName)]
+      if (!tooling) return diagnostics
+      const context = fileContext(fileName)
+      if (!context) return diagnostics
+      const { sourceFile, checker, bindings } = context
+      for (const site of collectLiteralSites(
+        typescript,
+        sourceFile,
+        tooling,
+        checker,
+        bindings
+      )) {
+        for (const diagnostic of tooling.diagnostics(site.property, site.value)) {
+          diagnostics.push({
+            file: sourceFile,
+            start: site.contentStart + diagnostic.start,
+            length: Math.max(1, diagnostic.end - diagnostic.start),
+            messageText: diagnostic.message,
+            category: typescript.DiagnosticCategory.Error,
+            code: diagnosticCode,
+            source: completionSource,
+          })
+        }
+      }
+      return diagnostics
+    }
+
+    proxy.getQuickInfoAtPosition = (fileName, position) => {
+      const getBaseQuickInfo = () => baseQuickInfo(fileName, position)
+      if (!tooling) return getBaseQuickInfo()
+      const context = fileContext(fileName)
+      if (!context) return getBaseQuickInfo()
+      const { sourceFile, checker, bindings } = context
+      const literal = findStringLiteralAtPosition(typescript, sourceFile, position)
+      if (!literal) return getBaseQuickInfo()
+      const site = siteForLiteral(
+        typescript,
+        sourceFile,
+        literal,
+        tooling,
+        checker,
+        bindings
+      )
+      if (!site) return getBaseQuickInfo()
+      const hover = tooling.hover(site.property, site.value, position - site.contentStart)
+      if (!hover) return getBaseQuickInfo()
+      return {
+        kind: typescript.ScriptElementKind.string,
+        kindModifiers: '',
+        textSpan: {
+          start: site.contentStart + hover.start,
+          length: hover.end - hover.start,
+        },
+        displayParts: [{ text: hover.text, kind: 'stringLiteral' }],
+        documentation: [{ text: hover.markdown, kind: 'text' }],
+      }
+    }
+
+    proxy.dispose = () => {
+      watcher.close()
+      baseDispose()
+    }
+    return proxy
+  },
+})
+
+export default init

package/types/check.d.ts

@@ -0,0 +1,31 @@
+import { type DocumentDiagnostic, type ExtractStyleSites } from "./document";
+export interface CheckStyleFilesOptions {
+	/** project root; file discovery and relative display paths anchor here */
+	root: string;
+	/** path to the compiler's config artifact; default `<root>/.tamagui/tamagui.config.json` */
+	configPath?: string;
+	/** explicit files to check instead of walking the root */
+	files?: readonly string[];
+}
+export interface CheckedFile {
+	/** root-relative display path */
+	file: string;
+	source: string;
+	diagnostics: readonly DocumentDiagnostic[];
+}
+export interface CheckStyleFilesResult {
+	files: readonly CheckedFile[];
+	checkedFileCount: number;
+	diagnosticCount: number;
+}
+export declare class MissingConfigArtifactError extends Error {
+	constructor(configPath: string);
+}
+export declare function createProjectExtractor(isStyleProp: (name: string) => boolean): ExtractStyleSites;
+export declare function checkStyleFiles(options: CheckStyleFilesOptions): CheckStyleFilesResult;
+/** human-readable report: one code frame per diagnostic, caret-underlined */
+export declare function formatCheckResults(result: CheckStyleFilesResult, options?: {
+	color?: boolean;
+}): string;
+
+//# sourceMappingURL=check.d.ts.map

package/types/check.d.ts.map

@@ -0,0 +1,11 @@
+{
+  "mappings": "AAcA,cAEO,yBACA,yBACA;AAgBP,iBAAiB,uBAAuB;;CAEtC;;CAEA;;CAEA;;AAGF,iBAAiB,YAAY;;CAE3B;CACA;CACA,sBAAsB;;AAGxB,iBAAiB,sBAAsB;CACrC,gBAAgB;CAChB;CACA;;AAGF,OAAO,cAAM,mCAAmC,MAAM;CACpD,YAAY;;AAoBd,OAAO,iBAAS,uBACd,cAAc,2BACb;AAIH,OAAO,iBAAS,gBAAgB,SAAS,yBAAyB;;AAoFlE,OAAO,iBAAS,mBACd,QAAQ,uBACR,UAAS;CAAE",
+  "names": [],
+  "sources": [
+    "src/check.ts"
+  ],
+  "version": 3,
+  "sourcesContent": [
+    "// The project checker behind `tamagui check`.\n//\n// Node-only entry: walks a project's source files, extracts every static flat\n// value site with the sucrase tokenizer, and reports the same diagnostics the\n// editor plugin and eslint rule produce, formatted as readable code frames.\n\nimport { readdirSync, readFileSync } from 'node:fs'\nimport { join, relative } from 'node:path'\n// deep paths, spelled down to the file: sucrase publishes no `exports` map, and\n// a bare `sucrase/dist/parser` is a directory import that ESM cannot resolve\nimport { parse } from 'sucrase/dist/parser/index.js'\nimport { TokenType } from 'sucrase/dist/parser/tokenizer/types.js'\n\nimport { createStyleTooling, type SerializedConfigFile } from './core'\nimport {\n  createDocumentStyleTooling,\n  type DocumentDiagnostic,\n  type ExtractStyleSites,\n} from './document'\nimport { createSucraseStyleSiteExtractor } from './extract-sucrase'\n\nconst sourceExtensions = /\\.(tsx|jsx)$/\nconst skippedDirectories = new Set([\n  'node_modules',\n  'dist',\n  'build',\n  'out',\n  'coverage',\n  '.git',\n  '.next',\n  '.expo',\n  '.tamagui',\n])\n\nexport interface CheckStyleFilesOptions {\n  /** project root; file discovery and relative display paths anchor here */\n  root: string\n  /** path to the compiler's config artifact; default `<root>/.tamagui/tamagui.config.json` */\n  configPath?: string\n  /** explicit files to check instead of walking the root */\n  files?: readonly string[]\n}\n\nexport interface CheckedFile {\n  /** root-relative display path */\n  file: string\n  source: string\n  diagnostics: readonly DocumentDiagnostic[]\n}\n\nexport interface CheckStyleFilesResult {\n  files: readonly CheckedFile[]\n  checkedFileCount: number\n  diagnosticCount: number\n}\n\nexport class MissingConfigArtifactError extends Error {\n  constructor(configPath: string) {\n    super(\n      `no Tamagui config artifact at ${configPath} — run your dev server or \\`tamagui generate\\` once so the compiler emits it`\n    )\n    this.name = 'MissingConfigArtifactError'\n  }\n}\n\nfunction walkSourceFiles(directory: string, results: string[]): void {\n  for (const entry of readdirSync(directory, { withFileTypes: true })) {\n    if (entry.isDirectory()) {\n      if (!skippedDirectories.has(entry.name) && !entry.name.startsWith('.')) {\n        walkSourceFiles(join(directory, entry.name), results)\n      }\n      continue\n    }\n    if (sourceExtensions.test(entry.name)) results.push(join(directory, entry.name))\n  }\n}\n\nexport function createProjectExtractor(\n  isStyleProp: (name: string) => boolean\n): ExtractStyleSites {\n  return createSucraseStyleSiteExtractor({ parse, TokenType }, { isStyleProp })\n}\n\nexport function checkStyleFiles(options: CheckStyleFilesOptions): CheckStyleFilesResult {\n  const configPath =\n    options.configPath ?? join(options.root, '.tamagui', 'tamagui.config.json')\n  let contents: string\n  try {\n    contents = readFileSync(configPath, 'utf8')\n  } catch {\n    throw new MissingConfigArtifactError(configPath)\n  }\n  const tooling = createStyleTooling(JSON.parse(contents) as SerializedConfigFile)\n  if (!tooling) throw new MissingConfigArtifactError(configPath)\n\n  const document = createDocumentStyleTooling(\n    tooling,\n    createProjectExtractor((name) => tooling.isStyleProp(name))\n  )\n\n  let files: string[]\n  if (options.files) {\n    files = [...options.files]\n  } else {\n    files = []\n    walkSourceFiles(options.root, files)\n    files.sort()\n  }\n\n  const checked: CheckedFile[] = []\n  let diagnosticCount = 0\n  for (const file of files) {\n    let source: string\n    try {\n      source = readFileSync(file, 'utf8')\n    } catch {\n      continue\n    }\n    let diagnostics: readonly DocumentDiagnostic[]\n    try {\n      diagnostics = document.diagnostics(source)\n    } catch {\n      // a file sucrase cannot parse is a syntax error the real compiler will\n      // report; the style checker stays quiet about it\n      continue\n    }\n    if (diagnostics.length === 0) continue\n    diagnosticCount += diagnostics.length\n    checked.push({ file: relative(options.root, file), source, diagnostics })\n  }\n\n  return { files: checked, checkedFileCount: files.length, diagnosticCount }\n}\n\nconst ansi = {\n  red: (text: string) => `\\x1b[31m${text}\\x1b[39m`,\n  dim: (text: string) => `\\x1b[2m${text}\\x1b[22m`,\n  bold: (text: string) => `\\x1b[1m${text}\\x1b[22m`,\n  cyan: (text: string) => `\\x1b[36m${text}\\x1b[39m`,\n}\nconst plain = {\n  red: (text: string) => text,\n  dim: (text: string) => text,\n  bold: (text: string) => text,\n  cyan: (text: string) => text,\n}\n\nfunction lineStarts(source: string): number[] {\n  const starts = [0]\n  for (let index = 0; index < source.length; index++) {\n    if (source.charCodeAt(index) === 10) starts.push(index + 1)\n  }\n  return starts\n}\n\nfunction positionOf(starts: number[], offset: number): { line: number; column: number } {\n  let low = 0\n  let high = starts.length - 1\n  while (low < high) {\n    const mid = (low + high + 1) >> 1\n    if (starts[mid] <= offset) low = mid\n    else high = mid - 1\n  }\n  return { line: low, column: offset - starts[low] }\n}\n\n/** human-readable report: one code frame per diagnostic, caret-underlined */\nexport function formatCheckResults(\n  result: CheckStyleFilesResult,\n  options: { color?: boolean } = {}\n): string {\n  const paint = options.color === false ? plain : ansi\n  const output: string[] = []\n\n  for (const checked of result.files) {\n    const starts = lineStarts(checked.source)\n    const lines = checked.source.split('\\n')\n    for (const diagnostic of checked.diagnostics) {\n      const start = positionOf(starts, diagnostic.start)\n      const end = positionOf(starts, diagnostic.end)\n      output.push(\n        `${paint.bold(checked.file)}${paint.dim(`:${start.line + 1}:${start.column + 1}`)} ${paint.red('error')} ${diagnostic.message}`\n      )\n      const line = lines[start.line] ?? ''\n      const gutter = String(start.line + 1)\n      output.push(`  ${paint.dim(`${gutter} │`)} ${line}`)\n      const underlineLength =\n        end.line === start.line\n          ? Math.max(1, end.column - start.column)\n          : Math.max(1, line.length - start.column)\n      output.push(\n        `  ${paint.dim(`${' '.repeat(gutter.length)} │`)} ${' '.repeat(start.column)}${paint.red('^'.repeat(underlineLength))}`\n      )\n      output.push('')\n    }\n  }\n\n  const summary =\n    result.diagnosticCount === 0\n      ? `${paint.bold('✓')} ${result.checkedFileCount} files, no flat value problems`\n      : `${paint.red(paint.bold(`✗ ${result.diagnosticCount} problem${result.diagnosticCount === 1 ? '' : 's'}`))} in ${result.files.length} file${result.files.length === 1 ? '' : 's'} ${paint.dim(`(${result.checkedFileCount} checked)`)}`\n  output.push(summary)\n  return output.join('\\n')\n}\n"
+  ]
+}

package/types/core.d.ts

@@ -0,0 +1,68 @@
+import { type DiagnoseStyleValueOptions, type ModifierKind, type SerializedGrammarSourceConfig, type StyleValueAnnotation, type StyleValueCompletion, type StyleValueCursorCompletions, type StyleValueDiagnostic } from "@tamagui/style-grammar/tooling";
+export type { StyleValueAnnotation, StyleValueCompletion, StyleValueCursorCompletions, StyleValueDiagnostic };
+/** the shape of the JSON artifact the Tamagui compiler writes */
+export interface SerializedConfigFile {
+	tamaguiConfig?: SerializedGrammarSourceConfig;
+	tamaguiConfigMetadata?: unknown;
+}
+export interface RgbaColor {
+	r: number;
+	g: number;
+	b: number;
+	a: number;
+}
+export interface StyleValueColor {
+	/** character span within the authored value */
+	start: number;
+	end: number;
+	text: string;
+	color: RgbaColor;
+	/** the theme the preview value came from, when theme-resolved */
+	theme?: string;
+}
+export interface StyleValueHover {
+	/** character span within the authored value */
+	start: number;
+	end: number;
+	text: string;
+	/** markdown suitable for an editor hover */
+	markdown: string;
+	/** a representative color for colorish targets */
+	color?: RgbaColor;
+}
+/**
+* The one sort key every host uses for completion entries, so ordering does
+* not drift between tsserver, LSP, and in-browser consumers: states first in
+* interaction order, then groups, media, containers, themes, platforms, then
+* configured values, then keywords.
+*/
+export declare function completionSortText(completion: StyleValueCompletion, modifierKind: ModifierKind | undefined): string;
+export interface StyleTooling {
+	/** every prop name treated as a flat style value site */
+	styleProps: ReadonlySet<string>;
+	/** engine options, for hosts that call @tamagui/style-grammar directly */
+	engine: DiagnoseStyleValueOptions;
+	isStyleProp(name: string): boolean;
+	/** the longhand a prop resolves to through the configured shorthands */
+	targetProperty(name: string): string;
+	/**
+	* cursor completions for one value slot, or null when the property takes no
+	* flat program (unknown props, legacy part props)
+	*/
+	completions(property: string, value: string, cursor: number): StyleValueCursorCompletions | null;
+	/** the complete static verdict for one authored value */
+	diagnostics(property: string, value: string): readonly StyleValueDiagnostic[];
+	/** classified spans: modifiers, tokens, keywords, literals */
+	annotations(property: string, value: string): readonly StyleValueAnnotation[];
+	/** hover content for the annotation under `offset`, or null */
+	hover(property: string, value: string, offset: number): StyleValueHover | null;
+	/** every span that resolves to a presentable color */
+	colors(property: string, value: string): readonly StyleValueColor[];
+	/** the modifier kind of a registered modifier name */
+	modifierKind(name: string): ModifierKind | undefined;
+	/** root theme names, preview themes first */
+	previewThemes: readonly string[];
+}
+export declare function createStyleTooling(file: SerializedConfigFile): StyleTooling | null;
+
+//# sourceMappingURL=core.d.ts.map

package/types/core.d.ts.map

@@ -0,0 +1,11 @@
+{
+  "mappings": "AAaA,cAUO,gCACA,mBACA,oCACA,2BACA,2BACA,kCACA,4BACA;AAEP,cACE,sBACA,sBACA,6BACA;;AAIF,iBAAiB,qBAAqB;CACpC,gBAAgB;CAChB;;AAGF,iBAAiB,UAAU;CACzB;CACA;CACA;CACA;;AAGF,iBAAiB,gBAAgB;;CAE/B;CACA;CACA;CACA,OAAO;;CAEP;;AAGF,iBAAiB,gBAAgB;;CAE/B;CACA;CACA;;CAEA;;CAEA,QAAQ;;;;;;;;AA+BV,OAAO,iBAAS,mBACd,YAAY,sBACZ,cAAc;AA6BhB,iBAAiB,aAAa;;CAE5B,YAAY;;CAEZ,QAAQ;CACR,YAAY;;CAEZ,eAAe;;;;;CAKf,YACE,kBACA,eACA,iBACC;;CAEH,YAAY,kBAAkB,yBAAyB;;CAEvD,YAAY,kBAAkB,yBAAyB;;CAEvD,MAAM,kBAAkB,eAAe,iBAAiB;;CAExD,OAAO,kBAAkB,yBAAyB;;CAElD,aAAa,eAAe;;CAE5B;;AAGF,OAAO,iBAAS,mBAAmB,MAAM,uBAAuB",
+  "names": [],
+  "sources": [
+    "src/core.ts"
+  ],
+  "version": 3,
+  "sourcesContent": [
+    "// The standalone Tamagui style tooling core.\n//\n// Browser-safe by contract: no node imports, no typescript imports. Everything\n// here works from the serialized config JSON the Tamagui compiler emits\n// (`.tamagui/tamagui.config.json`), so the same engine powers the tsserver\n// plugin, the VS Code extension, the CLI checker, and in-browser IDEs.\n//\n// The @tamagui/style-grammar engine owns candidate meaning; this module adds\n// the two things the engine's config view deliberately drops — token and theme\n// VALUES — and projects everything into editor-shaped results: completions,\n// diagnostics, hover, and color swatches.\n\nimport { normalizeCSSColor, rgba } from '@tamagui/normalize-css-color'\nimport {\n  annotateStyleValue,\n  completeStyleValueAtCursor,\n  createCandidatePropertyVocabulary,\n  createGrammarConfigViewFromSerializedConfig,\n  createModifierRegistry,\n  createStylePropSet,\n  diagnoseStyleValueProgram,\n  programEligibility,\n  stateModifierNames,\n  type DiagnoseStyleValueOptions,\n  type ModifierKind,\n  type SerializedGrammarSourceConfig,\n  type StyleValueAnnotation,\n  type StyleValueCompletion,\n  type StyleValueCursorCompletions,\n  type StyleValueDiagnostic,\n} from '@tamagui/style-grammar/tooling'\n\nexport type {\n  StyleValueAnnotation,\n  StyleValueCompletion,\n  StyleValueCursorCompletions,\n  StyleValueDiagnostic,\n}\n\n/** the shape of the JSON artifact the Tamagui compiler writes */\nexport interface SerializedConfigFile {\n  tamaguiConfig?: SerializedGrammarSourceConfig\n  tamaguiConfigMetadata?: unknown\n}\n\nexport interface RgbaColor {\n  r: number\n  g: number\n  b: number\n  a: number\n}\n\nexport interface StyleValueColor {\n  /** character span within the authored value */\n  start: number\n  end: number\n  text: string\n  color: RgbaColor\n  /** the theme the preview value came from, when theme-resolved */\n  theme?: string\n}\n\nexport interface StyleValueHover {\n  /** character span within the authored value */\n  start: number\n  end: number\n  text: string\n  /** markdown suitable for an editor hover */\n  markdown: string\n  /** a representative color for colorish targets */\n  color?: RgbaColor\n}\n\nconst modifierKindLabel: Readonly<Record<ModifierKind, string>> = {\n  state: 'state modifier',\n  media: 'media modifier',\n  theme: 'theme modifier',\n  platform: 'platform modifier',\n  group: 'group modifier',\n  container: 'container modifier',\n}\n\nconst modifierKindSort: Readonly<Record<ModifierKind, string>> = {\n  state: '00',\n  group: '01',\n  media: '02',\n  container: '03',\n  theme: '04',\n  platform: '05',\n}\n\nconst stateModifierSort = new Map(\n  stateModifierNames.map((name, index) => [name, index] as const)\n)\n\n/**\n * The one sort key every host uses for completion entries, so ordering does\n * not drift between tsserver, LSP, and in-browser consumers: states first in\n * interaction order, then groups, media, containers, themes, platforms, then\n * configured values, then keywords.\n */\nexport function completionSortText(\n  completion: StyleValueCompletion,\n  modifierKind: ModifierKind | undefined\n): string {\n  if (modifierKind) {\n    const stateOrder =\n      modifierKind === 'state'\n        ? `${String(stateModifierSort.get(completion.value) ?? 999).padStart(3, '0')}:`\n        : ''\n    return `${modifierKindSort[modifierKind]}:${stateOrder}${completion.value}`\n  }\n  return `${completion.kind === 'configured' ? '10' : '11'}:${completion.value}`\n}\n\n/** unwraps a compiler-serialized token variable to its raw value */\nfunction tokenValue(entry: unknown): unknown {\n  if (entry && typeof entry === 'object' && 'val' in entry) {\n    return (entry as { val: unknown }).val\n  }\n  return entry\n}\n\nfunction parseColor(value: unknown, opacity?: number): RgbaColor | null {\n  if (typeof value !== 'string') return null\n  const normalized = normalizeCSSColor(value)\n  if (normalized === null) return null\n  const color = rgba(normalized)\n  if (opacity !== undefined) color.a = color.a * (opacity / 100)\n  return color\n}\n\nexport interface StyleTooling {\n  /** every prop name treated as a flat style value site */\n  styleProps: ReadonlySet<string>\n  /** engine options, for hosts that call @tamagui/style-grammar directly */\n  engine: DiagnoseStyleValueOptions\n  isStyleProp(name: string): boolean\n  /** the longhand a prop resolves to through the configured shorthands */\n  targetProperty(name: string): string\n  /**\n   * cursor completions for one value slot, or null when the property takes no\n   * flat program (unknown props, legacy part props)\n   */\n  completions(\n    property: string,\n    value: string,\n    cursor: number\n  ): StyleValueCursorCompletions | null\n  /** the complete static verdict for one authored value */\n  diagnostics(property: string, value: string): readonly StyleValueDiagnostic[]\n  /** classified spans: modifiers, tokens, keywords, literals */\n  annotations(property: string, value: string): readonly StyleValueAnnotation[]\n  /** hover content for the annotation under `offset`, or null */\n  hover(property: string, value: string, offset: number): StyleValueHover | null\n  /** every span that resolves to a presentable color */\n  colors(property: string, value: string): readonly StyleValueColor[]\n  /** the modifier kind of a registered modifier name */\n  modifierKind(name: string): ModifierKind | undefined\n  /** root theme names, preview themes first */\n  previewThemes: readonly string[]\n}\n\nexport function createStyleTooling(file: SerializedConfigFile): StyleTooling | null {\n  const serialized = file.tamaguiConfig\n  if (!serialized) return null\n\n  const config = createGrammarConfigViewFromSerializedConfig(\n    serialized,\n    file.tamaguiConfigMetadata\n  )\n  const registry = createModifierRegistry(config).registry\n  const candidates = createCandidatePropertyVocabulary(config)\n  const engine: DiagnoseStyleValueOptions = { config, registry, candidates }\n  const styleProps = createStylePropSet(config)\n\n  // themes and tokens keep their VALUES here; the grammar view keeps names only\n  const themes = (serialized.themes || {}) as Readonly<\n    Record<string, Readonly<Record<string, unknown>> | undefined>\n  >\n  const rootThemes = Object.keys(themes).filter((name) => !name.includes('_'))\n  const previewThemes = [\n    ...['light', 'dark'].filter((name) => rootThemes.includes(name)),\n    ...rootThemes.filter((name) => name !== 'light' && name !== 'dark'),\n  ]\n  const tokens = (serialized.tokens || {}) as Readonly<\n    Record<string, Readonly<Record<string, unknown>> | undefined>\n  >\n  const media = (serialized.media || {}) as Readonly<Record<string, unknown>>\n\n  const targetProperty = (name: string): string => config.shorthands?.[name] || name\n\n  const themeValue = (name: string): { theme: string; value: unknown } | null => {\n    for (const theme of previewThemes) {\n      const value = themes[theme]?.[name]\n      if (value !== undefined) return { theme, value }\n    }\n    return null\n  }\n\n  const annotationColor = (\n    annotation: StyleValueAnnotation\n  ): { color: RgbaColor; theme?: string } | null => {\n    if (annotation.kind === 'token' || annotation.kind === 'identifier') {\n      const name =\n        annotation.opacity !== undefined\n          ? annotation.text.slice(0, annotation.text.lastIndexOf('/'))\n          : annotation.text\n      if (annotation.tokenCategory === 'color') {\n        const themed = themeValue(name)\n        if (themed) {\n          const color = parseColor(themed.value, annotation.opacity)\n          return color ? { color, theme: themed.theme } : null\n        }\n        const color = parseColor(tokenValue(tokens.color?.[name]), annotation.opacity)\n        return color ? { color } : null\n      }\n      if (annotation.kind === 'identifier') {\n        // literal CSS colors: hex, rgb()/hsl() never annotate (functions are\n        // skipped), but hex runs and named colors do\n        const color = parseColor(name)\n        return color ? { color } : null\n      }\n      return null\n    }\n    if (annotation.kind === 'keyword' && annotation.text === 'transparent') {\n      return { color: { r: 0, g: 0, b: 0, a: 0 } }\n    }\n    return null\n  }\n\n  const annotations = (property: string, value: string) =>\n    annotateStyleValue(property, value, engine)\n\n  const formatRgba = (color: RgbaColor): string =>\n    color.a === 1\n      ? `rgb(${color.r}, ${color.g}, ${color.b})`\n      : `rgba(${color.r}, ${color.g}, ${color.b}, ${Number(color.a.toFixed(3))})`\n\n  return {\n    styleProps,\n    engine,\n    previewThemes,\n    isStyleProp: (name) => styleProps.has(name),\n    targetProperty,\n    modifierKind: (name) => registry.get(name),\n\n    completions(property, value, cursor) {\n      const target = targetProperty(property)\n      if (programEligibility(target) === 'legacy-part') return null\n      if (!styleProps.has(property)) return null\n      return completeStyleValueAtCursor(property, value, cursor, engine)\n    },\n\n    diagnostics(property, value) {\n      if (!styleProps.has(property)) return []\n      return diagnoseStyleValueProgram(property, value, engine)\n    },\n\n    annotations,\n\n    colors(property, value) {\n      if (!styleProps.has(property)) return []\n      const results: StyleValueColor[] = []\n      for (const annotation of annotations(property, value)) {\n        const resolved = annotationColor(annotation)\n        if (!resolved) continue\n        results.push({\n          start: annotation.start,\n          end: annotation.end,\n          text: annotation.text,\n          color: resolved.color,\n          ...(resolved.theme !== undefined && { theme: resolved.theme }),\n        })\n      }\n      return results\n    },\n\n    hover(property, value, offset) {\n      if (!styleProps.has(property)) return null\n      const annotation = annotations(property, value).find(\n        (entry) => offset >= entry.start && offset <= entry.end\n      )\n      if (!annotation) return null\n\n      const lines: string[] = []\n      let color: RgbaColor | undefined\n\n      if (annotation.kind === 'modifier' && annotation.modifierKind) {\n        lines.push(\n          `**${annotation.text}** · Tamagui ${modifierKindLabel[annotation.modifierKind]}`\n        )\n        if (annotation.modifierKind === 'media') {\n          const query = media[annotation.text]\n          if (query !== undefined) {\n            lines.push('```json\\n' + JSON.stringify(query) + '\\n```')\n          }\n        }\n      } else if (annotation.kind === 'token') {\n        const name =\n          annotation.opacity !== undefined\n            ? annotation.text.slice(0, annotation.text.lastIndexOf('/'))\n            : annotation.text\n        if (annotation.tokenCategory === 'color') {\n          lines.push(`**${name}** · Tamagui color`)\n          let shown = 0\n          for (const theme of previewThemes) {\n            const value = themes[theme]?.[name]\n            if (value === undefined || shown >= 4) continue\n            shown++\n            lines.push(`- ${theme}: \\`${String(value)}\\``)\n          }\n          if (shown === 0) {\n            const value = tokenValue(tokens.color?.[name])\n            if (value !== undefined) lines.push(`- \\`${String(value)}\\``)\n          }\n          if (annotation.opacity !== undefined) {\n            lines.push(`- opacity: ${annotation.opacity}%`)\n          }\n        } else {\n          const value = tokenValue(tokens[annotation.tokenCategory || '']?.[name])\n          lines.push(\n            `**${name}** · Tamagui ${annotation.tokenCategory} token` +\n              (value !== undefined ? ` = \\`${String(value)}\\`` : '')\n          )\n        }\n        const resolved = annotationColor(annotation)\n        if (resolved) {\n          color = resolved.color\n          lines.push(`- resolves: \\`${formatRgba(resolved.color)}\\``)\n        }\n      } else if (annotation.kind === 'keyword') {\n        lines.push(\n          `**${annotation.text}** · CSS keyword` +\n            (annotation.property ? ` for \\`${annotation.property}\\`` : '')\n        )\n      } else {\n        const resolved = annotationColor(annotation)\n        if (!resolved) return null\n        color = resolved.color\n        lines.push(\n          `**${annotation.text}** · CSS color = \\`${formatRgba(resolved.color)}\\``\n        )\n      }\n\n      return {\n        start: annotation.start,\n        end: annotation.end,\n        text: annotation.text,\n        markdown: lines.join('\\n\\n'),\n        ...(color !== undefined && { color }),\n      }\n    },\n  }\n}\n"
+  ]
+}

package/types/document.d.ts

@@ -0,0 +1,42 @@
+import type { StyleTooling, StyleValueColor, StyleValueDiagnostic, StyleValueHover } from "./core";
+import type { StyleValueCursorCompletions } from "./core";
+/** one static string style value in a source file */
+export interface StyleSite {
+	/** the authored prop name (`bg`, `padding`) */
+	property: string;
+	/** the cooked string value */
+	value: string;
+	/** file offset of the value's first character (inside the quotes) */
+	start: number;
+	/** file offset just past the value's last character */
+	end: number;
+	/** how the site was authored, for hosts that filter */
+	kind: "jsx-attribute" | "styled-property";
+}
+export type ExtractStyleSites = (source: string, fileName?: string) => readonly StyleSite[];
+export interface DocumentDiagnostic extends StyleValueDiagnostic {
+	site: StyleSite;
+}
+export interface DocumentColor extends StyleValueColor {
+	site: StyleSite;
+}
+export interface DocumentHover extends StyleValueHover {
+	site: StyleSite;
+}
+export interface DocumentCompletions extends StyleValueCursorCompletions {
+	site: StyleSite;
+}
+export interface DocumentStyleTooling {
+	sites(source: string, fileName?: string): readonly StyleSite[];
+	/** completions at a file offset, spans mapped to file offsets */
+	completionsAt(source: string, offset: number, fileName?: string): DocumentCompletions | null;
+	/** every diagnostic in the file, spans mapped to file offsets */
+	diagnostics(source: string, fileName?: string): readonly DocumentDiagnostic[];
+	/** hover at a file offset, span mapped to file offsets */
+	hoverAt(source: string, offset: number, fileName?: string): DocumentHover | null;
+	/** every color swatch in the file, spans mapped to file offsets */
+	colors(source: string, fileName?: string): readonly DocumentColor[];
+}
+export declare function createDocumentStyleTooling(tooling: StyleTooling, extract: ExtractStyleSites): DocumentStyleTooling;
+
+//# sourceMappingURL=document.d.ts.map

package/types/document.d.ts.map

@@ -0,0 +1,11 @@
+{
+  "mappings": "AAUA,cACE,cACA,iBACA,sBACA,uBACK;AACP,cAAc,mCAAmC;;AAGjD,iBAAiB,UAAU;;CAEzB;;CAEA;;CAEA;;CAEA;;CAEA,MAAM,kBAAkB;;AAG1B,YAAY,qBACV,gBACA,+BACY;AAEd,iBAAiB,2BAA2B,qBAAqB;CAC/D,MAAM;;AAGR,iBAAiB,sBAAsB,gBAAgB;CACrD,MAAM;;AAGR,iBAAiB,sBAAsB,gBAAgB;CACrD,MAAM;;AAGR,iBAAiB,4BAA4B,4BAA4B;CACvE,MAAM;;AAGR,iBAAiB,qBAAqB;CACpC,MAAM,gBAAgB,6BAA6B;;CAEnD,cACE,gBACA,gBACA,oBACC;;CAEH,YAAY,gBAAgB,6BAA6B;;CAEzD,QAAQ,gBAAgB,gBAAgB,oBAAoB;;CAE5D,OAAO,gBAAgB,6BAA6B;;AAGtD,OAAO,iBAAS,2BACd,SAAS,cACT,SAAS,oBACR",
+  "names": [],
+  "sources": [
+    "src/document.ts"
+  ],
+  "version": 3,
+  "sourcesContent": [
+    "// Document-level orchestration: an extractor locates the style value sites in\n// one source file, the core answers inside each site, and this module joins\n// the two so every host (browser IDE, LSP wrapper, CLI checker) gets\n// file-offset results from one code path.\n//\n// Extractors are pluggable because hosts already own a parse: the tsserver\n// plugin walks TypeScript's AST, the eslint rule walks ESTree, soot's bundler\n// holds sucrase tokens. Each adapter reduces its tree to the same StyleSite\n// contract; nothing downstream re-parses.\n\nimport type {\n  StyleTooling,\n  StyleValueColor,\n  StyleValueDiagnostic,\n  StyleValueHover,\n} from './core'\nimport type { StyleValueCursorCompletions } from './core'\n\n/** one static string style value in a source file */\nexport interface StyleSite {\n  /** the authored prop name (`bg`, `padding`) */\n  property: string\n  /** the cooked string value */\n  value: string\n  /** file offset of the value's first character (inside the quotes) */\n  start: number\n  /** file offset just past the value's last character */\n  end: number\n  /** how the site was authored, for hosts that filter */\n  kind: 'jsx-attribute' | 'styled-property'\n}\n\nexport type ExtractStyleSites = (\n  source: string,\n  fileName?: string\n) => readonly StyleSite[]\n\nexport interface DocumentDiagnostic extends StyleValueDiagnostic {\n  site: StyleSite\n}\n\nexport interface DocumentColor extends StyleValueColor {\n  site: StyleSite\n}\n\nexport interface DocumentHover extends StyleValueHover {\n  site: StyleSite\n}\n\nexport interface DocumentCompletions extends StyleValueCursorCompletions {\n  site: StyleSite\n}\n\nexport interface DocumentStyleTooling {\n  sites(source: string, fileName?: string): readonly StyleSite[]\n  /** completions at a file offset, spans mapped to file offsets */\n  completionsAt(\n    source: string,\n    offset: number,\n    fileName?: string\n  ): DocumentCompletions | null\n  /** every diagnostic in the file, spans mapped to file offsets */\n  diagnostics(source: string, fileName?: string): readonly DocumentDiagnostic[]\n  /** hover at a file offset, span mapped to file offsets */\n  hoverAt(source: string, offset: number, fileName?: string): DocumentHover | null\n  /** every color swatch in the file, spans mapped to file offsets */\n  colors(source: string, fileName?: string): readonly DocumentColor[]\n}\n\nexport function createDocumentStyleTooling(\n  tooling: StyleTooling,\n  extract: ExtractStyleSites\n): DocumentStyleTooling {\n  const siteAt = (sites: readonly StyleSite[], offset: number): StyleSite | undefined =>\n    sites.find((site) => offset >= site.start && offset <= site.end)\n\n  return {\n    sites: (source, fileName) => extract(source, fileName),\n\n    completionsAt(source, offset, fileName) {\n      const site = siteAt(extract(source, fileName), offset)\n      if (!site) return null\n      const completions = tooling.completions(\n        site.property,\n        site.value,\n        offset - site.start\n      )\n      if (!completions) return null\n      return {\n        ...completions,\n        replaceStart: site.start + completions.replaceStart,\n        site,\n      }\n    },\n\n    diagnostics(source, fileName) {\n      const results: DocumentDiagnostic[] = []\n      for (const site of extract(source, fileName)) {\n        for (const diagnostic of tooling.diagnostics(site.property, site.value)) {\n          results.push({\n            ...diagnostic,\n            index: site.start + diagnostic.index,\n            start: site.start + diagnostic.start,\n            end: site.start + diagnostic.end,\n            site,\n          })\n        }\n      }\n      return results\n    },\n\n    hoverAt(source, offset, fileName) {\n      const site = siteAt(extract(source, fileName), offset)\n      if (!site) return null\n      const hover = tooling.hover(site.property, site.value, offset - site.start)\n      if (!hover) return null\n      return {\n        ...hover,\n        start: site.start + hover.start,\n        end: site.start + hover.end,\n        site,\n      }\n    },\n\n    colors(source, fileName) {\n      const results: DocumentColor[] = []\n      for (const site of extract(source, fileName)) {\n        for (const color of tooling.colors(site.property, site.value)) {\n          results.push({\n            ...color,\n            start: site.start + color.start,\n            end: site.start + color.end,\n            site,\n          })\n        }\n      }\n      return results\n    },\n  }\n}\n"
+  ]
+}