SFC theme integration: useTheme() + token string literals

[AlphaFoxz]

Summary

Add SFC compiler support for theme integration — two related features:

1. useTheme() reactive binding: returns a reactive ref to the current theme, so templates can bind theme.colors.surface etc. and re-render on theme switch.
2. Token string literals: template attributes like colorFg="text" should be compiled to colorThemed({token: 'text'}), reusing the existing TuiThemedColorRef runtime mechanism.

Expected API

<script setup>
const theme = useTheme()
</script>
<template>
  <Box :colorBg="theme.colors.surface">
    <Text colorFg="text">Hello</Text>
  </Box>
</template>

Implementation notes

• New runtime module packages/core/src/theme/use-theme.ts (does not currently exist) — returns a reactive theme ref bound to the global store.
• Compiler (packages/compiler/src) currently has zero recognition of useTheme or token string literals — both need codegen support.
• Token strings should resolve to TuiThemedColorRef via colorThemed({token: 'text'}), leveraging the existing runtime. Token validity should be checked at compile time against the known TuiThemeColors keys.
• colorFg="text" (static) and :colorFg="someRef" (dynamic) must remain distinguishable — only the static-string-literal case becomes a themed ref.

Context

Identified in the now-trimmed docs/theme-roadmap.md as the P3 (SFC integration) work item. The lower-priority P2 widget-level theme override is tracked separately in #42.

Affected packages: packages/core (new use-theme.ts runtime), packages/compiler (code generation)

---

概要

为 SFC 编译器增加主题集成支持 —— 两个相关特性:

1. useTheme() 响应式绑定:返回当前主题的响应式 ref,模板中可绑定 theme.colors.surface 等,主题切换时自动重渲染。
2. Token 字符串字面量:模板属性如 colorFg="text" 应被编译为 colorThemed({token: 'text'}),复用现有 TuiThemedColorRef 运行时机制。

期望 API

<script setup>
const theme = useTheme()
</script>
<template>
  <Box :colorBg="theme.colors.surface">
    <Text colorFg="text">Hello</Text>
  </Box>
</template>

实现要点

• 新增运行时模块 packages/core/src/theme/use-theme.ts(当前不存在)——返回绑定到全局 store 的响应式 theme ref。
• 编译器(packages/compiler/src)目前对 useTheme 和 token 字符串字面量零识别——两者都需要 codegen 支持。
• Token 字符串应通过 colorThemed({token: 'text'}) 解析为 TuiThemedColorRef,复用现有运行时机制。Token 合法性应在编译期对照已知 TuiThemeColors key 校验。
• colorFg="text"(静态)与 :colorFg="someRef"(动态)必须可区分——只有静态字符串字面量才转为 themed ref。

背景

此项在已精简的 docs/theme-roadmap.md 中识别为 P3(SFC 集成)工作项。优先级较低的 P2 widget 级主题覆盖在 #42 单独跟踪。

受影响包: packages/core(新增 use-theme.ts 运行时)、packages/compiler(代码生成)