diff --git a/CHANGELOG.md b/CHANGELOG.md index 4b5efc628..ffef8f970 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Add support for `addBase` plugins using the `@plugin` directive ([#14172](https://github.com/tailwindlabs/tailwindcss/pull/14172)) - Add support for the `tailwindcss/plugin` export ([#14173](https://github.com/tailwindlabs/tailwindcss/pull/14173)) +- Add support for the `theme()` function in plugins ([#14207](https://github.com/tailwindlabs/tailwindcss/pull/14207)) ### Fixed diff --git a/packages/tailwindcss/src/ast.ts b/packages/tailwindcss/src/ast.ts index 6f4901c25..07e104456 100644 --- a/packages/tailwindcss/src/ast.ts +++ b/packages/tailwindcss/src/ast.ts @@ -42,30 +42,6 @@ export function comment(value: string): Comment { } } -export type CssInJs = { [key: string]: string | CssInJs } - -export function objectToAst(obj: CssInJs): AstNode[] { - let ast: AstNode[] = [] - - for (let [name, value] of Object.entries(obj)) { - if (typeof value === 'string') { - if (!name.startsWith('--') && value === '@slot') { - ast.push(rule(name, [rule('@slot', [])])) - } else { - // Convert camelCase to kebab-case: - // https://github.com/postcss/postcss-js/blob/b3db658b932b42f6ac14ca0b1d50f50c4569805b/parser.js#L30-L35 - name = name.replace(/([A-Z])/g, '-$1').toLowerCase() - - ast.push(decl(name, value)) - } - } else { - ast.push(rule(name, objectToAst(value))) - } - } - - return ast -} - export enum WalkAction { /** Continue walking, which is the default */ Continue, diff --git a/packages/tailwindcss/src/compat/config/create-compat-config.ts b/packages/tailwindcss/src/compat/config/create-compat-config.ts new file mode 100644 index 000000000..540886f0d --- /dev/null +++ b/packages/tailwindcss/src/compat/config/create-compat-config.ts @@ -0,0 +1,179 @@ +import type { NamedUtilityValue } from '../../candidate' +import type { Theme } from '../../theme' +import { segment } from '../../utils/segment' +import type { UserConfig } from './types' + +function bareValues(fn: (value: NamedUtilityValue) => string | undefined) { + return { + // Ideally this would be a Symbol but some of the ecosystem assumes object with + // string / number keys for example by using `Object.entries()` which means that + // the function that handles the bare value would be lost + __BARE_VALUE__: fn, + } +} + +let bareIntegers = bareValues((value) => { + if (!Number.isNaN(Number(value.value))) { + return value.value + } +}) + +let barePercentages = bareValues((value: NamedUtilityValue) => { + if (!Number.isNaN(Number(value.value))) { + return `${value.value}%` + } +}) + +let barePixels = bareValues((value: NamedUtilityValue) => { + if (!Number.isNaN(Number(value.value))) { + return `${value.value}px` + } +}) + +let bareMilliseconds = bareValues((value: NamedUtilityValue) => { + if (!Number.isNaN(Number(value.value))) { + return `${value.value}ms` + } +}) + +let bareDegrees = bareValues((value: NamedUtilityValue) => { + if (!Number.isNaN(Number(value.value))) { + return `${value.value}deg` + } +}) + +export function createCompatConfig(theme: Theme): UserConfig { + return { + theme: { + colors: ({ theme }) => theme('color', {}), + accentColor: ({ theme }) => theme('colors'), + aspectRatio: bareValues((value) => { + if (value.fraction === null) return + let [lhs, rhs] = segment(value.fraction, '/') + if (!Number.isInteger(Number(lhs)) || !Number.isInteger(Number(rhs))) return + return value.fraction + }), + backdropBlur: ({ theme }) => theme('blur'), + backdropBrightness: ({ theme }) => ({ + ...theme('brightness'), + ...barePercentages, + }), + backdropContrast: ({ theme }) => ({ + ...theme('contrast'), + ...barePercentages, + }), + backdropGrayscale: ({ theme }) => ({ + ...theme('grayscale'), + ...barePercentages, + }), + backdropHueRotate: ({ theme }) => ({ + ...theme('hueRotate'), + ...bareDegrees, + }), + backdropInvert: ({ theme }) => ({ + ...theme('invert'), + ...barePercentages, + }), + backdropOpacity: ({ theme }) => ({ + ...theme('opacity'), + ...barePercentages, + }), + backdropSaturate: ({ theme }) => ({ + ...theme('saturate'), + ...barePercentages, + }), + backdropSepia: ({ theme }) => ({ + ...theme('sepia'), + ...barePercentages, + }), + backgroundColor: ({ theme }) => theme('colors'), + backgroundOpacity: ({ theme }) => theme('opacity'), + border: barePixels, + borderColor: ({ theme }) => theme('colors'), + borderOpacity: ({ theme }) => theme('opacity'), + borderSpacing: ({ theme }) => theme('spacing'), + boxShadowColor: ({ theme }) => theme('colors'), + brightness: barePercentages, + caretColor: ({ theme }) => theme('colors'), + columns: bareIntegers, + contrast: barePercentages, + divideColor: ({ theme }) => theme('borderColor'), + divideOpacity: ({ theme }) => theme('borderOpacity'), + divideWidth: ({ theme }) => ({ + ...theme('borderWidth'), + ...barePixels, + }), + fill: ({ theme }) => theme('colors'), + flexBasis: ({ theme }) => theme('spacing'), + flexGrow: bareIntegers, + flexShrink: bareIntegers, + gap: ({ theme }) => theme('spacing'), + gradientColorStopPositions: barePercentages, + gradientColorStops: ({ theme }) => theme('colors'), + grayscale: barePercentages, + gridRowEnd: bareIntegers, + gridRowStart: bareIntegers, + gridTemplateColumns: bareValues((value) => { + if (!Number.isNaN(Number(value.value))) { + return `repeat(${value.value}, minmax(0, 1fr))` + } + }), + gridTemplateRows: bareValues((value) => { + if (!Number.isNaN(Number(value.value))) { + return `repeat(${value.value}, minmax(0, 1fr))` + } + }), + height: ({ theme }) => theme('spacing'), + hueRotate: bareDegrees, + inset: ({ theme }) => theme('spacing'), + invert: barePercentages, + lineClamp: bareIntegers, + margin: ({ theme }) => theme('spacing'), + maxHeight: ({ theme }) => theme('spacing'), + maxWidth: ({ theme }) => theme('spacing'), + minHeight: ({ theme }) => theme('spacing'), + minWidth: ({ theme }) => theme('spacing'), + opacity: barePercentages, + order: bareIntegers, + outlineColor: ({ theme }) => theme('colors'), + outlineOffset: barePixels, + outlineWidth: barePixels, + padding: ({ theme }) => theme('spacing'), + placeholderColor: ({ theme }) => theme('colors'), + placeholderOpacity: ({ theme }) => theme('opacity'), + ringColor: ({ theme }) => theme('colors'), + ringOffsetColor: ({ theme }) => theme('colors'), + ringOffsetWidth: barePixels, + ringOpacity: ({ theme }) => theme('opacity'), + ringWidth: barePixels, + rotate: bareDegrees, + saturate: barePercentages, + scale: barePercentages, + scrollMargin: ({ theme }) => theme('spacing'), + scrollPadding: ({ theme }) => theme('spacing'), + sepia: barePercentages, + size: ({ theme }) => theme('spacing'), + skew: bareDegrees, + space: ({ theme }) => theme('spacing'), + stroke: ({ theme }) => theme('colors'), + strokeWidth: barePixels, + textColor: ({ theme }) => theme('colors'), + textDecorationColor: ({ theme }) => theme('colors'), + textDecorationThickness: barePixels, + textIndent: ({ theme }) => theme('spacing'), + textOpacity: ({ theme }) => theme('opacity'), + textUnderlineOffset: barePixels, + transitionDelay: bareMilliseconds, + transitionDuration: { + DEFAULT: theme.get(['--default-transition-duration']) ?? null, + ...bareMilliseconds, + }, + transitionTimingFunction: { + DEFAULT: theme.get(['--default-transition-timing-function']) ?? null, + }, + translate: ({ theme }) => theme('spacing'), + width: ({ theme }) => theme('spacing'), + zIndex: bareIntegers, + }, + } +} diff --git a/packages/tailwindcss/src/compat/config/deep-merge.ts b/packages/tailwindcss/src/compat/config/deep-merge.ts new file mode 100644 index 000000000..49ac100b5 --- /dev/null +++ b/packages/tailwindcss/src/compat/config/deep-merge.ts @@ -0,0 +1,37 @@ +export function isPlainObject(value: T): value is T & Record { + if (Object.prototype.toString.call(value) !== '[object Object]') { + return false + } + + const prototype = Object.getPrototypeOf(value) + return prototype === null || Object.getPrototypeOf(prototype) === null +} + +export function deepMerge( + target: T, + sources: (Partial | null | undefined)[], + customizer: (a: any, b: any) => any, +) { + type Key = keyof T + type Value = T[Key] + + for (let source of sources) { + if (source === null || source === undefined) { + continue + } + + for (let k of Reflect.ownKeys(source) as Key[]) { + let merged = customizer(target[k], source[k]) + + if (merged !== undefined) { + target[k] = merged + } else if (!isPlainObject(target[k]) || !isPlainObject(source[k])) { + target[k] = source[k] as Value + } else { + target[k] = deepMerge({}, [target[k], source[k]], customizer) as Value + } + } + } + + return target +} diff --git a/packages/tailwindcss/src/compat/config/resolve-config.test.ts b/packages/tailwindcss/src/compat/config/resolve-config.test.ts new file mode 100644 index 000000000..c2a0774d7 --- /dev/null +++ b/packages/tailwindcss/src/compat/config/resolve-config.test.ts @@ -0,0 +1,196 @@ +import { test } from 'vitest' +import { buildDesignSystem } from '../../design-system' +import { Theme } from '../../theme' +import { resolveConfig } from './resolve-config' + +test('top level theme keys are replaced', ({ expect }) => { + let design = buildDesignSystem(new Theme()) + + let config = resolveConfig(design, [ + { + theme: { + colors: { + red: 'red', + }, + + fontFamily: { + sans: 'SF Pro Display', + }, + }, + }, + { + theme: { + colors: { + green: 'green', + }, + }, + }, + { + theme: { + colors: { + blue: 'blue', + }, + }, + }, + ]) + + expect(config).toMatchObject({ + theme: { + colors: { + blue: 'blue', + }, + fontFamily: { + sans: 'SF Pro Display', + }, + }, + }) +}) + +test('theme can be extended', ({ expect }) => { + let design = buildDesignSystem(new Theme()) + + let config = resolveConfig(design, [ + { + theme: { + colors: { + red: 'red', + }, + + fontFamily: { + sans: 'SF Pro Display', + }, + }, + }, + { + theme: { + extend: { + colors: { + blue: 'blue', + }, + }, + }, + }, + ]) + + expect(config).toMatchObject({ + theme: { + colors: { + red: 'red', + blue: 'blue', + }, + fontFamily: { + sans: 'SF Pro Display', + }, + }, + }) +}) + +test('theme keys can reference other theme keys using the theme function regardless of order', ({ + expect, +}) => { + let design = buildDesignSystem(new Theme()) + + let config = resolveConfig(design, [ + { + theme: { + colors: { + red: 'red', + }, + placeholderColor: { + green: 'green', + }, + }, + }, + { + theme: { + extend: { + colors: ({ theme }) => ({ + ...theme('placeholderColor'), + blue: 'blue', + }), + }, + }, + }, + { + theme: { + extend: { + caretColor: ({ theme }) => theme('accentColor'), + accentColor: ({ theme }) => theme('backgroundColor'), + backgroundColor: ({ theme }) => theme('colors'), + }, + }, + }, + ]) + + expect(config).toMatchObject({ + theme: { + colors: { + red: 'red', + green: 'green', + blue: 'blue', + }, + accentColor: { + red: 'red', + green: 'green', + blue: 'blue', + }, + backgroundColor: { + red: 'red', + green: 'green', + blue: 'blue', + }, + caretColor: { + red: 'red', + green: 'green', + blue: 'blue', + }, + }, + }) +}) + +test('theme keys can read from the CSS theme', ({ expect }) => { + let theme = new Theme() + theme.add('--color-green', 'green') + + let design = buildDesignSystem(theme) + + let config = resolveConfig(design, [ + { + theme: { + colors: ({ theme }) => ({ + // Reads from the --color-* namespace + ...theme('color'), + red: 'red', + }), + accentColor: ({ theme }) => ({ + // Reads from the --color-* namespace through `colors` + ...theme('colors'), + }), + placeholderColor: ({ theme }) => ({ + // Reads from the --color-* namespace through `colors` + primary: theme('colors.green'), + + // Reads from the --color-* namespace directly + secondary: theme('color.green'), + }), + }, + }, + ]) + + expect(config).toMatchObject({ + theme: { + colors: { + red: 'red', + green: 'var(--color-green, green)', + }, + accentColor: { + red: 'red', + green: 'var(--color-green, green)', + }, + placeholderColor: { + primary: 'var(--color-green, green)', + secondary: 'var(--color-green, green)', + }, + }, + }) +}) diff --git a/packages/tailwindcss/src/compat/config/resolve-config.ts b/packages/tailwindcss/src/compat/config/resolve-config.ts new file mode 100644 index 000000000..c119b29e4 --- /dev/null +++ b/packages/tailwindcss/src/compat/config/resolve-config.ts @@ -0,0 +1,121 @@ +import type { DesignSystem } from '../../design-system' +import { createThemeFn } from '../../theme-fn' +import { deepMerge, isPlainObject } from './deep-merge' +import { + type ResolvedConfig, + type ResolvedThemeValue, + type ThemeValue, + type UserConfig, +} from './types' + +interface ResolutionContext { + design: DesignSystem + configs: UserConfig[] + theme: Record + extend: Record + result: ResolvedConfig +} + +let minimal: ResolvedConfig = { + theme: {}, +} + +export function resolveConfig(design: DesignSystem, configs: UserConfig[]): ResolvedConfig { + let ctx: ResolutionContext = { + design, + configs, + theme: {}, + extend: {}, + + // Start with a minimal valid, but empty config + result: structuredClone(minimal), + } + + // Merge themes + mergeTheme(ctx) + + return { + theme: ctx.theme as ResolvedConfig['theme'], + } +} + +function mergeThemeExtension( + themeValue: ThemeValue | ThemeValue[], + extensionValue: ThemeValue | ThemeValue[], +) { + // When we have an array of objects, we do want to merge it + if (Array.isArray(themeValue) && isPlainObject(themeValue[0])) { + return themeValue.concat(extensionValue) + } + + // When the incoming value is an array, and the existing config is an object, + // prepend the existing object + if ( + Array.isArray(extensionValue) && + isPlainObject(extensionValue[0]) && + isPlainObject(themeValue) + ) { + return [themeValue, ...extensionValue] + } + + // Override arrays (for example for font-families, box-shadows, ...) + if (Array.isArray(extensionValue)) { + return extensionValue + } + + // Execute default behaviour + return undefined +} + +export interface PluginUtils { + theme(keypath: string, defaultValue?: any): any +} + +function mergeTheme(ctx: ResolutionContext) { + let api: PluginUtils = { + theme: createThemeFn(ctx.design, () => ctx.theme, resolveValue), + } + + function resolveValue(value: ThemeValue | null | undefined): ResolvedThemeValue { + if (typeof value === 'function') { + return value(api) ?? null + } + + return value ?? null + } + + for (let config of ctx.configs) { + let theme = config.theme ?? {} + let extend = theme.extend ?? {} + + // Shallow merge themes so latest "group" wins + Object.assign(ctx.theme, theme) + + // Collect extensions by key so each + // group can be lazily deep merged + for (let key in extend) { + ctx.extend[key] ??= [] + ctx.extend[key].push(extend[key]) + } + } + + // Remove the `extend` key from the theme It's only used for merging and + // should not be present in the resolved theme + delete ctx.theme.extend + + // Deep merge every `extend` key into the theme + for (let key in ctx.extend) { + let values = [ctx.theme[key], ...ctx.extend[key]] + + ctx.theme[key] = () => { + let v = values.map(resolveValue) + + let result = deepMerge({}, v, mergeThemeExtension) + return result + } + } + + for (let key in ctx.theme) { + ctx.theme[key] = resolveValue(ctx.theme[key]) + } +} diff --git a/packages/tailwindcss/src/compat/config/types.ts b/packages/tailwindcss/src/compat/config/types.ts new file mode 100644 index 000000000..db28725d7 --- /dev/null +++ b/packages/tailwindcss/src/compat/config/types.ts @@ -0,0 +1,18 @@ +import type { PluginUtils } from './resolve-config' + +export type ResolvableTo = T | ((utils: PluginUtils) => T) + +export interface UserConfig { + theme?: ThemeConfig +} + +export type ThemeValue = ResolvableTo> | null | undefined +export type ResolvedThemeValue = Record | null + +export type ThemeConfig = Record & { + extend?: Record +} + +export interface ResolvedConfig { + theme: Record> +} diff --git a/packages/tailwindcss/src/plugin-api.test.ts b/packages/tailwindcss/src/plugin-api.test.ts new file mode 100644 index 000000000..c02521df0 --- /dev/null +++ b/packages/tailwindcss/src/plugin-api.test.ts @@ -0,0 +1,815 @@ +import { describe, test, vi } from 'vitest' +import { compile } from '.' +import plugin from './plugin' + +const css = String.raw + +describe('theme', async () => { + test('plugin theme can contain objects', async ({ expect }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + ` + + let compiler = await compile(input, { + loadPlugin: async () => { + return plugin( + function ({ addBase, theme }) { + addBase({ + '@keyframes enter': theme('keyframes.enter'), + '@keyframes exit': theme('keyframes.exit'), + }) + }, + { + theme: { + extend: { + keyframes: { + enter: { + from: { + opacity: 'var(--tw-enter-opacity, 1)', + transform: + 'translate3d(var(--tw-enter-translate-x, 0), var(--tw-enter-translate-y, 0), 0) scale3d(var(--tw-enter-scale, 1), var(--tw-enter-scale, 1), var(--tw-enter-scale, 1)) rotate(var(--tw-enter-rotate, 0))', + }, + }, + exit: { + to: { + opacity: 'var(--tw-exit-opacity, 1)', + transform: + 'translate3d(var(--tw-exit-translate-x, 0), var(--tw-exit-translate-y, 0), 0) scale3d(var(--tw-exit-scale, 1), var(--tw-exit-scale, 1), var(--tw-exit-scale, 1)) rotate(var(--tw-exit-rotate, 0))', + }, + }, + }, + }, + }, + }, + ) + }, + }) + + expect(compiler.build([])).toMatchInlineSnapshot(` + "@layer base { + @keyframes enter { + from { + opacity: var(--tw-enter-opacity, 1); + transform: translate3d(var(--tw-enter-translate-x, 0), var(--tw-enter-translate-y, 0), 0) scale3d(var(--tw-enter-scale, 1), var(--tw-enter-scale, 1), var(--tw-enter-scale, 1)) rotate(var(--tw-enter-rotate, 0)); + } + } + @keyframes exit { + to { + opacity: var(--tw-exit-opacity, 1); + transform: translate3d(var(--tw-exit-translate-x, 0), var(--tw-exit-translate-y, 0), 0) scale3d(var(--tw-exit-scale, 1), var(--tw-exit-scale, 1), var(--tw-exit-scale, 1)) rotate(var(--tw-exit-rotate, 0)); + } + } + } + " + `) + }) + + test('plugin theme can extend colors', async ({ expect }) => { + let input = css` + @theme reference { + --color-red-500: #ef4444; + } + @tailwind utilities; + @plugin "my-plugin"; + ` + + let compiler = await compile(input, { + loadPlugin: async () => { + return plugin( + function ({ matchUtilities, theme }) { + matchUtilities( + { + scrollbar: (value) => ({ 'scrollbar-color': value }), + }, + { + values: theme('colors'), + }, + ) + }, + { + theme: { + extend: { + colors: { + 'russet-700': '#7a4724', + }, + }, + }, + }, + ) + }, + }) + + expect(compiler.build(['scrollbar-red-500', 'scrollbar-russet-700'])).toMatchInlineSnapshot(` + ".scrollbar-red-500 { + scrollbar-color: var(--color-red-500, #ef4444); + } + .scrollbar-russet-700 { + scrollbar-color: #7a4724; + } + " + `) + }) + + test('plugin theme values can reference legacy theme keys that have been replaced with bare value support', async ({ + expect, + }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + ` + + let compiler = await compile(input, { + loadPlugin: async () => { + return plugin( + function ({ matchUtilities, theme }) { + matchUtilities( + { + 'animate-duration': (value) => ({ 'animation-duration': value }), + }, + { + values: theme('animationDuration'), + }, + ) + }, + { + theme: { + extend: { + animationDuration: ({ theme }: { theme: (path: string) => any }) => { + return { + ...theme('transitionDuration'), + } + }, + }, + }, + }, + ) + }, + }) + + expect(compiler.build(['animate-duration-316'])).toMatchInlineSnapshot(` + ".animate-duration-316 { + animation-duration: 316ms; + } + " + `) + }) + + test('plugin theme values that support bare values are merged with other values for that theme key', async ({ + expect, + }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + ` + + let compiler = await compile(input, { + loadPlugin: async () => { + return plugin( + function ({ matchUtilities, theme }) { + matchUtilities( + { + 'animate-duration': (value) => ({ 'animation-duration': value }), + }, + { + values: theme('animationDuration'), + }, + ) + }, + { + theme: { + extend: { + transitionDuration: { + slow: '800ms', + }, + + animationDuration: ({ theme }: { theme: (path: string) => any }) => ({ + ...theme('transitionDuration'), + }), + }, + }, + }, + ) + }, + }) + + expect(compiler.build(['animate-duration-316', 'animate-duration-slow'])) + .toMatchInlineSnapshot(` + ".animate-duration-316 { + animation-duration: 316ms; + } + .animate-duration-slow { + animation-duration: 800ms; + } + " + `) + }) + + test('theme value functions are resolved correctly regardless of order', async ({ expect }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + ` + + let compiler = await compile(input, { + loadPlugin: async () => { + return plugin( + function ({ matchUtilities, theme }) { + matchUtilities( + { + 'animate-delay': (value) => ({ 'animation-delay': value }), + }, + { + values: theme('animationDelay'), + }, + ) + }, + { + theme: { + extend: { + animationDuration: ({ theme }: { theme: (path: string) => any }) => ({ + ...theme('transitionDuration'), + }), + + animationDelay: ({ theme }: { theme: (path: string) => any }) => ({ + ...theme('animationDuration'), + }), + + transitionDuration: { + slow: '800ms', + }, + }, + }, + }, + ) + }, + }) + + expect(compiler.build(['animate-delay-316', 'animate-delay-slow'])).toMatchInlineSnapshot(` + ".animate-delay-316 { + animation-delay: 316ms; + } + .animate-delay-slow { + animation-delay: 800ms; + } + " + `) + }) + + test('plugins can override the default key', async ({ expect }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + ` + + let compiler = await compile(input, { + loadPlugin: async () => { + return plugin( + function ({ matchUtilities, theme }) { + matchUtilities( + { + 'animate-duration': (value) => ({ 'animation-delay': value }), + }, + { + values: theme('transitionDuration'), + }, + ) + }, + { + theme: { + extend: { + transitionDuration: { + DEFAULT: '1500ms', + }, + }, + }, + }, + ) + }, + }) + + expect(compiler.build(['animate-duration'])).toMatchInlineSnapshot(` + ".animate-duration { + animation-delay: 1500ms; + } + " + `) + }) + + test('plugins can read CSS theme keys using the old theme key notation', async ({ expect }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + @theme reference { + --animation: pulse 1s linear infinite; + --animation-spin: spin 1s linear infinite; + } + ` + + let compiler = await compile(input, { + loadPlugin: async () => { + return plugin(function ({ matchUtilities, theme }) { + matchUtilities( + { + animation: (value) => ({ animation: value }), + }, + { + values: theme('animation'), + }, + ) + + matchUtilities( + { + animation2: (value) => ({ animation: value }), + }, + { + values: { + DEFAULT: theme('animation.DEFAULT'), + twist: theme('animation.spin'), + }, + }, + ) + }) + }, + }) + + expect(compiler.build(['animation-spin', 'animation', 'animation2', 'animation2-twist'])) + .toMatchInlineSnapshot(` + ".animation { + animation: var(--animation, pulse 1s linear infinite); + } + .animation-spin { + animation: var(--animation-spin, spin 1s linear infinite); + } + .animation2 { + animation: var(--animation, pulse 1s linear infinite); + } + .animation2-twist { + animation: var(--animation-spin, spin 1s linear infinite); + } + " + `) + }) + + test('CSS theme values are mreged with JS theme values', async ({ expect }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + @theme reference { + --animation: pulse 1s linear infinite; + --animation-spin: spin 1s linear infinite; + } + ` + + let compiler = await compile(input, { + loadPlugin: async () => { + return plugin( + function ({ matchUtilities, theme }) { + matchUtilities( + { + animation: (value) => ({ '--animation': value }), + }, + { + values: theme('animation'), + }, + ) + }, + { + theme: { + extend: { + animation: { + bounce: 'bounce 1s linear infinite', + }, + }, + }, + }, + ) + }, + }) + + expect(compiler.build(['animation', 'animation-spin', 'animation-bounce'])) + .toMatchInlineSnapshot(` + ".animation { + --animation: var(--animation, pulse 1s linear infinite); + } + .animation-bounce { + --animation: bounce 1s linear infinite; + } + .animation-spin { + --animation: var(--animation-spin, spin 1s linear infinite); + } + " + `) + }) + + test('CSS theme defaults take precedence over JS theme defaults', async ({ expect }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + @theme reference { + --animation: pulse 1s linear infinite; + --animation-spin: spin 1s linear infinite; + } + ` + + let compiler = await compile(input, { + loadPlugin: async () => { + return plugin( + function ({ matchUtilities, theme }) { + matchUtilities( + { + animation: (value) => ({ '--animation': value }), + }, + { + values: theme('animation'), + }, + ) + }, + { + theme: { + extend: { + animation: { + DEFAULT: 'twist 1s linear infinite', + }, + }, + }, + }, + ) + }, + }) + + expect(compiler.build(['animation'])).toMatchInlineSnapshot(` + ".animation { + --animation: var(--animation, pulse 1s linear infinite); + } + " + `) + }) + + test('CSS theme values take precedence even over non-object JS values', async ({ expect }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + @theme reference { + --animation-simple-spin: spin 1s linear infinite; + --animation-simple-bounce: bounce 1s linear infinite; + } + ` + + let fn = vi.fn() + + await compile(input, { + loadPlugin: async () => { + return plugin( + function ({ theme }) { + fn(theme('animation.simple')) + }, + { + theme: { + extend: { + animation: { + simple: 'simple 1s linear', + }, + }, + }, + }, + ) + }, + }) + + expect(fn).toHaveBeenCalledWith({ + spin: 'var(--animation-simple-spin, spin 1s linear infinite)', + bounce: 'var(--animation-simple-bounce, bounce 1s linear infinite)', + }) + }) + + test('all necessary theme keys support bare values', async ({ expect }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + ` + + let { build } = await compile(input, { + loadPlugin: async () => { + return plugin(function ({ matchUtilities, theme }) { + function utility(name: string, themeKey: string) { + matchUtilities( + { [name]: (value) => ({ '--value': value }) }, + { values: theme(themeKey) }, + ) + } + + utility('my-aspect', 'aspectRatio') + utility('my-backdrop-brightness', 'backdropBrightness') + utility('my-backdrop-contrast', 'backdropContrast') + utility('my-backdrop-grayscale', 'backdropGrayscale') + utility('my-backdrop-hue-rotate', 'backdropHueRotate') + utility('my-backdrop-invert', 'backdropInvert') + utility('my-backdrop-opacity', 'backdropOpacity') + utility('my-backdrop-saturate', 'backdropSaturate') + utility('my-backdrop-sepia', 'backdropSepia') + utility('my-border', 'border') + utility('my-brightness', 'brightness') + utility('my-columns', 'columns') + utility('my-contrast', 'contrast') + utility('my-divide-width', 'divideWidth') + utility('my-flex-grow', 'flexGrow') + utility('my-flex-shrink', 'flexShrink') + utility('my-gradient-color-stop-positions', 'gradientColorStopPositions') + utility('my-grayscale', 'grayscale') + utility('my-grid-row-end', 'gridRowEnd') + utility('my-grid-row-start', 'gridRowStart') + utility('my-grid-template-columns', 'gridTemplateColumns') + utility('my-grid-template-rows', 'gridTemplateRows') + utility('my-hue-rotate', 'hueRotate') + utility('my-invert', 'invert') + utility('my-line-clamp', 'lineClamp') + utility('my-opacity', 'opacity') + utility('my-order', 'order') + utility('my-outline-offset', 'outlineOffset') + utility('my-outline-width', 'outlineWidth') + utility('my-ring-offset-width', 'ringOffsetWidth') + utility('my-ring-width', 'ringWidth') + utility('my-rotate', 'rotate') + utility('my-saturate', 'saturate') + utility('my-scale', 'scale') + utility('my-sepia', 'sepia') + utility('my-skew', 'skew') + utility('my-stroke-width', 'strokeWidth') + utility('my-text-decoration-thickness', 'textDecorationThickness') + utility('my-text-underline-offset', 'textUnderlineOffset') + utility('my-transition-delay', 'transitionDelay') + utility('my-transition-duration', 'transitionDuration') + utility('my-z-index', 'zIndex') + }) + }, + }) + + let output = build([ + 'my-aspect-2/5', + 'my-backdrop-brightness-1', + 'my-backdrop-contrast-1', + 'my-backdrop-grayscale-1', + 'my-backdrop-hue-rotate-1', + 'my-backdrop-invert-1', + 'my-backdrop-opacity-1', + 'my-backdrop-saturate-1', + 'my-backdrop-sepia-1', + 'my-border-1', + 'my-brightness-1', + 'my-columns-1', + 'my-contrast-1', + 'my-divide-width-1', + 'my-flex-grow-1', + 'my-flex-shrink-1', + 'my-gradient-color-stop-positions-1', + 'my-grayscale-1', + 'my-grid-row-end-1', + 'my-grid-row-start-1', + 'my-grid-template-columns-1', + 'my-grid-template-rows-1', + 'my-hue-rotate-1', + 'my-invert-1', + 'my-line-clamp-1', + 'my-opacity-1', + 'my-order-1', + 'my-outline-offset-1', + 'my-outline-width-1', + 'my-ring-offset-width-1', + 'my-ring-width-1', + 'my-rotate-1', + 'my-saturate-1', + 'my-scale-1', + 'my-sepia-1', + 'my-skew-1', + 'my-stroke-width-1', + 'my-text-decoration-thickness-1', + 'my-text-underline-offset-1', + 'my-transition-delay-1', + 'my-transition-duration-1', + 'my-z-index-1', + ]) + + expect(output).toMatchInlineSnapshot(` + ".my-aspect-2\\/5 { + --value: 2/5; + } + .my-backdrop-brightness-1 { + --value: 1%; + } + .my-backdrop-contrast-1 { + --value: 1%; + } + .my-backdrop-grayscale-1 { + --value: 1%; + } + .my-backdrop-hue-rotate-1 { + --value: 1deg; + } + .my-backdrop-invert-1 { + --value: 1%; + } + .my-backdrop-opacity-1 { + --value: 1%; + } + .my-backdrop-saturate-1 { + --value: 1%; + } + .my-backdrop-sepia-1 { + --value: 1%; + } + .my-border-1 { + --value: 1px; + } + .my-brightness-1 { + --value: 1%; + } + .my-columns-1 { + --value: 1; + } + .my-contrast-1 { + --value: 1%; + } + .my-divide-width-1 { + --value: 1px; + } + .my-flex-grow-1 { + --value: 1; + } + .my-flex-shrink-1 { + --value: 1; + } + .my-gradient-color-stop-positions-1 { + --value: 1%; + } + .my-grayscale-1 { + --value: 1%; + } + .my-grid-row-end-1 { + --value: 1; + } + .my-grid-row-start-1 { + --value: 1; + } + .my-grid-template-columns-1 { + --value: repeat(1, minmax(0, 1fr)); + } + .my-grid-template-rows-1 { + --value: repeat(1, minmax(0, 1fr)); + } + .my-hue-rotate-1 { + --value: 1deg; + } + .my-invert-1 { + --value: 1%; + } + .my-line-clamp-1 { + --value: 1; + } + .my-opacity-1 { + --value: 1%; + } + .my-order-1 { + --value: 1; + } + .my-outline-offset-1 { + --value: 1px; + } + .my-outline-width-1 { + --value: 1px; + } + .my-ring-offset-width-1 { + --value: 1px; + } + .my-ring-width-1 { + --value: 1px; + } + .my-rotate-1 { + --value: 1deg; + } + .my-saturate-1 { + --value: 1%; + } + .my-scale-1 { + --value: 1%; + } + .my-sepia-1 { + --value: 1%; + } + .my-skew-1 { + --value: 1deg; + } + .my-stroke-width-1 { + --value: 1px; + } + .my-text-decoration-thickness-1 { + --value: 1px; + } + .my-text-underline-offset-1 { + --value: 1px; + } + .my-transition-delay-1 { + --value: 1ms; + } + .my-transition-duration-1 { + --value: 1ms; + } + .my-z-index-1 { + --value: 1; + } + " + `) + }) + + test('theme keys can derive from other theme keys', async ({ expect }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + @theme { + --color-primary: red; + --color-secondary: blue; + } + ` + + let fn = vi.fn() + + await compile(input, { + loadPlugin: async () => { + return plugin( + ({ theme }) => { + // The compatability config specifies that `accentColor` spreads in `colors` + fn(theme('accentColor.primary')) + + // This should even work for theme keys specified in plugin configs + fn(theme('myAccentColor.secondary')) + }, + { + theme: { + extend: { + myAccentColor: ({ theme }) => theme('accentColor'), + }, + }, + }, + ) + }, + }) + + expect(fn).toHaveBeenCalledWith('var(--color-primary, red)') + expect(fn).toHaveBeenCalledWith('var(--color-secondary, blue)') + }) + + test('nested theme key lookups work even for flattened keys', async ({ expect }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + @theme { + --color-red-100: red; + --color-red-200: orangered; + --color-red-300: darkred; + } + ` + + let fn = vi.fn() + + await compile(input, { + loadPlugin: async () => { + return plugin(({ theme }) => { + fn(theme('color.red.100')) + fn(theme('colors.red.200')) + fn(theme('backgroundColor.red.300')) + }) + }, + }) + + expect(fn).toHaveBeenCalledWith('var(--color-red-100, red)') + expect(fn).toHaveBeenCalledWith('var(--color-red-200, orangered)') + expect(fn).toHaveBeenCalledWith('var(--color-red-300, darkred)') + }) + + test('keys that do not exist return the default value (or undefined if none)', async ({ + expect, + }) => { + let input = css` + @tailwind utilities; + @plugin "my-plugin"; + ` + + let fn = vi.fn() + + await compile(input, { + loadPlugin: async () => { + return plugin(({ theme }) => { + fn(theme('i.do.not.exist')) + fn(theme('color')) + fn(theme('color', 'magenta')) + fn(theme('colors')) + }) + }, + }) + + expect(fn).toHaveBeenCalledWith(undefined) // Not present in CSS or resolved config + expect(fn).toHaveBeenCalledWith(undefined) // Not present in CSS or resolved config + expect(fn).toHaveBeenCalledWith('magenta') // Not present in CSS or resolved config + expect(fn).toHaveBeenCalledWith({}) // Present in the resolved config + }) +}) diff --git a/packages/tailwindcss/src/plugin-api.ts b/packages/tailwindcss/src/plugin-api.ts index 3599c7a20..9140a7772 100644 --- a/packages/tailwindcss/src/plugin-api.ts +++ b/packages/tailwindcss/src/plugin-api.ts @@ -1,13 +1,17 @@ import { substituteAtApply } from './apply' -import { objectToAst, rule, type AstNode, type CssInJs } from './ast' +import { decl, rule, type AstNode } from './ast' +import type { NamedUtilityValue } from './candidate' +import { createCompatConfig } from './compat/config/create-compat-config' +import { resolveConfig } from './compat/config/resolve-config' +import type { UserConfig } from './compat/config/types' import type { DesignSystem } from './design-system' +import { createThemeFn } from './theme-fn' import { withAlpha, withNegative } from './utilities' import { inferDataType } from './utils/infer-data-type' -export type Config = Record - +export type Config = UserConfig export type PluginFn = (api: PluginAPI) => void -export type PluginWithConfig = { handler: PluginFn; config?: Partial } +export type PluginWithConfig = { handler: PluginFn; config?: UserConfig } export type PluginWithOptions = { (options?: T): PluginWithConfig __isOptionsFunction: true @@ -24,15 +28,22 @@ export type PluginAPI = { options?: Partial<{ type: string | string[] supportsNegativeValues: boolean - values: Record + values: Record & { + __BARE_VALUE__?: (value: NamedUtilityValue) => string | undefined + } modifiers: 'any' | Record }>, ): void + theme(path: string, defaultValue?: any): any } const IS_VALID_UTILITY_NAME = /^[a-z][a-zA-Z0-9/%._-]*$/ -export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): PluginAPI { +function buildPluginApi( + designSystem: DesignSystem, + ast: AstNode[], + resolvedConfig: { theme?: Record }, +): PluginAPI { return { addBase(css) { ast.push(rule('@layer base', objectToAst(css))) @@ -61,6 +72,11 @@ export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): Plug addUtilities(utilities) { for (let [name, css] of Object.entries(utilities)) { + if (name.startsWith('@keyframes ')) { + ast.push(rule(name, objectToAst(css))) + continue + } + if (name[0] !== '.' || !IS_VALID_UTILITY_NAME.test(name.slice(1))) { throw new Error( `\`addUtilities({ '${name}' : … })\` defines an invalid utility selector. Utilities must be a single class name and start with a lowercase letter, eg. \`.scrollbar-none\`.`, @@ -120,7 +136,8 @@ export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): Plug let isColor = types.includes('color') // Resolve the candidate value - let value: string | null + let value: string | null = null + let isFraction = false { let values = options?.values ?? {} @@ -128,24 +145,30 @@ export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): Plug if (isColor) { // Color utilities implicitly support `inherit`, `transparent`, and `currentColor` // for backwards compatibility but still allow them to be overridden - values = { - inherit: 'inherit', - transparent: 'transparent', - current: 'currentColor', - ...values, - } + values = Object.assign( + { + inherit: 'inherit', + transparent: 'transparent', + current: 'currentColor', + }, + values, + ) } if (!candidate.value) { value = values.DEFAULT ?? null } else if (candidate.value.kind === 'arbitrary') { value = candidate.value.value - } else { - value = values[candidate.value.value] ?? null + } else if (values[candidate.value.value]) { + value = values[candidate.value.value] + } else if (values.__BARE_VALUE__) { + value = values.__BARE_VALUE__(candidate.value) ?? null + + isFraction = (candidate.value.fraction !== null && value?.includes('/')) ?? false } } - if (!value) return + if (value === null) return // Resolve the modifier value let modifier: string | null @@ -167,12 +190,12 @@ export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): Plug } // A modifier was provided but is invalid - if (candidate.modifier && !modifier) { + if (candidate.modifier && modifier === null && !isFraction) { // For arbitrary values, return `null` to avoid falling through to the next utility return candidate.value?.kind === 'arbitrary' ? null : undefined } - if (isColor && modifier) { + if (isColor && modifier !== null) { value = withAlpha(value, modifier) } @@ -186,27 +209,70 @@ export function buildPluginApi(designSystem: DesignSystem, ast: AstNode[]): Plug }) } }, + + theme: createThemeFn( + designSystem, + () => resolvedConfig.theme ?? {}, + (value) => value, + ), } } +export type CssInJs = { [key: string]: string | CssInJs } + +function objectToAst(obj: CssInJs): AstNode[] { + let ast: AstNode[] = [] + + for (let [name, value] of Object.entries(obj)) { + if (typeof value !== 'object') { + if (!name.startsWith('--') && value === '@slot') { + ast.push(rule(name, [rule('@slot', [])])) + } else { + // Convert camelCase to kebab-case: + // https://github.com/postcss/postcss-js/blob/b3db658b932b42f6ac14ca0b1d50f50c4569805b/parser.js#L30-L35 + name = name.replace(/([A-Z])/g, '-$1').toLowerCase() + + ast.push(decl(name, String(value))) + } + } else if (value !== null) { + ast.push(rule(name, objectToAst(value))) + } + } + + return ast +} + export function registerPlugins(plugins: Plugin[], designSystem: DesignSystem, ast: AstNode[]) { - let pluginApi = buildPluginApi(designSystem, ast) + let pluginObjects = [] for (let plugin of plugins) { if ('__isOptionsFunction' in plugin) { // Happens with `plugin.withOptions()` when no options were passed: // e.g. `require("my-plugin")` instead of `require("my-plugin")(options)` - plugin().handler(pluginApi) + pluginObjects.push(plugin()) } else if ('handler' in plugin) { // Happens with `plugin(…)`: // e.g. `require("my-plugin")` // // or with `plugin.withOptions()` when the user passed options: // e.g. `require("my-plugin")(options)` - plugin.handler(pluginApi) + pluginObjects.push(plugin) } else { // Just a plain function without using the plugin(…) API - plugin(pluginApi) + pluginObjects.push({ handler: plugin, config: {} as UserConfig }) } } + + // Now merge all the configs and make all that crap work + let resolvedConfig = resolveConfig(designSystem, [ + createCompatConfig(designSystem.theme), + ...pluginObjects.map(({ config }) => config ?? {}), + ]) + + let pluginApi = buildPluginApi(designSystem, ast, resolvedConfig) + + // Loop over the handlers and run them all with the resolved config + CSS theme probably somehow + for (let { handler } of pluginObjects) { + handler(pluginApi) + } } diff --git a/packages/tailwindcss/src/theme-fn.ts b/packages/tailwindcss/src/theme-fn.ts new file mode 100644 index 000000000..04665735c --- /dev/null +++ b/packages/tailwindcss/src/theme-fn.ts @@ -0,0 +1,156 @@ +import { deepMerge } from './compat/config/deep-merge' +import type { UserConfig } from './compat/config/types' +import type { DesignSystem } from './design-system' +import type { Theme } from './theme' +import { DefaultMap } from './utils/default-map' +import { toKeyPath } from './utils/to-key-path' + +export function createThemeFn( + designSystem: DesignSystem, + configTheme: () => UserConfig['theme'], + resolveValue: (value: any) => any, +) { + return function theme(path: string, defaultValue?: any) { + let keypath = toKeyPath(path) + let cssValue = readFromCss(designSystem.theme, keypath) + + if (typeof cssValue !== 'object') { + return cssValue + } + + let configValue = resolveValue(get(configTheme() ?? {}, keypath) ?? null) + + if (configValue !== null && typeof configValue === 'object') { + return deepMerge({}, [configValue, cssValue], (_, b) => b) + } + + // Values from CSS take precedence over values from the config + return cssValue ?? configValue ?? defaultValue + } +} + +function readFromCss(theme: Theme, path: string[]) { + type ThemeValue = + // A normal string value + | string + + // A nested tuple with additional data + | [main: string, extra: Record] + + let themeKey = path + // Escape dots used inside square brackets + // Replace camelCase with dashes + .map((part) => + part.replaceAll('.', '_').replace(/([a-z])([A-Z])/g, (_, a, b) => `${a}-${b.toLowerCase()}`), + ) + + // Remove the `DEFAULT` key at the end of a path + // We're reading from CSS anyway so it'll be a string + .filter((part, index) => part !== 'DEFAULT' || index !== path.length - 1) + .join('-') + + let map = new Map() + let nested = new DefaultMap>(() => new Map()) + + let ns = theme.resolveNamespace(`--${themeKey}` as any) + + if (ns.size === 0) { + return null + } + + for (let [key, value] of ns) { + // Non-nested values can be set directly + if (!key || !key.includes('--')) { + map.set(key, value) + continue + } + + // Nested values are stored separately + let nestedIndex = key.indexOf('--') + + let mainKey = key.slice(0, nestedIndex) + let nestedKey = key.slice(nestedIndex + 2) + + // Make `nestedKey` camel case: + nestedKey = nestedKey.replace(/-([a-z])/g, (_, a) => a.toUpperCase()) + + nested.get(mainKey === '' ? null : mainKey).set(nestedKey, value) + } + + for (let [key, extra] of nested) { + let value = map.get(key) + if (typeof value !== 'string') continue + + map.set(key, [value, Object.fromEntries(extra)]) + } + + // We have to turn the map into object-like structure for v3 compatibility + let obj = {} + let useNestedObjects = false // paths.some((path) => nestedKeys.has(path)) + + for (let [key, value] of map) { + key = key ?? 'DEFAULT' + + let path: string[] = [] + let splitIndex = key.indexOf('-') + + if (useNestedObjects && splitIndex !== -1) { + path.push(key.slice(0, splitIndex)) + path.push(key.slice(splitIndex + 1)) + } else { + path.push(key) + } + + set(obj, path, value) + } + + if ('DEFAULT' in obj) { + // The request looked like `theme('animation.DEFAULT')` and was turned into + // a lookup for `--animation-*` and we should extract the value for the + // `DEFAULT` key from the list of possible values + if (path[path.length - 1] === 'DEFAULT') { + return obj.DEFAULT + } + + // The request looked like `theme('animation.spin')` and was turned into a + // lookup for `--animation-spin-*` which had only one entry which means it + // should be returned directly + if (Object.keys(obj).length === 1) { + return obj.DEFAULT + } + } + + return obj +} + +function get(obj: any, path: string[]) { + for (let i = 0; i < path.length; ++i) { + let key = path[i] + + // The key does not exist so concatenate it with the next key + if (obj[key] === undefined) { + if (path[i + 1] === undefined) { + return undefined + } + + path[i + 1] = `${key}-${path[i + 1]}` + continue + } + + obj = obj[key] + } + + return obj +} + +function set(obj: any, path: string[], value: any) { + for (let key of path.slice(0, -1)) { + if (obj[key] === undefined) { + obj[key] = {} + } + + obj = obj[key] + } + + obj[path[path.length - 1]] = value +} diff --git a/packages/tailwindcss/src/theme.ts b/packages/tailwindcss/src/theme.ts index 7d150c350..fc14e507c 100644 --- a/packages/tailwindcss/src/theme.ts +++ b/packages/tailwindcss/src/theme.ts @@ -144,6 +144,21 @@ export class Theme { return values } + + resolveNamespace(namespace: string) { + let values = new Map() + let prefix = `${namespace}-` + + for (let [key, value] of this.values) { + if (key === namespace) { + values.set(null, value.isInline ? value.value : this.#var(key)!) + } else if (key.startsWith(prefix)) { + values.set(key.slice(prefix.length), value.isInline ? value.value : this.#var(key)!) + } + } + + return values + } } export type ThemeKey = @@ -255,6 +270,7 @@ export type ThemeKey = | '--translate' | '--width' | '--z-index' + | `--default-${string}` export type ColorThemeKey = | '--color' diff --git a/packages/tailwindcss/src/utilities.test.ts b/packages/tailwindcss/src/utilities.test.ts index 8880c8a46..a01e8473f 100644 --- a/packages/tailwindcss/src/utilities.test.ts +++ b/packages/tailwindcss/src/utilities.test.ts @@ -16092,7 +16092,7 @@ describe('legacy: matchUtilities', () => { `) }) - test('functional utilities with type: color and explicit modifiers', async () => { + test('functional utilities with explicit modifiers', async () => { async function run(candidates: string[]) { let compiled = await compile( css` diff --git a/packages/tailwindcss/src/utils/to-key-path.bench.ts b/packages/tailwindcss/src/utils/to-key-path.bench.ts new file mode 100644 index 000000000..e2a942762 --- /dev/null +++ b/packages/tailwindcss/src/utils/to-key-path.bench.ts @@ -0,0 +1,12 @@ +import { bench } from 'vitest' +import { toKeyPath } from './to-key-path' + +bench('toKeyPath', () => { + toKeyPath('fontSize.xs') + toKeyPath('fontSize.xs[1].lineHeight') + toKeyPath('colors.red.500') + toKeyPath('colors[red].500') + toKeyPath('colors[red].[500]') + toKeyPath('colors[red]500') + toKeyPath('colors[red][500]') +}) diff --git a/packages/tailwindcss/src/utils/to-key-path.test.ts b/packages/tailwindcss/src/utils/to-key-path.test.ts new file mode 100644 index 000000000..87056c20b --- /dev/null +++ b/packages/tailwindcss/src/utils/to-key-path.test.ts @@ -0,0 +1,13 @@ +import { expect, it } from 'vitest' +import { toKeyPath } from './to-key-path' + +it('can convert key paths to arrays', () => { + expect(toKeyPath('fontSize.xs')).toEqual(['fontSize', 'xs']) + expect(toKeyPath('fontSize.xs[1].lineHeight')).toEqual(['fontSize', 'xs', '1', 'lineHeight']) + expect(toKeyPath('colors.red.500')).toEqual(['colors', 'red', '500']) + expect(toKeyPath('colors[red].500')).toEqual(['colors', 'red', '500']) + expect(toKeyPath('colors[red].[500]')).toEqual(['colors', 'red', '500']) + expect(toKeyPath('colors[red]500')).toEqual(['colors', 'red', '500']) + expect(toKeyPath('colors[red][500]')).toEqual(['colors', 'red', '500']) + expect(toKeyPath('colors[red]500[50]5')).toEqual(['colors', 'red', '500', '50', '5']) +}) diff --git a/packages/tailwindcss/src/utils/to-key-path.ts b/packages/tailwindcss/src/utils/to-key-path.ts new file mode 100644 index 000000000..40334612e --- /dev/null +++ b/packages/tailwindcss/src/utils/to-key-path.ts @@ -0,0 +1,54 @@ +import { segment } from './segment' + +/** + * Parse a path string into an array of path segments + * + * Square bracket notation `a[b]` may be used to "escape" dots that would + * otherwise be interpreted as path separators. + * + * Example: + * a -> ['a'] + * a.b.c -> ['a', 'b', 'c'] + * a[b].c -> ['a', 'b', 'c'] + * a[b.c].e.f -> ['a', 'b.c', 'e', 'f'] + * a[b][c][d] -> ['a', 'b', 'c', 'd'] + * + * @param {string} path + **/ +export function toKeyPath(path: string) { + let keypath: string[] = [] + + for (let part of segment(path, '.')) { + if (!part.includes('[')) { + keypath.push(part) + continue + } + + let currentIndex = 0 + + while (true) { + let bracketL = part.indexOf('[', currentIndex) + let bracketR = part.indexOf(']', bracketL) + + if (bracketL === -1 || bracketR === -1) { + break + } + + // Add the part before the bracket as a key + if (bracketL > currentIndex) { + keypath.push(part.slice(currentIndex, bracketL)) + } + + // Add the part inside the bracket as a key + keypath.push(part.slice(bracketL + 1, bracketR)) + currentIndex = bracketR + 1 + } + + // Add the part after the last bracket as a key + if (currentIndex <= part.length - 1) { + keypath.push(part.slice(currentIndex)) + } + } + + return keypath +}