fix(theme): keep variants when replacing slot classes in app config

[benjamincanac]

🔗 Linked issue

Resolves #6800

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

A function slot value in app.config.ui used to replace the slot's fully resolved classes, so it also dropped everything the variants and compoundVariants contribute. Copying the default theme classes into a replacer produced an unstyled component, which is what #6800 reports.

Construction-time replacers are now resolved when the tv config is built: the slot is blanked on the extend side and the replacer's result takes the place of the slot's own classes, so variants keep merging on top, the same as with a plain string. The defaults argument the replacer receives is now the slot's own theme classes instead of the resolved chain, and (defaults) => defaults stays a no-op.

The ui and class props are unchanged, they run after variant resolution so a function there still replaces the resolved output. Docs now spell out the difference.

This also removes the call-time directives path entirely, so slots with an app config replacer are memoized again like any other slot.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[codspeed-hq]

Merging this PR will improve performance by 17.54%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
✅ 30 untouched benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	button (~6 slots)	446 µs	379.5 µs	+17.54%

Tip

Curious why this is faster? Comment @codspeedbot explain why this is faster on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing fix/config-slot-replacer-variants (aab7edd) with v4 (795c353)}

[pkg-pr-new]

npm i https://pkg.pr.new/@nuxt/ui@6824

commit: aab7edd

[coderabbitai]

📝 Walkthrough

Walkthrough

The change separates construction-time replacers from call-time replacers. Configuration functions now resolve theme classes before createTV, while variants and compound variants remain applicable. Invocation-time class and className functions replace fully resolved classes. Documentation, type comments, and tests describe and verify these semantics.

Estimated code review effort: 4 (Complex) | ~45 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the fix for preserving variant classes when replacing slot classes through app configuration.
Description check	✅ Passed	The description accurately explains the bug, implementation, behavior of ui and class props, documentation updates, and linked issue.
Linked Issues check	✅ Passed	The changes satisfy issue #6800 by preserving variant and compound-variant classes for app-config slot replacers and documenting the behavior.
Out of Scope Changes check	✅ Passed	The implementation, tests, type documentation, and user documentation are all directly related to the linked issue and stated objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/config-slot-replacer-variants

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

src/runtime/types/tv.ts

Parsing error: Unexpected token {

src/runtime/utils/tv.ts

Parsing error: Unexpected token {

test/utils/tv.spec.ts

Parsing error: Unexpected token as

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/runtime/types/tv.ts`:
- Around line 5-9: The call-time replacer documentation must clarify that it
replaces resolved classes, while accompanying plain classes still merge into the
result. Update src/runtime/types/tv.ts lines 5-9 and
docs/content/docs/1.getting-started/5.theme/3.components.md lines 406-408,
replacing the claim that returned classes are the only ones left with this
qualification.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 499cceaa-fb88-4f93-ba2b-785196a025ad

📥 Commits

Reviewing files that changed from the base of the PR and between 795c353 and aab7edd.

📒 Files selected for processing (5)

• docs/content/docs/1.getting-started/5.theme/3.components.md
• skills/nuxt-ui/references/guidelines/design-system.md
• src/runtime/types/tv.ts
• src/runtime/utils/tv.ts
• test/utils/tv.spec.ts

[coderabbitai]

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Document plain classes supplied with a call-time replacer.

A call-time replacer removes the resolved class chain. It does not remove plain values supplied alongside the replacer. For example, [() => 'text-xl', 'opacity-50'] resolves to both classes.

• src/runtime/types/tv.ts#L5-L9: state that the replacer replaces resolved classes, while accompanying plain classes still merge.
• docs/content/docs/1.getting-started/5.theme/3.components.md#L406-L408: replace “the returned classes are the only ones left” with the same qualification.

📍 Affects 2 files

• src/runtime/types/tv.ts#L5-L9 (this comment)
• docs/content/docs/1.getting-started/5.theme/3.components.md#L406-L408

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/runtime/types/tv.ts` around lines 5 - 9, The call-time replacer
documentation must clarify that it replaces resolved classes, while accompanying
plain classes still merge into the result. Update src/runtime/types/tv.ts lines
5-9 and docs/content/docs/1.getting-started/5.theme/3.components.md lines
406-408, replacing the claim that returned classes are the only ones left with
this qualification.