@urbicon-ui/blocks 6.19.3 → 6.21.1

package/dist/utils/variants.js

@@ -2,8 +2,9 @@
 // ─── cx: class concatenation ─────────────────────────────────────────────────
 /**
  * Concatenate class inputs into a single string. Accepts strings, nested
- * arrays, and falsy values (filtered out). Trims and joins with single
- * spaces.
+ * arrays, `{ class: condition }` records (Svelte 5 `ClassValue` / clsx
+ * shape — keys with truthy values are included) and falsy values (filtered
+ * out). Trims and joins with single spaces.
  *
  * Note: `cx()` does **not** deduplicate — `cx('foo', 'foo bar')` returns
  * `'foo foo bar'`. Duplicate Tailwind classes are harmless at runtime
@@ -20,11 +21,24 @@ export function cx(...inputs) {
             if (trimmed)
                 parts.push(trimmed);
         }
+        else if (typeof input === 'number') {
+            // clsx/ClassValue parity: numbers stringify (0 is already filtered).
+            parts.push(String(input));
+        }
         else if (Array.isArray(input)) {
             const nested = cx(...input);
             if (nested)
                 parts.push(nested);
         }
+        else if (typeof input === 'object') {
+            for (const key of Object.keys(input)) {
+                if (!input[key])
+                    continue;
+                const trimmed = key.trim();
+                if (trimmed)
+                    parts.push(trimmed);
+            }
+        }
     }
     return parts.join(' ');
 }
@@ -53,27 +67,34 @@ const BUCKET_PATTERNS = [
     // Flex / Grid
     [/^flex-(row|col|row-reverse|col-reverse)$/, 'flex-direction'],
     [/^flex-(wrap|nowrap|wrap-reverse)$/, 'flex-wrap'],
-    [/^flex-(1|auto|initial|none)$/, 'flex'],
-    [/^grow(-0|-\[.+\])?$/, 'flex-grow'],
-    [/^shrink(-0|-\[.+\])?$/, 'flex-shrink'],
+    // v4 accepts any integer (`flex-2`) and arbitrary values (`flex-[2_2_0%]`).
+    [/^flex-(\d+|auto|initial|none|\[[^\]]+\])$/, 'flex'],
+    [/^grow(-\d+|-\[.+\])?$/, 'flex-grow'],
+    [/^shrink(-\d+|-\[.+\])?$/, 'flex-shrink'],
     [/^basis-/, 'flex-basis'],
     [/^order-/, 'order'],
-    [/^items-(start|end|center|baseline|stretch)$/, 'align-items'],
+    [/^items-(start|end|center|baseline|baseline-last|stretch)$/, 'align-items'],
     [/^justify-(start|end|center|between|around|evenly|normal|stretch)$/, 'justify-content'],
-    [/^justify-items-(start|end|center|stretch)$/, 'justify-items'],
+    [/^justify-items-(start|end|center|stretch|normal)$/, 'justify-items'],
     [/^justify-self-(auto|start|end|center|stretch)$/, 'justify-self'],
     [/^content-(start|end|center|between|around|evenly|baseline|stretch|normal)$/, 'align-content'],
-    [/^self-(auto|start|end|center|stretch|baseline)$/, 'align-self'],
+    [/^self-(auto|start|end|center|stretch|baseline|baseline-last)$/, 'align-self'],
     [/^place-content-/, 'place-content'],
     [/^place-items-/, 'place-items'],
     [/^place-self-/, 'place-self'],
     [/^grid-cols-/, 'grid-template-columns'],
     [/^grid-rows-/, 'grid-template-rows'],
+    [/^grid-flow-/, 'grid-auto-flow'],
+    // grid-column vs -start vs -end are three CSS properties — `col-span-2`
+    // must not conflict with `col-start-3`.
+    [/^col-start-/, 'grid-column-start'],
+    [/^col-end-/, 'grid-column-end'],
     [/^col-/, 'grid-column'],
+    [/^row-start-/, 'grid-row-start'],
+    [/^row-end-/, 'grid-row-end'],
     [/^row-/, 'grid-row'],
     [/^auto-cols-/, 'grid-auto-columns'],
     [/^auto-rows-/, 'grid-auto-rows'],
-    [/^auto-flow-/, 'grid-auto-flow'],
     // Sizing — width / height
     [/^min-w-/, 'min-w'],
     [/^min-h-/, 'min-h'],
@@ -103,13 +124,27 @@ const BUCKET_PATTERNS = [
     [/^ms-/, 'ms'],
     [/^me-/, 'me'],
     [/^m-/, 'm'],
-    // Gap / space-between
+    // Gap / space-between / divide
     [/^gap-x-/, 'gap-x'],
     [/^gap-y-/, 'gap-y'],
     [/^gap-/, 'gap'],
+    [/^space-x-reverse$/, 'space-x-reverse'],
+    [/^space-y-reverse$/, 'space-y-reverse'],
     [/^space-x-/, 'space-x'],
     [/^space-y-/, 'space-y'],
-    // Position offsets
+    // divide-* — width / style / color are orthogonal properties.
+    [/^divide-(x|y)-reverse$/, (m) => `divide-${m[1]}-reverse`],
+    [/^divide-(x|y)(-(\d+|\[[^\]]+\]))?$/, (m) => `divide-${m[1]}-width`],
+    [/^divide-(solid|dashed|dotted|double|none)$/, 'divide-style'],
+    [/^divide-/, 'divide-color'],
+    // Position offsets. v4.1 inset-shadow-* / inset-ring-* must not fall into
+    // the `inset-` position bucket.
+    [/^inset-shadow-\[/, 'inset-shadow'],
+    [/^inset-shadow-(2xs|xs|sm|none)$/, 'inset-shadow'],
+    [/^inset-shadow$/, 'inset-shadow'],
+    [/^inset-shadow-/, 'inset-shadow-color'],
+    [/^inset-ring(-\d+|-\[[^\]]+\])?$/, 'inset-ring-width'],
+    [/^inset-ring-/, 'inset-ring-color'],
     [/^inset-x-/, 'inset-x'],
     [/^inset-y-/, 'inset-y'],
     [/^inset-/, 'inset'],
@@ -136,6 +171,11 @@ const BUCKET_PATTERNS = [
     [/^rounded-s(-|$)/, 'rounded-s'],
     [/^rounded-e(-|$)/, 'rounded-e'],
     [/^rounded(-|$)/, 'rounded'],
+    // border-collapse / border-spacing are table-layout properties, not colors.
+    [/^border-(collapse|separate)$/, 'border-collapse'],
+    [/^border-spacing-x-/, 'border-spacing-x'],
+    [/^border-spacing-y-/, 'border-spacing-y'],
+    [/^border-spacing-/, 'border-spacing'],
     // Border style (must come before width/color)
     [/^border-(solid|dashed|dotted|double|hidden|none)$/, 'border-style'],
     // Border width — `border`, `border-1`, `border-2`, `border-[3px]` (Tailwind v4 accepts any integer)
@@ -145,10 +185,12 @@ const BUCKET_PATTERNS = [
     // Border color (catch-all, e.g. `border-red-500`, `border-primary`, `border-border-subtle`)
     [/^border-(x|y|t|r|b|l|s|e)-/, (m) => `border-${m[1]}-color`],
     [/^border-/, 'border-color'],
-    // Outline / ring
-    [/^outline-(none|dashed|dotted|double|hidden)$/, 'outline-style'],
+    // Outline / ring. In v4 bare `outline` sets outline-style: solid — it is a
+    // style, not a width.
+    [/^outline-(solid|dashed|dotted|double|none|hidden)$/, 'outline-style'],
+    [/^outline$/, 'outline-style'],
     [/^outline-offset-/, 'outline-offset'],
-    [/^outline(-\d+|-\[[^\]]+\])?$/, 'outline-width'],
+    [/^outline(-\d+|-\[[^\]]+\])$/, 'outline-width'],
     [/^outline-/, 'outline-color'],
     [/^ring-offset-(\d+|\[[^\]]+\])$/, 'ring-offset-width'],
     [/^ring-offset-/, 'ring-offset-color'],
@@ -162,30 +204,58 @@ const BUCKET_PATTERNS = [
     [/^bg-clip-/, 'bg-clip'],
     [/^bg-origin-/, 'bg-origin'],
     [
-        /^bg-(top|right|bottom|left|center|left-top|left-bottom|right-top|right-bottom)$/,
+        /^bg-(top|right|bottom|left|center|left-top|left-bottom|right-top|right-bottom|top-left|top-right|bottom-left|bottom-right)$/,
         'bg-position'
     ],
+    // Data-type hints and image-valued arbitraries must not read as bg-color —
+    // background-image and background-color are independent CSS properties
+    // (a gradient overlay must never strip the color underneath, see the
+    // Skeleton wave shimmer and Progress striped fill).
+    [/^bg-\[(?:length|size):/, 'bg-size'],
+    [/^bg-\[position:/, 'bg-position'],
+    [/^bg-\[(?:image:|url\(|linear-gradient\(|radial-gradient\(|conic-gradient\()/, 'bg-image'],
+    [/^bg-\[color:/, 'bg-color'],
+    [/^bg-position-/, 'bg-position'],
+    [/^bg-size-/, 'bg-size'],
+    [/^bg-(?:linear|radial|conic)(-|$)/, 'bg-image'],
     [/^bg-gradient-to-/, 'bg-image'],
+    [/^bg-none$/, 'bg-image'],
     [/^bg-/, 'bg-color'],
     [/^from-/, 'gradient-from'],
     [/^via-/, 'gradient-via'],
     [/^to-/, 'gradient-to'],
     // Text — size / align / weight / color (specific first). v4 size+leading shorthand: `text-sm/6`, `text-base/relaxed`.
+    // v4.1 text-shadow-* must not read as text-color — and like `shadow`,
+    // the named size scale is finite; other single-word values are colors
+    // (`text-shadow-white` must not strip `text-shadow-lg`).
+    [/^text-shadow-\[/, 'text-shadow'],
+    [/^text-shadow-(2xs|xs|sm|md|lg|none)$/, 'text-shadow'],
+    [/^text-shadow$/, 'text-shadow'],
+    [/^text-shadow-/, 'text-shadow-color'],
     [/^text-(xs|sm|base|lg|xl|\d+xl)(\/[\w.-]+)?$/, 'text-size'],
+    // Data-type hints disambiguate the overloaded `text-` arbitraries.
+    [/^text-\[length:/, 'text-size'],
+    [/^text-\[color:/, 'text-color'],
     // Arbitrary text-size values starting with a digit (e.g. `text-[11px]`,
     // `text-[1.5rem]`). Hex/named values like `text-[#fff]` / `text-[var(--x)]`
     // still fall through to the text-color catch-all below.
     [/^text-\[[0-9.]/, 'text-size'],
     [/^text-(left|center|right|justify|start|end)$/, 'text-align'],
-    [/^text-(ellipsis|clip|wrap|nowrap|balance|pretty)$/, 'text-overflow'],
+    // text-overflow (ellipsis/clip) and text-wrap (wrap/nowrap/balance/pretty)
+    // are different CSS properties — a wrap override must not strip ellipsis'
+    // sibling and vice versa.
+    [/^text-(ellipsis|clip)$/, 'text-overflow'],
+    [/^text-(wrap|nowrap|balance|pretty)$/, 'text-wrap'],
     [/^text-(current|inherit|transparent)$/, 'text-color'],
     [/^text-/, 'text-color'],
     [/^font-(thin|extralight|light|normal|medium|semibold|bold|extrabold|black)$/, 'font-weight'],
+    [/^font-stretch-/, 'font-stretch'],
     [/^font-(sans|serif|mono)$/, 'font-family'],
     [/^font-/, 'font-family'],
     [/^italic$|^not-italic$/, 'font-style'],
     [/^tracking-/, 'letter-spacing'],
     [/^leading-/, 'line-height'],
+    [/^line-clamp-/, 'line-clamp'],
     [/^underline$|^overline$|^line-through$|^no-underline$/, 'text-decoration'],
     // text-decoration sub-properties are orthogonal CSS — three separate buckets.
     // Order matters: style names first, then thickness (numeric/arbitrary), then color catch-all.
@@ -201,8 +271,10 @@ const BUCKET_PATTERNS = [
     [/^align-(baseline|top|middle|bottom|text-top|text-bottom|sub|super)$/, 'vertical-align'],
     // Effects
     [/^opacity-/, 'opacity'],
-    [/^shadow-(inner|none)$/, 'shadow'],
-    [/^shadow(-\w+)?$/, 'shadow'],
+    // Named shadow scale is finite; any other `shadow-<word>` is a color
+    // (`shadow-primary` must not strip `shadow-md`).
+    [/^shadow-(2xs|xs|sm|md|lg|xl|2xl|inner|none)$/, 'shadow'],
+    [/^shadow$/, 'shadow'],
     [/^shadow-\[/, 'shadow'],
     [/^shadow-/, 'shadow-color'],
     [/^blur(-\w+)?$/, 'blur'],
@@ -220,13 +292,20 @@ const BUCKET_PATTERNS = [
     [/^scale-x-/, 'scale-x'],
     [/^scale-y-/, 'scale-y'],
     [/^scale-/, 'scale'],
+    // v4 3D rotate axes are orthogonal to plain rotate.
+    [/^rotate-(x|y|z)-/, (m) => `rotate-${m[1]}`],
     [/^rotate-/, 'rotate'],
     [/^translate-x-/, 'translate-x'],
     [/^translate-y-/, 'translate-y'],
+    [/^translate-z-/, 'translate-z'],
+    // v4 plain `translate-*` sets both axes.
+    [/^translate-/, 'translate'],
     [/^skew-x-/, 'skew-x'],
     [/^skew-y-/, 'skew-y'],
     [/^origin-/, 'transform-origin'],
-    // Transitions / animations
+    // Transitions / animations. v4 transition-behavior must not conflict with
+    // transition-property (`transition-discrete` composes with `transition-colors`).
+    [/^transition-(discrete|normal)$/, 'transition-behavior'],
     [/^transition(-\w+)?$/, 'transition'],
     [/^transition-\[/, 'transition'],
     [/^duration-/, 'transition-duration'],
@@ -239,6 +318,37 @@ const BUCKET_PATTERNS = [
     [/^accent-/, 'accent-color'],
     [/^caret-/, 'caret-color']
 ];
+// Arbitrary CSS properties whose utility twin should share a bucket, so
+// `[gap:inherit]` and `gap-4` resolve against each other (Codeberg #21).
+// Everything else buckets as `@<property>` — same-property arbitraries
+// conflict, utilities stay untouched (twMerge behaves the same way).
+const ARBITRARY_PROP_ALIAS = {
+    gap: 'gap',
+    'column-gap': 'gap-x',
+    'row-gap': 'gap-y',
+    transform: 'transform'
+};
+const ARBITRARY_PROP_PATTERN = /^\[((?:--)?[a-zA-Z][a-zA-Z0-9-]*):.+\]$/;
+/**
+ * Index of the last `:` outside any `[]`/`()` nesting, or -1. This is the
+ * modifier/base boundary: colons inside arbitrary values (`bg-[url(https://…)]`),
+ * arbitrary properties (`[gap:inherit]`) and selector modifiers
+ * (`supports-[display:grid]:grid`) must not split the class.
+ */
+function lastTopLevelColon(cls) {
+    let depth = 0;
+    let last = -1;
+    for (let i = 0; i < cls.length; i++) {
+        const ch = cls[i];
+        if (ch === '[' || ch === '(')
+            depth++;
+        else if (ch === ']' || ch === ')')
+            depth = depth > 0 ? depth - 1 : 0;
+        else if (ch === ':' && depth === 0)
+            last = i;
+    }
+    return last;
+}
 /**
  * Returns the conflict-bucket key of a Tailwind class, or `null` if the class
  * does not match any catalogued utility family. Unknown classes never conflict.
@@ -246,8 +356,10 @@ const BUCKET_PATTERNS = [
  * Modifier prefixes are part of the key — `hover:bg-red` returns `hover:bg-color`
  * while `bg-red` returns `bg-color`. The two never strip each other. `!`-important
  * is normalized away entirely so `!bg-red` and `bg-red` share a bucket.
+ * Arbitrary properties bucket per property name (`[gap:inherit]` → `gap`,
+ * `[--spinner-speed:1s]` → `@--spinner-speed`).
  *
- * Results are memoized per process — `tailwindBucket` is called O(stages × classes)
+ * Results are memoized per process — `tailwindBucket` is called O(sources × classes)
  * per `tv()` resolve, and the same handful of class strings appear thousands of
  * times across a render tree. Cap kept high enough for any realistic application
  * surface; values are short and the map never frees.
@@ -255,11 +367,13 @@ const BUCKET_PATTERNS = [
 const BUCKET_CACHE = new Map();
 const BUCKET_CACHE_MAX = 4096;
 function tailwindBucket(cls) {
+    // Stored values are `string | null`, never `undefined` — a single lookup
+    // distinguishes hit from miss.
     const cached = BUCKET_CACHE.get(cls);
-    if (cached !== undefined || BUCKET_CACHE.has(cls))
+    if (cached !== undefined)
         return cached;
     // Split off all modifier prefixes (`hover:focus-visible:dark:md:bg-red`).
-    const lastColon = cls.lastIndexOf(':');
+    const lastColon = lastTopLevelColon(cls);
     let modifiers = lastColon >= 0 ? cls.slice(0, lastColon + 1) : '';
     let base = lastColon >= 0 ? cls.slice(lastColon + 1) : cls;
     // Strip `!`-important markers — Tailwind v3 leading (`!bg-red`, `hover:!bg-red`)
@@ -273,23 +387,103 @@ function tailwindBucket(cls) {
     if (base.endsWith('!'))
         base = base.slice(0, -1);
     // Negative spacing like `-mx-2` shares its bucket with `mx-2`.
-    if (base.startsWith('-'))
+    if (base.startsWith('-') && !base.startsWith('-['))
         base = base.slice(1);
     let result = null;
-    for (const [pattern, key] of BUCKET_PATTERNS) {
-        const match = base.match(pattern);
-        if (match) {
-            const bucketKey = typeof key === 'string' ? key : key(match);
-            result = modifiers + bucketKey;
-            break;
+    const arbitraryProp = base.match(ARBITRARY_PROP_PATTERN);
+    if (arbitraryProp) {
+        const prop = arbitraryProp[1];
+        result = modifiers + (ARBITRARY_PROP_ALIAS[prop] ?? `@${prop}`);
+    }
+    else {
+        for (const [pattern, key] of BUCKET_PATTERNS) {
+            const match = base.match(pattern);
+            if (match) {
+                const bucketKey = typeof key === 'string' ? key : key(match);
+                result = modifiers + bucketKey;
+                break;
+            }
         }
     }
     if (BUCKET_CACHE.size < BUCKET_CACHE_MAX)
         BUCKET_CACHE.set(cls, result);
     return result;
 }
+// Directional shorthand dominance: a LATER class in bucket K also strips
+// earlier classes in DOMINANCE[K]. Longhands never strip their shorthand —
+// a later `pl-2` composes with an earlier `p-4` (Tailwind's own cascade
+// resolves the left side), but a later `p-0` fully replaces earlier `px-4`
+// or `pl-10`, matching what the override author means.
+//
+// Deliberately absent: `text-size` → `line-height`. The library pairs a
+// slot-base `leading-*` with axis-supplied `text-*` across sources by
+// design (labels, timeline meta, table cells) — stripping the leading would
+// silently change typography; leading-* also wins Tailwind's own cascade.
+const DOMINANCE = {
+    p: ['px', 'py', 'ps', 'pe', 'pt', 'pr', 'pb', 'pl'],
+    px: ['pr', 'pl'],
+    py: ['pt', 'pb'],
+    m: ['mx', 'my', 'ms', 'me', 'mt', 'mr', 'mb', 'ml'],
+    mx: ['mr', 'ml'],
+    my: ['mt', 'mb'],
+    inset: ['inset-x', 'inset-y', 'start', 'end', 'top', 'right', 'bottom', 'left'],
+    'inset-x': ['right', 'left'],
+    'inset-y': ['top', 'bottom'],
+    size: ['w', 'h'],
+    gap: ['gap-x', 'gap-y'],
+    rounded: [
+        'rounded-tl',
+        'rounded-tr',
+        'rounded-bl',
+        'rounded-br',
+        'rounded-ss',
+        'rounded-se',
+        'rounded-es',
+        'rounded-ee',
+        'rounded-t',
+        'rounded-r',
+        'rounded-b',
+        'rounded-l',
+        'rounded-s',
+        'rounded-e'
+    ],
+    'rounded-t': ['rounded-tl', 'rounded-tr'],
+    'rounded-r': ['rounded-tr', 'rounded-br'],
+    'rounded-b': ['rounded-bl', 'rounded-br'],
+    'rounded-l': ['rounded-tl', 'rounded-bl'],
+    'rounded-s': ['rounded-ss', 'rounded-es'],
+    'rounded-e': ['rounded-se', 'rounded-ee'],
+    'border-width': [
+        'border-x-width',
+        'border-y-width',
+        'border-s-width',
+        'border-e-width',
+        'border-t-width',
+        'border-r-width',
+        'border-b-width',
+        'border-l-width'
+    ],
+    'border-x-width': ['border-r-width', 'border-l-width'],
+    'border-y-width': ['border-t-width', 'border-b-width'],
+    'border-color': [
+        'border-x-color',
+        'border-y-color',
+        'border-s-color',
+        'border-e-color',
+        'border-t-color',
+        'border-r-color',
+        'border-b-color',
+        'border-l-color'
+    ],
+    'border-x-color': ['border-r-color', 'border-l-color'],
+    'border-y-color': ['border-t-color', 'border-b-color'],
+    overflow: ['overflow-x', 'overflow-y'],
+    scale: ['scale-x', 'scale-y'],
+    translate: ['translate-x', 'translate-y', 'translate-z']
+};
 /**
- * Removes classes from `prior` whose conflict-bucket appears in `current`.
+ * Removes classes from `prior` whose conflict-bucket appears in `current`,
+ * including buckets a later shorthand dominates (`p-0` strips `px-4`).
  * Stable order preserved within each side.
  */
 function stripConflicts(prior, current) {
@@ -298,8 +492,19 @@ function stripConflicts(prior, current) {
     const used = new Set();
     for (const cls of current) {
         const b = tailwindBucket(cls);
-        if (b)
-            used.add(b);
+        if (!b)
+            continue;
+        used.add(b);
+        // Dominance expansion keeps the modifier prefix: `hover:p` dominates
+        // `hover:px`, never the plain-state `px`. Bucket keys contain no `:`,
+        // so the last colon is the modifier boundary.
+        const keyStart = b.lastIndexOf(':') + 1;
+        const dominated = DOMINANCE[b.slice(keyStart)];
+        if (dominated) {
+            const mods = b.slice(0, keyStart);
+            for (const d of dominated)
+                used.add(mods + d);
+        }
     }
     if (used.size === 0)
         return prior;
@@ -308,6 +513,25 @@ function stripConflicts(prior, current) {
         return b == null || !used.has(b);
     });
 }
+/**
+ * Folds an ordered list of class-token sources into one list: each source
+ * strips the accumulated earlier sources' conflicting buckets, then appends
+ * its own tokens. The last source therefore wins per bucket — deterministic,
+ * independent of stylesheet order.
+ *
+ * Within a single source, order is preserved and same-bucket pairs fall
+ * through to the CSS cascade — author-controlled pairings inside one class
+ * string (`rounded-md rounded-t-none`) stay intact.
+ */
+function foldSources(sources) {
+    let acc = [];
+    for (const tokens of sources) {
+        if (tokens.length === 0)
+            continue;
+        acc = acc.length === 0 ? tokens : [...stripConflicts(acc, tokens), ...tokens];
+    }
+    return acc;
+}
 /**
  * Tokenize a class-string into individual class tokens. Whitespace-only
  * fragments and empty strings are filtered.
@@ -364,7 +588,7 @@ function stripUndefined(obj) {
 }
 export function matchesCompound(compound, effectiveProps) {
     for (const key of Object.keys(compound)) {
-        if (key === 'class' || key === 'className')
+        if (key === 'class')
             continue;
         const constraint = compound[key];
         const propValue = falsyToString(effectiveProps[key]);
@@ -388,111 +612,188 @@ function resolveClassValue(value) {
         return cx(...value);
     return '';
 }
+/**
+ * Config-time validation — every violation here is a programming error in a
+ * `*.variants.ts` (or a consumer's own tv() call), so it throws immediately
+ * at module init instead of degrading silently at render time. The compile-
+ * time layer (ValidSlotVariants, VariantPropsMap) catches the same class of
+ * mistakes for literal configs; this covers JS consumers and values built
+ * from imported constants.
+ */
+function validateTvConfig(config) {
+    const { base, slots, variants = {}, compoundVariants = [], defaultVariants = {} } = config;
+    const slotNames = slots != null && Object.keys(slots).length > 0 ? Object.keys(slots) : null;
+    if (slotNames && base != null) {
+        // Fail loud instead of the historical silent drop (base only ever
+        // reached a slot literally named 'base').
+        throw new Error('tv(): `base` and `slots` are mutually exclusive — declare the primary slot as `slots.base` instead.');
+    }
+    const requireBaseSlot = (context) => {
+        if (slotNames && !slotNames.includes('base')) {
+            throw new Error(`tv(): ${context} is a plain class value, which routes to the 'base' slot — but no slot named 'base' is declared.`);
+        }
+    };
+    // Leaf values must bottom out in class strings (nested arrays allowed,
+    // falsy entries tolerated for conditional-array patterns). Objects inside
+    // arrays and scalar garbage would silently render as '' — or worse, leak
+    // through cx()'s record form as literal slot-name classes — so they throw.
+    const checkClassLeaf = (value, context) => {
+        if (value == null || value === false)
+            return;
+        if (typeof value === 'string')
+            return;
+        if (Array.isArray(value)) {
+            for (const [i, v] of value.entries()) {
+                checkClassLeaf(v, `${context}[${i}]`);
+            }
+            return;
+        }
+        throw new Error(`tv(): ${context} must be a class string (or nested array of strings), got ${typeof value}.`);
+    };
+    const checkSlotKeys = (value, context) => {
+        if (value == null)
+            return;
+        if (typeof value === 'string' || Array.isArray(value)) {
+            if (slotNames)
+                requireBaseSlot(context);
+            checkClassLeaf(value, context);
+            return;
+        }
+        if (typeof value === 'object') {
+            if (!slotNames) {
+                throw new Error(`tv(): ${context} is a slot map, but this tv() declares no slots — use a plain class string/array.`);
+            }
+            for (const key of Object.keys(value)) {
+                if (!slotNames.includes(key)) {
+                    throw new Error(`tv(): ${context} targets unknown slot '${key}' (declared slots: ${slotNames.join(', ')}).`);
+                }
+                checkClassLeaf(value[key], `${context}.${key}`);
+            }
+            return;
+        }
+        throw new Error(`tv(): ${context} must be a class string, array or slot map, got ${typeof value}.`);
+    };
+    for (const [axis, values] of Object.entries(variants)) {
+        for (const [valueName, value] of Object.entries(values)) {
+            checkSlotKeys(value, `variants.${axis}.${valueName}`);
+        }
+    }
+    for (const [i, cv] of compoundVariants.entries()) {
+        for (const key of Object.keys(cv)) {
+            if (key === 'class')
+                continue;
+            const axis = variants[key];
+            if (axis == null) {
+                throw new Error(`tv(): compoundVariants[${i}] references unknown variant axis '${key}'.`);
+            }
+            const constraint = cv[key];
+            const values = Array.isArray(constraint) ? constraint : [constraint];
+            const booleanAxis = 'true' in axis || 'false' in axis;
+            for (const v of values) {
+                const normalized = falsyToString(v);
+                // 'true'/'false' may be matched even when only one of them is
+                // declared — half-declared boolean axes are idiomatic
+                // (`loading: { true: … }` + a compound on `loading: false`). The
+                // escape only applies to boolean-ish axes; `size: true` on a string
+                // axis is a config error.
+                if ((normalized === 'true' || normalized === 'false') && booleanAxis)
+                    continue;
+                if (normalized == null || !(normalized in axis)) {
+                    throw new Error(`tv(): compoundVariants[${i}] matches '${key}: ${String(v)}', but axis '${key}' declares no such value (values: ${Object.keys(axis).join(', ')}).`);
+                }
+            }
+        }
+        checkSlotKeys(cv.class, `compoundVariants[${i}].class`);
+    }
+    for (const [key, value] of Object.entries(defaultVariants)) {
+        const axis = variants[key];
+        if (axis == null) {
+            throw new Error(`tv(): defaultVariants references unknown variant axis '${key}'.`);
+        }
+        const normalized = falsyToString(value);
+        const booleanAxis = 'true' in axis || 'false' in axis;
+        if ((normalized === 'true' || normalized === 'false') && booleanAxis)
+            continue;
+        if (normalized == null || !(normalized in axis)) {
+            throw new Error(`tv(): defaultVariants.${key} = '${String(value)}' is not a declared value of axis '${key}' (values: ${Object.keys(axis).join(', ')}).`);
+        }
+    }
+}
 // Implementation
 export function tv(config) {
+    validateTvConfig(config);
     const { base, slots, variants = {}, compoundVariants = [], defaultVariants = {} } = config;
     const variantEntries = Object.entries(variants);
     const hasSlots = slots != null && Object.keys(slots).length > 0;
+    /**
+     * Shared pipeline: first source → each variant axis in declaration order →
+     * each matching compoundVariant in array order → call-site class override.
+     * `foldSources` lets every later source strip earlier sources' conflicting
+     * buckets, so axis and compound order are semantic: declare the axis that
+     * must win a shared bucket later. See "tv() engine — explicit trade-offs"
+     * in ARCHITECTURE.md. `pickValue` routes config values: identity in no-slot
+     * mode; per-slot lookup (slot maps by name, plain strings to the 'base'
+     * slot) in slot mode.
+     */
+    function foldFor(firstSource, effective, pickValue, overrideTokens) {
+        const sources = [firstSource];
+        for (const [vName, vMap] of variantEntries) {
+            const key = falsyToString(effective[vName]);
+            if (key == null || !(key in vMap))
+                continue;
+            sources.push(tokenize(resolveClassValue(pickValue(vMap[key]))));
+        }
+        for (const cv of compoundVariants) {
+            if (!matchesCompound(cv, effective))
+                continue;
+            sources.push(tokenize(resolveClassValue(pickValue(cv.class))));
+        }
+        sources.push(overrideTokens);
+        return foldSources(sources).join(' ');
+    }
     if (!hasSlots) {
-        return function resolve(props) {
+        const identity = (value) => value;
+        const baseTokens = tokenize(resolveClassValue(base));
+        const resolve = function resolve(props) {
             const effective = { ...defaultVariants, ...stripUndefined(props || {}) };
-            // Pipeline stages — later stages strip earlier stages' conflicting
-            // buckets. See "tv() engine — explicit trade-offs" in ARCHITECTURE.md.
-            const baseTokens = tokenize(resolveClassValue(base));
-            const variantTokens = [];
-            for (const [vName, vMap] of variantEntries) {
-                const key = falsyToString(effective[vName]);
-                if (key != null && key in vMap) {
-                    variantTokens.push(...tokenize(resolveClassValue(vMap[key])));
-                }
-            }
-            const compoundTokens = [];
-            for (const cv of compoundVariants) {
-                if (matchesCompound(cv, effective)) {
-                    compoundTokens.push(...tokenize(resolveClassValue(cv.class ?? cv.className)));
-                }
-            }
-            const overrideTokens = [];
-            if (props?.class)
-                overrideTokens.push(...tokenize(resolveClassValue(props.class)));
-            if (props?.className)
-                overrideTokens.push(...tokenize(resolveClassValue(props.className)));
-            // Strip in pipeline order: variants strip base, compounds strip
-            // (base+variants), overrides strip all prior. Each stage's own classes
-            // remain untouched.
-            const afterVariants = [...stripConflicts(baseTokens, variantTokens), ...variantTokens];
-            const afterCompounds = [...stripConflicts(afterVariants, compoundTokens), ...compoundTokens];
-            const final = [...stripConflicts(afterCompounds, overrideTokens), ...overrideTokens];
-            return final.join(' ');
+            const overrideTokens = props?.class ? tokenize(cx(props.class)) : [];
+            return foldFor(baseTokens, effective, identity, overrideTokens);
         };
+        // Introspection hook for tooling (variants linter, docs-gen) — the
+        // config is static module data, exposing it costs nothing.
+        Object.defineProperty(resolve, 'config', { value: config, enumerable: false });
+        return resolve;
     }
-    // Slot mode
-    const slotEntries = Object.keys(slots);
-    return function resolve(props) {
+    // Slot mode — `slots` is narrowed to non-null by `hasSlots`.
+    const slotNames = Object.keys(slots);
+    const slotBases = new Map();
+    for (const slotName of slotNames) {
+        slotBases.set(slotName, tokenize(resolveClassValue(slots[slotName])));
+    }
+    const pickerFor = (slotName) => (value) => {
+        if (value != null && typeof value === 'object' && !Array.isArray(value)) {
+            return value[slotName];
+        }
+        // Plain string/array config values route to the 'base' slot only.
+        return slotName === 'base' ? value : undefined;
+    };
+    const resolve = function resolve(props) {
+        if (import.meta.env?.DEV && props != null && props.class != null) {
+            console.warn(`tv(): a top-level \`class\` is ignored in slot mode (slots: ${slotNames.join(', ')}) — pass it to the slot function instead, e.g. styles.base({ class }).`);
+        }
         const topProps = { ...defaultVariants, ...stripUndefined(props || {}) };
         const result = {};
-        for (const slotName of slotEntries) {
+        for (const slotName of slotNames) {
+            const pick = pickerFor(slotName);
+            const slotBase = slotBases.get(slotName);
             result[slotName] = function slotFn(slotProps) {
                 const effective = { ...topProps, ...stripUndefined(slotProps || {}) };
-                // 1. Slot base (merge config.base into 'base' slot if present).
-                //    `config.base` only contributes to a slot literally named
-                //    `'base'`. If a component renames its primary slot (e.g. to
-                //    `wrapper`), `config.base` is silently dropped — slots and
-                //    config.base must agree on the name.
-                const baseTokens = [];
-                if (slotName === 'base' && base) {
-                    baseTokens.push(...tokenize(resolveClassValue(base)));
-                }
-                baseTokens.push(...tokenize(resolveClassValue(slots[slotName])));
-                // 2. Per-slot variant resolution
-                const variantTokens = [];
-                for (const [vName, vMap] of variantEntries) {
-                    const key = falsyToString(effective[vName]);
-                    if (key == null || !(key in vMap))
-                        continue;
-                    const vValue = vMap[key];
-                    if (vValue != null && typeof vValue === 'object' && !Array.isArray(vValue)) {
-                        const obj = vValue;
-                        if (slotName in obj) {
-                            variantTokens.push(...tokenize(resolveClassValue(obj[slotName])));
-                        }
-                    }
-                    else if (slotName === 'base') {
-                        variantTokens.push(...tokenize(resolveClassValue(vValue)));
-                    }
-                }
-                // 3. Compound variant resolution (per-slot)
-                const compoundTokens = [];
-                for (const cv of compoundVariants) {
-                    if (!matchesCompound(cv, effective))
-                        continue;
-                    const cvClass = cv.class ?? cv.className;
-                    if (cvClass != null && typeof cvClass === 'object' && !Array.isArray(cvClass)) {
-                        const obj = cvClass;
-                        if (slotName in obj) {
-                            compoundTokens.push(...tokenize(resolveClassValue(obj[slotName])));
-                        }
-                    }
-                    else if (slotName === 'base') {
-                        compoundTokens.push(...tokenize(resolveClassValue(cvClass)));
-                    }
-                }
-                // 4. Class override from slotProps
-                const overrideTokens = [];
-                if (slotProps?.class)
-                    overrideTokens.push(...tokenize(resolveClassValue(slotProps.class)));
-                if (slotProps?.className)
-                    overrideTokens.push(...tokenize(resolveClassValue(slotProps.className)));
-                // Pipeline strip: later stage wins over earlier stage's conflicts.
-                const afterVariants = [...stripConflicts(baseTokens, variantTokens), ...variantTokens];
-                const afterCompounds = [
-                    ...stripConflicts(afterVariants, compoundTokens),
-                    ...compoundTokens
-                ];
-                const final = [...stripConflicts(afterCompounds, overrideTokens), ...overrideTokens];
-                return final.join(' ');
+                const overrideTokens = slotProps?.class ? tokenize(cx(slotProps.class)) : [];
+                return foldFor(slotBase, effective, pick, overrideTokens);
             };
         }
         return result;
     };
+    Object.defineProperty(resolve, 'config', { value: config, enumerable: false });
+    return resolve;
 }