@363045841yyt/klinechart-core 0.7.6 → 0.7.7

package/src/tokens/__tests__/themeToCssVars.test.ts

@@ -0,0 +1,175 @@
+/**
+ * Tests for `themeToCssVars` / `toCssDeclarationBlock`.
+ *
+ * Acceptance criteria:
+ *   1. Every theme key (colors × 32 + palette × 10 + spacing × 9
+ *      + typography × 9 + motion × 5 = 65) maps to a CSS variable.
+ *   2. Variable names follow `--klc-{family}-{kebab-key}` exactly.
+ *   3. Camel→kebab transform is correct on edge cases (single-letter,
+ *      already-kebab, trailing digits).
+ *   4. Custom prefix is honoured.
+ *   5. Prefix without `--` throws (misuse caught early).
+ *   6. mergeTheme overrides surface in the emit output.
+ *   7. toCssDeclarationBlock produces parseable CSS.
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import {
+    lightTheme,
+    darkTheme,
+    mergeTheme,
+} from '..'
+import { camelToKebab, themeToCssVars, toCssDeclarationBlock } from '../themeToCssVars'
+
+describe('camelToKebab', () => {
+    it.each([
+        ['candleUpBody', 'candle-up-body'],
+        ['fontWeightRegular', 'font-weight-regular'],
+        ['i1', 'i1'],
+        ['i10', 'i10'],
+        ['background', 'background'],
+        ['durationFast', 'duration-fast'],
+        ['fontFamilyMono', 'font-family-mono'],
+    ])('%s → %s', (input, expected) => {
+        expect(camelToKebab(input)).toBe(expected)
+    })
+})
+
+function countColorLeaves(c: Record<string, unknown>): number {
+    let count = 0
+    for (const v of Object.values(c)) {
+        if (v !== null && typeof v === 'object') {
+            count += countColorLeaves(v as Record<string, unknown>)
+        } else {
+            count++
+        }
+    }
+    return count
+}
+
+describe('themeToCssVars — coverage', () => {
+    it('emits the expected number of variables for lightTheme', () => {
+        const vars = themeToCssVars(lightTheme)
+        const expectedCount =
+            countColorLeaves(lightTheme.colors as unknown as Record<string, unknown>) +
+            Object.keys(lightTheme.spacing).length +
+            Object.keys(lightTheme.typography).length +
+            Object.keys(lightTheme.motion).length
+        expect(Object.keys(vars)).toHaveLength(expectedCount)
+    })
+
+    it('every var name starts with --klc- by default', () => {
+        const vars = themeToCssVars(lightTheme)
+        for (const k of Object.keys(vars)) {
+            expect(k.startsWith('--klc-')).toBe(true)
+        }
+    })
+
+    it('every var value is a non-empty string', () => {
+        const vars = themeToCssVars(lightTheme)
+        for (const v of Object.values(vars)) {
+            expect(typeof v).toBe('string')
+            expect(v.length).toBeGreaterThan(0)
+        }
+    })
+})
+
+describe('themeToCssVars — naming', () => {
+    it('colors.background → --klc-color-background', () => {
+        const vars = themeToCssVars(lightTheme)
+        expect(vars['--klc-color-background']).toBe(lightTheme.colors.background)
+    })
+
+    it('colors.candleUpBody → --klc-color-candle-up-body', () => {
+        const vars = themeToCssVars(lightTheme)
+        expect(vars['--klc-color-candle-up-body']).toBe(lightTheme.colors.candleUpBody)
+    })
+
+    it('colors.palette.i1 → --klc-color-palette-i1', () => {
+        const vars = themeToCssVars(lightTheme)
+        expect(vars['--klc-color-palette-i1']).toBe(lightTheme.colors.palette.i1)
+    })
+
+    it('spacing.md → --klc-spacing-md', () => {
+        const vars = themeToCssVars(lightTheme)
+        expect(vars['--klc-spacing-md']).toBe(lightTheme.spacing.md)
+    })
+
+    it('typography.fontWeightRegular → string-cast number', () => {
+        const vars = themeToCssVars(lightTheme)
+        expect(vars['--klc-typography-font-weight-regular']).toBe(
+            String(lightTheme.typography.fontWeightRegular),
+        )
+    })
+
+    it('motion.durationFast → --klc-motion-duration-fast', () => {
+        const vars = themeToCssVars(lightTheme)
+        expect(vars['--klc-motion-duration-fast']).toBe(lightTheme.motion.durationFast)
+    })
+})
+
+describe('themeToCssVars — prefix', () => {
+    it('honours a custom prefix', () => {
+        const vars = themeToCssVars(lightTheme, { prefix: '--chart-' })
+        expect(vars['--chart-color-background']).toBe(lightTheme.colors.background)
+        expect(vars['--klc-color-background']).toBeUndefined()
+    })
+
+    it('throws when the prefix does not start with --', () => {
+        expect(() => themeToCssVars(lightTheme, { prefix: 'klc-' })).toThrow(
+            /must start with '--'/,
+        )
+    })
+})
+
+describe('themeToCssVars — light vs dark parity', () => {
+    it('both themes produce maps with the exact same key set', () => {
+        const l = Object.keys(themeToCssVars(lightTheme)).sort()
+        const d = Object.keys(themeToCssVars(darkTheme)).sort()
+        expect(l).toEqual(d)
+    })
+})
+
+describe('themeToCssVars — mergeTheme propagation', () => {
+    it('an override surfaces in the emit output', () => {
+        const custom = mergeTheme(lightTheme, {
+            colors: { candleUpBody: '#112233' },
+        })
+        expect(themeToCssVars(custom)['--klc-color-candle-up-body']).toBe('#112233')
+    })
+
+    it('non-overridden keys keep the base value', () => {
+        const custom = mergeTheme(lightTheme, {
+            colors: { candleUpBody: '#112233' },
+        })
+        expect(themeToCssVars(custom)['--klc-color-background']).toBe(
+            lightTheme.colors.background,
+        )
+    })
+})
+
+describe('toCssDeclarationBlock', () => {
+    it('produces a parseable :root block by default', () => {
+        const css = toCssDeclarationBlock(themeToCssVars(lightTheme))
+        expect(css.startsWith(':root {\n')).toBe(true)
+        expect(css.endsWith('\n}')).toBe(true)
+        expect(css).toContain('--klc-color-background: ' + lightTheme.colors.background + ';')
+    })
+
+    it('honours a custom selector', () => {
+        const css = toCssDeclarationBlock(
+            themeToCssVars(darkTheme),
+            '[data-theme="dark"]',
+        )
+        expect(css.startsWith('[data-theme="dark"] {\n')).toBe(true)
+    })
+
+    it('emits one declaration per line', () => {
+        const vars = themeToCssVars(lightTheme)
+        const css = toCssDeclarationBlock(vars)
+        // count of `;` lines should equal the number of vars
+        const semicolons = (css.match(/;/g) ?? []).length
+        expect(semicolons).toBe(Object.keys(vars).length)
+    })
+})

package/src/tokens/__tests__/tokens.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Design token contract tests.
+ *
+ * What this enforces:
+ *   1. **Theme parity** — `lightTheme` and `darkTheme` have the exact
+ *      same key set in every token family. Adding a key to one without
+ *      the other is the most common source of "looks fine in dev,
+ *      breaks in production" theme bugs.
+ *   2. **Color validity** — every color token parses as a CSS color
+ *      we can hand the renderer. We accept 6/8-digit hex, plus the
+ *      single named `transparent` keyword.
+ *   3. **WCAG contrast** — bull/bear vs background must reach the AA
+ *      threshold (≥ 3:1 for non-text graphics). This is the floor;
+ *      themes are encouraged to exceed it.
+ *   4. **Merge semantics** — `mergeTheme(base, override)` is shallow
+ *      per family, deep on `colors.palette`, and never mutates inputs.
+ */
+
+import { describe, it, expect } from 'vitest'
+
+import {
+    lightTheme,
+    darkTheme,
+    mergeTheme,
+    type Theme,
+    type ColorTokens,
+} from '..'
+
+// ---------------------------------------------------------------------------
+// Color parsing & contrast helpers (kept inline so tests don't reach into
+// renderer internals — those will arrive in a later tick).
+// ---------------------------------------------------------------------------
+
+const HEX = /^#[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$/
+const RGBA = /^rgba?\(/
+const HSLA = /^hsla?\(/
+
+function parseHex(color: string): { r: number; g: number; b: number } | null {
+    if (!HEX.test(color)) return null
+    const r = parseInt(color.slice(1, 3), 16)
+    const g = parseInt(color.slice(3, 5), 16)
+    const b = parseInt(color.slice(5, 7), 16)
+    return { r, g, b }
+}
+
+function relativeLuminance(c: string): number {
+    const p = parseHex(c)
+    if (p === null) throw new Error(`relativeLuminance: ${c} not parseable`)
+    const linear = (v: number): number => {
+        const s = v / 255
+        return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4)
+    }
+    return 0.2126 * linear(p.r) + 0.7152 * linear(p.g) + 0.0722 * linear(p.b)
+}
+
+function contrast(a: string, b: string): number {
+    const la = relativeLuminance(a)
+    const lb = relativeLuminance(b)
+    const [hi, lo] = la > lb ? [la, lb] : [lb, la]
+    return (hi + 0.05) / (lo + 0.05)
+}
+
+// ---------------------------------------------------------------------------
+// Parity
+// ---------------------------------------------------------------------------
+
+function keysSorted(o: object): string[] {
+    return Object.keys(o).sort()
+}
+
+describe('theme parity', () => {
+    it('lightTheme and darkTheme expose the same top-level families', () => {
+        expect(keysSorted(lightTheme)).toEqual(keysSorted(darkTheme))
+    })
+
+    it.each([
+        ['colors', (t: Theme) => t.colors],
+        ['spacing', (t: Theme) => t.spacing],
+        ['typography', (t: Theme) => t.typography],
+        ['motion', (t: Theme) => t.motion],
+    ] as const)('family %s has the same key set in both themes', (_name, pick) => {
+        expect(keysSorted(pick(lightTheme))).toEqual(keysSorted(pick(darkTheme)))
+    })
+
+    it('palette has the same i1..i10 keys in both themes', () => {
+        expect(keysSorted(lightTheme.colors.palette)).toEqual(
+            keysSorted(darkTheme.colors.palette),
+        )
+        expect(keysSorted(lightTheme.colors.palette)).toEqual([
+            'i1',
+            'i10',
+            'i2',
+            'i3',
+            'i4',
+            'i5',
+            'i6',
+            'i7',
+            'i8',
+            'i9',
+        ])
+    })
+})
+
+// ---------------------------------------------------------------------------
+// Color value validity
+// ---------------------------------------------------------------------------
+
+function colorEntries(c: ColorTokens, prefix = ''): Array<[string, string]> {
+    const out: Array<[string, string]> = []
+    for (const [k, v] of Object.entries(c)) {
+        const key = prefix ? `${prefix}.${k}` : k
+        if (typeof v === 'object' && v !== null) {
+            out.push(...colorEntries(v as unknown as ColorTokens, key))
+        } else {
+            out.push([key, v as string])
+        }
+    }
+    return out
+}
+
+describe('color value validity', () => {
+    for (const theme of [lightTheme, darkTheme]) {
+        for (const [key, value] of colorEntries(theme.colors)) {
+            it(`${theme.name}: ${key} is a valid CSS color string`, () => {
+                // Top-level tokens are hex; legacy compatibility groups
+                // may use rgba/hsl/transparent.
+                const valid =
+                    HEX.test(value) ||
+                    RGBA.test(value) ||
+                    HSLA.test(value) ||
+                    value === 'transparent'
+                expect(valid).toBe(true)
+            })
+        }
+    }
+})
+
+// ---------------------------------------------------------------------------
+// WCAG AA non-text contrast (≥ 3:1) for the bull / bear roles
+// ---------------------------------------------------------------------------
+
+function hexBase(c: string): string {
+    // Drop alpha if present so contrast is measured against the unmuted hue.
+    return c.length === 9 ? c.slice(0, 7) : c
+}
+
+describe('WCAG AA contrast — candle bull/bear vs background (≥ 3:1)', () => {
+    for (const theme of [lightTheme, darkTheme]) {
+        for (const role of ['candleUpBody', 'candleDownBody'] as const) {
+            it(`${theme.name}: ${role}`, () => {
+                const ratio = contrast(
+                    hexBase(theme.colors[role]),
+                    hexBase(theme.colors.background),
+                )
+                expect(ratio).toBeGreaterThanOrEqual(3)
+            })
+        }
+    }
+})
+
+describe('WCAG AA contrast — foreground text vs background (≥ 4.5:1)', () => {
+    for (const theme of [lightTheme, darkTheme]) {
+        it(`${theme.name}`, () => {
+            const ratio = contrast(
+                hexBase(theme.colors.foreground),
+                hexBase(theme.colors.background),
+            )
+            expect(ratio).toBeGreaterThanOrEqual(4.5)
+        })
+    }
+})
+
+// ---------------------------------------------------------------------------
+// mergeTheme
+// ---------------------------------------------------------------------------
+
+describe('mergeTheme', () => {
+    it('returns a new theme; never mutates the base', () => {
+        const before = JSON.stringify(lightTheme)
+        const merged = mergeTheme(lightTheme, {
+            name: 'custom',
+            colors: { candleUpBody: '#111111' },
+        })
+        expect(JSON.stringify(lightTheme)).toBe(before)
+        expect(merged).not.toBe(lightTheme)
+    })
+
+    it('override wins for each specified key; base wins elsewhere', () => {
+        const merged = mergeTheme(lightTheme, {
+            colors: { candleUpBody: '#111111' },
+        })
+        expect(merged.colors.candleUpBody).toBe('#111111')
+        expect(merged.colors.candleDownBody).toBe(lightTheme.colors.candleDownBody)
+        expect(merged.colors.background).toBe(lightTheme.colors.background)
+    })
+
+    it('palette merges per-key, not whole-replace', () => {
+        const merged = mergeTheme(lightTheme, {
+            colors: { palette: { i1: '#000000' } },
+        })
+        expect(merged.colors.palette.i1).toBe('#000000')
+        expect(merged.colors.palette.i2).toBe(lightTheme.colors.palette.i2)
+        expect(merged.colors.palette.i10).toBe(lightTheme.colors.palette.i10)
+    })
+
+    it('name override propagates', () => {
+        const merged = mergeTheme(lightTheme, { name: 'corporate' })
+        expect(merged.name).toBe('corporate')
+    })
+
+    it('no override returns a structurally-equal theme', () => {
+        const merged = mergeTheme(lightTheme, {})
+        expect(merged).toEqual(lightTheme)
+    })
+})

package/src/tokens/colorPresetSettings.ts

@@ -0,0 +1,128 @@
+import type { ColorTokens, ColorValue } from './types'
+
+export type ColorPresetThemeName = 'light' | 'dark'
+
+export type ColorPresetKey = keyof Pick<
+    ColorTokens,
+    | 'background'
+    | 'foreground'
+    | 'chartBackground'
+    | 'candleUpBody'
+    | 'candleUpBorder'
+    | 'candleUpWick'
+    | 'candleDownBody'
+    | 'candleDownBorder'
+    | 'candleDownWick'
+    | 'volumeUp'
+    | 'volumeDown'
+    | 'axisText'
+    | 'axisLine'
+    | 'axisTick'
+    | 'gridMajor'
+    | 'gridMinor'
+    | 'crosshairLine'
+    | 'crosshairLabelBg'
+    | 'crosshairLabelText'
+    | 'selectionFill'
+    | 'selectionStroke'
+    | 'tooltipBg'
+    | 'tooltipText'
+    | 'tooltipBorder'
+    | 'volumeProfilePoc'
+    | 'footprintAsk'
+    | 'footprintBid'
+    | 'footprintImbalance'
+    | 'alertActive'
+    | 'alertTriggered'
+    | 'alertMuted'
+    | 'avwapLine'
+    | 'avwapBand'
+    | 'mtfOverlay'
+>
+
+export interface ColorPresetItem {
+    readonly key: ColorPresetKey
+    readonly label: string
+    readonly group: 'canvas' | 'candle' | 'axis' | 'interaction'
+}
+
+export type ColorPresetOverrides = Partial<Record<ColorPresetKey, ColorValue>>
+
+export type ColorPresetSettings = Partial<Record<ColorPresetThemeName, ColorPresetOverrides>>
+
+export const COLOR_PRESET_STORAGE_KEY = 'kline-chart-color-presets'
+
+export const COLOR_PRESET_ITEMS: readonly ColorPresetItem[] = [
+    { key: 'background', label: '背景', group: 'canvas' },
+    { key: 'chartBackground', label: '图表背景', group: 'canvas' },
+    { key: 'foreground', label: '前景', group: 'canvas' },
+    { key: 'gridMajor', label: '主网格线', group: 'canvas' },
+    { key: 'gridMinor', label: '次网格线', group: 'canvas' },
+
+    { key: 'candleUpBody', label: '上涨实体', group: 'candle' },
+    { key: 'candleUpBorder', label: '上涨边框', group: 'candle' },
+    { key: 'candleUpWick', label: '上涨影线', group: 'candle' },
+    { key: 'candleDownBody', label: '下跌实体', group: 'candle' },
+    { key: 'candleDownBorder', label: '下跌边框', group: 'candle' },
+    { key: 'candleDownWick', label: '下跌影线', group: 'candle' },
+    { key: 'volumeUp', label: '上涨成交量', group: 'candle' },
+    { key: 'volumeDown', label: '下跌成交量', group: 'candle' },
+
+    { key: 'axisText', label: '坐标文字', group: 'axis' },
+    { key: 'axisLine', label: '坐标轴线', group: 'axis' },
+    { key: 'axisTick', label: '坐标刻度', group: 'axis' },
+
+    { key: 'crosshairLine', label: '十字光标', group: 'interaction' },
+    { key: 'crosshairLabelBg', label: '光标标签背景', group: 'interaction' },
+    { key: 'crosshairLabelText', label: '光标标签文字', group: 'interaction' },
+    { key: 'selectionFill', label: '选区填充', group: 'interaction' },
+    { key: 'selectionStroke', label: '选区边框', group: 'interaction' },
+    { key: 'tooltipBg', label: '提示背景', group: 'interaction' },
+    { key: 'tooltipText', label: '提示文字', group: 'interaction' },
+    { key: 'tooltipBorder', label: '提示边框', group: 'interaction' },
+
+    { key: 'volumeProfilePoc', label: '成交量 POC', group: 'interaction' },
+    { key: 'footprintAsk', label: '主动买盘', group: 'interaction' },
+    { key: 'footprintBid', label: '主动卖盘', group: 'interaction' },
+    { key: 'footprintImbalance', label: '订单失衡', group: 'interaction' },
+    { key: 'alertActive', label: '活动警报', group: 'interaction' },
+    { key: 'alertTriggered', label: '触发警报', group: 'interaction' },
+    { key: 'alertMuted', label: '静音警报', group: 'interaction' },
+    { key: 'avwapLine', label: 'AVWAP 线', group: 'interaction' },
+    { key: 'avwapBand', label: 'AVWAP 区域', group: 'interaction' },
+    { key: 'mtfOverlay', label: '多周期叠加', group: 'interaction' },
+]
+
+const COLOR_PRESET_KEYS = new Set<ColorPresetKey>(COLOR_PRESET_ITEMS.map((item) => item.key))
+
+export function normalizeColorPresetSettings(value: unknown): ColorPresetSettings {
+    if (!value || typeof value !== 'object') return {}
+
+    const source = value as Record<string, unknown>
+    const result: ColorPresetSettings = {}
+
+    for (const themeName of ['light', 'dark'] as const) {
+        const themeOverrides = source[themeName]
+        if (!themeOverrides || typeof themeOverrides !== 'object') continue
+
+        const clean: ColorPresetOverrides = {}
+        for (const [key, color] of Object.entries(themeOverrides as Record<string, unknown>)) {
+            if (COLOR_PRESET_KEYS.has(key as ColorPresetKey) && typeof color === 'string' && color.trim()) {
+                clean[key as ColorPresetKey] = color
+            }
+        }
+        if (Object.keys(clean).length > 0) result[themeName] = clean
+    }
+
+    return result
+}
+
+export function applyColorPresetOverrides(
+    colors: ColorTokens,
+    themeName: ColorPresetThemeName,
+    settings?: ColorPresetSettings,
+): ColorTokens {
+    const overrides = settings?.[themeName]
+    if (!overrides || Object.keys(overrides).length === 0) return colors
+    return { ...colors, ...overrides }
+}

package/src/tokens/index.ts

@@ -0,0 +1,65 @@
+/**
+ * @klinechart-quant/core/tokens — semantic design tokens + presets.
+ *
+ * See `./types.ts` for the contract; `./theme-light.ts` and
+ * `./theme-dark.ts` for shipping presets; `./mergeTheme.ts` for the
+ * override helper.
+ *
+ * Public surface from the root `@klinechart-quant/core` barrel.
+ */
+
+export type {
+    Theme,
+    ThemeOverride,
+    ColorTokens,
+    SpacingTokens,
+    TypographyTokens,
+    MotionTokens,
+    IndicatorPalette,
+    ColorValue,
+    CssLength,
+    CssDuration,
+    CssEasing,
+    TextColors,
+    PriceColors,
+    TagBgColors,
+    BorderColors,
+    MAColors,
+    BOLLColors,
+    MACDColors,
+    RSIColors,
+    CCIColors,
+    KDJColors,
+    MOMColors,
+    WMSRColors,
+    KSTColors,
+    EXPMAColors,
+    ENEColors,
+    LabelColors,
+    LastPriceLabelColors,
+    VolumePriceColors,
+    StructureColors,
+    ZonesColors,
+} from './types'
+
+export { lightTheme } from './theme-light'
+export { darkTheme } from './theme-dark'
+export { withAsiaMarketColors, resolveThemeColors } from './theme-china'
+export { mergeTheme } from './mergeTheme'
+export {
+    COLOR_PRESET_ITEMS,
+    COLOR_PRESET_STORAGE_KEY,
+    applyColorPresetOverrides,
+    normalizeColorPresetSettings,
+    type ColorPresetItem,
+    type ColorPresetKey,
+    type ColorPresetOverrides,
+    type ColorPresetSettings,
+    type ColorPresetThemeName,
+} from './colorPresetSettings'
+export {
+    themeToCssVars,
+    toCssDeclarationBlock,
+    camelToKebab,
+    type ThemeToCssVarsOptions,
+} from './themeToCssVars'

package/src/tokens/mergeTheme.ts

@@ -0,0 +1,48 @@
+/**
+ * Theme override / merge helper.
+ *
+ *   const myTheme = mergeTheme(lightTheme, {
+ *     name: 'my-light',
+ *     colors: { candleUpBody: '#00C896' },
+ *   })
+ *
+ * Shallow-merges each top-level token family. Within a family, the
+ * override wins for any key it specifies; missing keys fall back to the
+ * base. The override's `name` (if provided) wins.
+ *
+ * Strictly immutable: returns a new theme; the inputs are untouched.
+ */
+
+import type { Theme, ThemeOverride } from './types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function isRecord(v: unknown): v is Record<string, any> {
+    return v !== null && typeof v === 'object'
+}
+
+function deepMergeColors(
+    base: Theme['colors'],
+    override: Partial<Theme['colors']> | undefined,
+): Theme['colors'] {
+    const merged = { ...base } as unknown as Record<string, unknown>
+    if (!override) return merged as unknown as Theme['colors']
+    for (const [k, v] of Object.entries(override)) {
+        const baseVal = (base as unknown as Record<string, unknown>)[k]
+        if (isRecord(v) && isRecord(baseVal)) {
+            merged[k] = { ...baseVal, ...v }
+        } else if (v !== undefined) {
+            merged[k] = v
+        }
+    }
+    return merged as unknown as Theme['colors']
+}
+
+export function mergeTheme(base: Theme, override: ThemeOverride): Theme {
+    return {
+        name: override.name ?? base.name,
+        colors: deepMergeColors(base.colors, override.colors),
+        spacing: { ...base.spacing, ...(override.spacing ?? {}) },
+        typography: { ...base.typography, ...(override.typography ?? {}) },
+        motion: { ...base.motion, ...(override.motion ?? {}) },
+    }
+}