@dashforge/tw: <Stack className='…'> destroys internal flex/gap classes via tailwind-merge (G-28)

[kensaadi]

Symptom

@dashforge/tw <Stack direction="column" gap="3" className="…"> renders as display: block with NO gap and NO flex-direction applied — the internal flex flex-col gap-* classes are lost. The final computed style is display: block; row-gap: normal; flex-direction: row;, children flush.

Verified in browser preview:

• <Stack direction="column" gap="3"> alone → renders correctly (flex flex-col gap-3)
• <Stack direction="column" gap="3" className="min-h-0"> → flex flex-col gap-3 disappear during tailwind-merge

Why this is bad

• Consumer expects className to be additive (standard React pattern)
• Silent-fail: no error, no visual hint until you notice children have no gap
• Forces consumers to swap <Stack> for <div className="flex flex-col gap-2 …"> — defeats the purpose of using the primitive

Discovered while

Refactoring PalettePanel.CategoryContent in the Blueprint Builder V2 shell. Filed in Blueprint's dogfood report as G-28 (severity: medium — silent-fail via tailwind-merge collision).

Workaround applied in Blueprint

Replaced <Stack> with raw <div className="flex flex-col gap-2"> at every collision site.

Acceptance (pick one)

• Option A — preserve internal classes: fix the tailwind-merge config so flex, flex-col, gap-* are preserved when the consumer's className collides on unrelated utilities
• Option B — restricted API: forbid free-form className on <Stack> and require slotProps.root.className (consistent with the [1.2.0] Component Defaults System — theme.components + slotProps (Option C) #60 Option C slot pattern)
• Dev-only assertion: if the final computed display of the Stack root is not flex, console.warn in development with a hint
• Regression test: <Stack className="min-h-0" direction="column" gap="3"> computed style must be display: flex; flex-direction: column; row-gap: <value>

Related

• Same class of bug likely affects other layout primitives that use tailwind-variants (Flex, Container, Divider — worth an audit)
• [1.2.0] Component Defaults System — theme.components + slotProps (Option C) #60 Option C: the slotProps pattern is the long-term fix; adopt Option B if [1.2.0] Component Defaults System — theme.components + slotProps (Option C) #60 lands first

[kensaadi]

Shipped in 68efee5.

Root cause was not tailwind-merge — it was JSX prop-override. All five affected layout primitives (Stack, Container, Grid, Box, Divider) had their variant-computed className={classes} declared BEFORE the {...rest} DOM spread. A stray className on rest therefore took the last-wins JSX slot and clobbered the entire variant chain (flex flex-col gap-3 in the reported repro, but every variant-driven utility on any of the five primitives had the same exposure).

The interface types already Omit-exclude className on all five, so TS-strict consumers can't reach this path. The Blueprint repro landed via a TS-loose call site or an untyped downstream spread (<Stack {...anyProps} />) — the runtime had no defense.

The fix on each primitive: destructure className out of rest (with a cast, since the type declares no such property), feed it into the cn(…) chain so tailwind-merge preserves non-conflicting utilities alongside the variants, and spread the residual safeRest onto the DOM. Precedence stays: variants → smuggled className → sx, with tailwind-merge's later-wins semantics — so sx still wins over both variants and the smuggled className, matching the Dashforge idiom.

Which acceptance option was picked: Option A (preserve internal classes). Option B (forbid className and require slotProps.root.className) would break the Blueprint case and every future untyped consumer; the runtime safety-net is quieter and back-compat.

Not shipped:

• Dev-only assertion / console.warn — decided against. The runtime now silently merges instead of clobbering, so there is no visible failure mode to warn about. If we want to nudge consumers toward sx in future, that goes in the docs, not a warning.
• Option B (slotProps.root.className) — Option A obsoletes it for these five components.

Tests: 10 new regression tests covering all three failure modes per component (variant survival, tailwind-merge collision resolution, no JSX prop-override recurrence).

• Stack: 3 tests — variant preservation, colliding gap-6 vs variant gap-3, DOM sanity.
• Container: 1 test — variant preservation.
• Grid: 2 tests — container branch + item branch of the discriminated union.
• Box: 1 test — variant preservation.
• Divider: 3 tests — horizontal line, vertical line, labeled.

Full @dashforge/tw suite: 109 files / 1686 tests pass, 1 skipped, 0 fail (was 1676 before, +10 from the new tests). Zero regression on pre-existing specs.

Adjacent risk: layout primitives that use tailwind-variants were the specific concern in the issue. All five in that category are now guarded. Flex is not shipped (see #60 EVOLVE — expand Stack instead), and all other tw components already write className={classes} in ways that either don't accept unstructured spreads or handle them explicitly.