@urbicon-ui/blocks 6.1.8 → 6.3.1

package/dist/primitives/Textarea/Textarea.svelte

@@ -1,9 +1,9 @@
 <script lang="ts">
   import { mintRegistry } from '../..';
-  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { getBlocksConfig, resolveSlotClasses } from '../../provider';
   import { useFormField, getTierContext } from '../../utils';
   import type { TextareaProps } from './index';
-  import { textareaVariants } from './textarea.variants';
+  import { textareaVariants, type TextareaVariants } from './textarea.variants';
 
   let {
     label,
@@ -36,13 +36,6 @@
 
   const blocksConfig = getBlocksConfig();
   const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
-  const slotClasses = $derived(
-    mergeSlotClasses(
-      blocksConfig?.defaults?.Textarea?.slotClasses,
-      resolvePresetSlotClasses(blocksConfig?.presets, 'Textarea', preset),
-      slotClassesProp
-    )
-  );
 
   let textareaRef = $state<HTMLTextAreaElement>();
 
@@ -66,20 +59,27 @@
 
   const showFooter = $derived(!!error || !!helper || (showCounter && maxlength));
 
-  const styles = $derived(
-    textareaVariants({
-      tier: effectiveTier,
-      variant,
-      size,
-      intent,
-      autoResize: autoResize || undefined,
-      disabled: disabled || undefined,
-      readonly: readonly || undefined,
-      error: !!error || undefined,
-      required: required || undefined,
-      messageType: error ? 'error' : 'helper',
-      counterState
-    })
+  // Variant props feed both the tv() style computation and the slot-class
+  // cascade — extracted into one derived so `resolveSlotClasses` can match
+  // conditional `overrides` against the textarea's active variants.
+  const variantProps: TextareaVariants = $derived({
+    tier: effectiveTier,
+    variant,
+    size,
+    intent,
+    autoResize: autoResize || undefined,
+    disabled: disabled || undefined,
+    readonly: readonly || undefined,
+    error: !!error || undefined,
+    required: required || undefined,
+    messageType: error ? 'error' : 'helper',
+    counterState
+  });
+
+  const styles = $derived(textareaVariants(variantProps));
+
+  const slotClasses = $derived(
+    resolveSlotClasses(blocksConfig, 'Textarea', preset, variantProps, slotClassesProp)
   );
 
   const lineHeight = $derived(size === 'sm' ? 20 : size === 'lg' ? 28 : 24);

package/dist/primitives/Textarea/index.d.ts

@@ -1,6 +1,6 @@
 import type { HTMLTextareaAttributes } from 'svelte/elements';
 import type { MintProp } from '../../mint';
-import type { TextareaVariants } from './textarea.variants';
+import type { TextareaSlots, TextareaVariants } from './textarea.variants';
 /**
  * @description Multi-line text input with auto-resize, character counter, and validation states.
  * Shares the same variant/intent/size system as Input for visual consistency.
@@ -59,8 +59,12 @@ export interface TextareaProps extends Omit<TextareaVariants, 'error' | 'counter
     class?: string;
     /** Remove all default tv() classes. Only user-provided classes apply. */
     unstyled?: boolean;
-    /** Per-slot class overrides merged with tv() styles. */
-    slotClasses?: Partial<Record<'wrapper' | 'base' | 'label' | 'footer' | 'message' | 'counter', string>>;
+    /**
+     * Per-slot class overrides merged with tv() styles. Slots: wrapper (root —
+     * what `class` also targets) | base (the `<textarea>` element) | label |
+     * footer | message | counter.
+     */
+    slotClasses?: Partial<Record<TextareaSlots, string>>;
     /**
      * Apply a named preset registered via `<BlocksProvider presets={{ Textarea: {...} }}>`.
      * Prefer this over `class` overrides when the requested look falls outside the

package/dist/primitives/Textarea/textarea.variants.d.ts

@@ -1,4 +1,4 @@
-import { type VariantProps } from '../../utils/variants';
+import { type SlotNames, type VariantProps } from '../../utils/variants';
 export declare const textareaVariants: (props?: import("../../utils/variants").TVProps<{
     tier: {
         modify: {
@@ -191,3 +191,5 @@ export declare const textareaVariants: (props?: import("../../utils/variants").T
     }) | undefined) => string;
 };
 export type TextareaVariants = VariantProps<typeof textareaVariants>;
+/** Slot names derived from the `tv()` config above — single source of truth for `slotClasses`. */
+export type TextareaSlots = SlotNames<typeof textareaVariants>;

package/dist/primitives/Toast/Toaster.svelte

@@ -10,7 +10,7 @@
   import SuccessCircleIconDefault from '../../icons/SuccessCircleIcon.svelte';
   import WarningTriangleIconDefault from '../../icons/WarningTriangleIcon.svelte';
   import DangerCircleIconDefault from '../../icons/DangerCircleIcon.svelte';
-  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { getBlocksConfig, resolveSlotClasses } from '../../provider';
   import type { ToastProps } from './index';
 
   const bt = useBlocksI18n();
@@ -38,12 +38,11 @@
 
   const blocksConfig = getBlocksConfig();
   const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+  // Component-level slot-class cascade. Per-toast `intent` is NOT part of
+  // activeProps — it is applied per row in the `slot(key, intent)` helper via
+  // its own `toastVariants({ placement, intent })` call (see below).
   const slotClasses = $derived(
-    mergeSlotClasses(
-      blocksConfig?.defaults?.Toaster?.slotClasses,
-      resolvePresetSlotClasses(blocksConfig?.presets, 'Toaster', preset),
-      slotClassesProp
-    )
+    resolveSlotClasses(blocksConfig, 'Toaster', preset, { placement }, slotClassesProp)
   );
 
   $effect(() => {

package/dist/primitives/Toast/index.d.ts

@@ -1,5 +1,5 @@
 import type { HTMLAttributes } from 'svelte/elements';
-import type { ToastPlacement } from './toast.variants';
+import type { ToasterSlots, ToastPlacement } from './toast.variants';
 /**
  * Canonical intents accepted by the toaster. Use as a runtime list when
  * building dispatchers (e.g. `toaster[intent]?.(title, opts)`); use
@@ -82,7 +82,7 @@ export interface ToastProps extends Omit<HTMLAttributes<HTMLDivElement>, 'childr
     /** Strip all default tv classes. Use with `slotClasses` for a fully custom look. */
     unstyled?: boolean;
     /** Per-slot class overrides merged with (or replacing, when `unstyled`) the default styles. */
-    slotClasses?: Partial<Record<'container' | 'toast' | 'icon' | 'content' | 'title' | 'description' | 'dismissButton' | 'progress', string>>;
+    slotClasses?: Partial<Record<ToasterSlots, string>>;
     /**
      * Apply a named preset registered via `<BlocksProvider presets={{ Toaster: {...} }}>`.
      * Prefer this over `class` overrides when the requested look falls outside the

package/dist/primitives/Toast/toast.variants.d.ts

@@ -1,4 +1,4 @@
-import { type VariantProps } from '../../utils/variants';
+import { type SlotNames, type VariantProps } from '../../utils/variants';
 export declare const toastVariants: (props?: import("../../utils/variants").TVProps<{
     intent: {
         primary: {
@@ -111,4 +111,6 @@ export declare const toastVariants: (props?: import("../../utils/variants").TVPr
     }) | undefined) => string;
 };
 export type ToastVariants = VariantProps<typeof toastVariants>;
+/** Slot names derived from the tv() config — single source of truth for slotClasses. */
+export type ToasterSlots = SlotNames<typeof toastVariants>;
 export type ToastPlacement = 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center';

package/dist/primitives/Toggle/Toggle.svelte

@@ -1,8 +1,8 @@
 <script lang="ts">
   import { useBlocksI18n, mintRegistry } from '../..';
-  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { getBlocksConfig, resolveSlotClasses } from '../../provider';
   import { getTierContext, useFormField } from '../../utils';
-  import { toggleVariants } from './toggle.variants';
+  import { toggleVariants, type ToggleVariants } from './toggle.variants';
   import type { ToggleProps } from './index';
 
   const bt = useBlocksI18n();
@@ -42,13 +42,6 @@
 
   const blocksConfig = getBlocksConfig();
   const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
-  const slotClasses = $derived(
-    mergeSlotClasses(
-      blocksConfig?.defaults?.Toggle?.slotClasses,
-      resolvePresetSlotClasses(blocksConfig?.presets, 'Toggle', preset),
-      slotClassesProp
-    )
-  );
 
   let rootEl = $state<HTMLElement>();
 
@@ -58,16 +51,23 @@
   const tierCtx = getTierContext();
   const effectiveTier = $derived(tier ?? tierCtx?.tier ?? 'commit');
 
-  const styles = $derived(
-    toggleVariants({
-      tier: effectiveTier,
-      size,
-      intent,
-      appearance,
-      checked,
-      disabled,
-      withBorder
-    })
+  // Variant props feed both the tv() style computation and the slot-class
+  // cascade — extracted into one derived so `resolveSlotClasses` can match
+  // conditional `overrides` against the toggle's active variants.
+  const variantProps: ToggleVariants = $derived({
+    tier: effectiveTier,
+    size,
+    intent,
+    appearance,
+    checked,
+    disabled,
+    withBorder
+  });
+
+  const styles = $derived(toggleVariants(variantProps));
+
+  const slotClasses = $derived(
+    resolveSlotClasses(blocksConfig, 'Toggle', preset, variantProps, slotClassesProp)
   );
 
   const dataState = $derived(checked ? 'checked' : 'unchecked');

package/dist/primitives/Toggle/index.d.ts

@@ -1,7 +1,7 @@
 import type { HTMLInputAttributes } from 'svelte/elements';
 import type { MintProp } from '../../mint';
 import type { InteractiveTier } from '../../utils';
-import type { ToggleVariants } from './toggle.variants';
+import type { ToggleSlots, ToggleVariants } from './toggle.variants';
 /**
  * @description Accessible switch control for boolean on/off states.
  * Built on a hidden native input with semantic intents and Mint micro-interactions.
@@ -43,8 +43,12 @@ export interface ToggleProps extends Omit<ToggleVariants, 'checked'>, Omit<HTMLI
     class?: string;
     /** Strip all default tailwind-variants classes. Use with `slotClasses` for a fully custom look. The track exposes `data-state` for conditional styling. */
     unstyled?: boolean;
-    /** Per-slot class overrides merged with (or replacing, when `unstyled`) the default styles. */
-    slotClasses?: Partial<Record<'wrapper' | 'control' | 'track' | 'thumb' | 'label' | 'message', string>>;
+    /**
+     * Per-slot class overrides merged with (or replacing, when `unstyled`) the
+     * default styles. Slots: wrapper (root — what `class` also targets) | control
+     * (the `<label>` wrapping the input) | track | thumb | label | message.
+     */
+    slotClasses?: Partial<Record<ToggleSlots, string>>;
     /**
      * Apply a named preset registered via `<BlocksProvider presets={{ Toggle: {...} }}>`.
      * Prefer this over `class` overrides when the requested look falls outside the

package/dist/primitives/Toggle/toggle.variants.d.ts

@@ -1,4 +1,4 @@
-import { type VariantProps } from '../../utils/variants';
+import { type SlotNames, type VariantProps } from '../../utils/variants';
 export declare const toggleVariants: (props?: import("../../utils/variants").TVProps<{
     tier: {
         commit: {
@@ -132,3 +132,5 @@ export declare const toggleVariants: (props?: import("../../utils/variants").TVP
     }) | undefined) => string;
 };
 export type ToggleVariants = VariantProps<typeof toggleVariants>;
+/** Slot names derived from the `tv()` config above — single source of truth for `slotClasses`. */
+export type ToggleSlots = SlotNames<typeof toggleVariants>;

package/dist/primitives/Toolbar/Toolbar.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
-  import { toolbarVariants } from './toolbar.variants';
+  import { toolbarVariants, type ToolbarVariants } from './toolbar.variants';
   import type { ToolbarProps } from './index';
-  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { getBlocksConfig, resolveSlotClasses } from '../../provider';
   import { setTierContext } from '../../utils/tier-context';
 
   let {
@@ -30,15 +30,13 @@
 
   const blocksConfig = getBlocksConfig();
   const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+
+  const variantProps: ToolbarVariants = $derived({ variant, orientation, gap, padding });
+  const styles = $derived(toolbarVariants(variantProps));
+
   const slotClasses = $derived(
-    mergeSlotClasses(
-      blocksConfig?.defaults?.Toolbar?.slotClasses,
-      resolvePresetSlotClasses(blocksConfig?.presets, 'Toolbar', preset),
-      slotClassesProp
-    )
+    resolveSlotClasses(blocksConfig, 'Toolbar', preset, variantProps, slotClassesProp)
   );
-
-  const styles = $derived(toolbarVariants({ variant, orientation, gap, padding }));
 </script>
 
 <div

package/dist/primitives/Toolbar/index.d.ts

@@ -1,7 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import type { InteractiveTier } from '../../utils';
-import type { ToolbarVariants } from './toolbar.variants';
+import type { ToolbarSlots, ToolbarVariants } from './toolbar.variants';
 /**
  * Props interface for Toolbar component
  *
@@ -54,8 +54,9 @@ export interface ToolbarProps extends ToolbarVariants, Omit<HTMLAttributes<HTMLD
     tier?: InteractiveTier;
     /** Remove all default tv() classes. Combine with `slotClasses` to restyle from scratch. */
     unstyled?: boolean;
-    /** Per-slot class overrides merged with (or replacing when `unstyled`) the default classes. */
-    slotClasses?: Partial<Record<'base', string>>;
+    /** Per-slot class overrides merged with (or replacing when `unstyled`) the default classes.
+     *  Slots: base */
+    slotClasses?: Partial<Record<ToolbarSlots, string>>;
     /**
      * Apply a named preset registered via `<BlocksProvider presets={{ Toolbar: {...} }}>`.
      * Prefer this over `class` overrides when the requested look falls outside the

package/dist/primitives/Toolbar/toolbar.variants.d.ts

@@ -1,4 +1,4 @@
-import { type VariantProps } from '../../utils/variants';
+import { type SlotNames, type VariantProps } from '../../utils/variants';
 export declare const toolbarVariants: (props?: import("../../utils/variants").TVProps<{
     variant: {
         quiet: {
@@ -68,3 +68,5 @@ export declare const toolbarVariants: (props?: import("../../utils/variants").TV
     }) | undefined) => string;
 };
 export type ToolbarVariants = VariantProps<typeof toolbarVariants>;
+/** Slot names derived from the tv() config — single source of truth for slotClasses. */
+export type ToolbarSlots = SlotNames<typeof toolbarVariants>;

package/dist/primitives/Tooltip/Tooltip.svelte

@@ -1,7 +1,8 @@
 <script lang="ts">
   import { tooltipVariants } from './tooltip.variants';
+  import type { VariantProps } from '../../utils/variants';
   import type { TooltipProps } from './index';
-  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { getBlocksConfig, resolveSlotClasses } from '../../provider';
   import {
     computePosition,
     autoUpdate,
@@ -31,13 +32,6 @@
 
   const blocksConfig = getBlocksConfig();
   const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
-  const slotClasses = $derived(
-    mergeSlotClasses(
-      blocksConfig?.defaults?.Tooltip?.slotClasses,
-      resolvePresetSlotClasses(blocksConfig?.presets, 'Tooltip', preset),
-      slotClassesProp
-    )
-  );
 
   let visible = $state(false);
   let triggerElement = $state<HTMLElement>();
@@ -48,7 +42,11 @@
   const propsId = $props.id();
   const tooltipId = `tooltip-${propsId}`;
 
-  const styles = $derived(tooltipVariants({ visible, intent, size }));
+  const variantProps: VariantProps<typeof tooltipVariants> = $derived({ visible, intent, size });
+  const styles = $derived(tooltipVariants(variantProps));
+  const slotClasses = $derived(
+    resolveSlotClasses(blocksConfig, 'Tooltip', preset, variantProps, slotClassesProp)
+  );
 
   let showTimeout: number;
   let hideTimeout: number;

package/dist/primitives/Tooltip/index.d.ts

@@ -1,7 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import type { Placement } from '../../utils/floating';
-import type { TooltipVariants } from './tooltip.variants';
+import type { TooltipSlots, TooltipVariants } from './tooltip.variants';
 /**
  * @description Contextual overlay that displays brief, supplementary text on hover or focus.
  * Built with Floating UI for precise positioning and accessibility support.
@@ -43,7 +43,7 @@ export interface TooltipProps extends TooltipVariants, Omit<HTMLAttributes<HTMLD
     /** Remove default tv classes; only consumer classes apply. */
     unstyled?: boolean;
     /** Per-slot class overrides merged with (or replacing, when unstyled) tv styles. */
-    slotClasses?: Partial<Record<'base' | 'arrow', string>>;
+    slotClasses?: Partial<Record<TooltipSlots, string>>;
     /**
      * Apply a named preset registered via `<BlocksProvider presets={{ Tooltip: {...} }}>`.
      * Prefer this over `class` overrides when the requested look falls outside the

package/dist/primitives/Tooltip/tooltip.variants.d.ts

@@ -1,4 +1,4 @@
-import { type VariantProps } from '../../utils/variants';
+import { type SlotNames, type VariantProps } from '../../utils/variants';
 export declare const tooltipVariants: (props?: import("../../utils/variants").TVProps<{
     visible: {
         true: {
@@ -61,3 +61,5 @@ export declare const tooltipVariants: (props?: import("../../utils/variants").TV
     }) | undefined) => string;
 };
 export type TooltipVariants = Omit<VariantProps<typeof tooltipVariants>, 'visible'>;
+/** Slot names derived from the `tv()` config above — single source of truth for `slotClasses`. */
+export type TooltipSlots = SlotNames<typeof tooltipVariants>;

package/dist/provider/blocks-context.d.ts

@@ -1,5 +1,28 @@
+/**
+ * A prop-conditional style rule. Its non-`class` keys are matched against a
+ * component's active variant props — exactly like a `tv()` compoundVariant
+ * (`string` = equality, `string[]` = "one of"). On a match, the `class`
+ * record (slot → classes) is merged into the slot-class cascade. Additive:
+ * every matching rule contributes; later sources win per Tailwind bucket.
+ *
+ * @example
+ * { variant: 'outlined', class: { base: 'border' } } // 1px border only on outlined
+ */
+export interface ConditionalOverride {
+    /** Per-slot classes applied when the prop conditions match. */
+    class: Record<string, string>;
+    /** Prop conditions: prop name → required value (or one of several). */
+    [propCondition: string]: string | string[] | Record<string, string> | undefined;
+}
 export interface ComponentDefaults {
     slotClasses?: Record<string, string>;
+    /**
+     * Prop-conditional style rules, applied after unconditional `slotClasses`
+     * (so they win per bucket) but before instance-level `slotClasses` / `class`.
+     * Use for surgical per-variant tweaks the unconditional `slotClasses` cannot
+     * express, e.g. `overrides: [{ variant: 'outlined', class: { base: 'border' } }]`.
+     */
+    overrides?: ConditionalOverride[];
 }
 /**
  * A preset is a named, project-defined visual style for a component.
@@ -12,6 +35,8 @@ export interface ComponentDefaults {
  */
 export interface ComponentPreset {
     slotClasses?: Record<string, string>;
+    /** Prop-conditional rules scoped to this preset (see {@link ConditionalOverride}). */
+    overrides?: ConditionalOverride[];
 }
 /** Map of component name → preset name → preset definition. */
 export type PresetMap = Record<string, Record<string, ComponentPreset>>;
@@ -30,3 +55,23 @@ export declare function mergeSlotClasses(...sources: (Record<string, string> | u
  * is used but not registered, so missing presets are discoverable.
  */
 export declare function resolvePresetSlotClasses(presets: PresetMap | undefined, component: string, presetName: string | undefined): Record<string, string> | undefined;
+/**
+ * Collect the per-slot classes of every `overrides` entry whose prop
+ * conditions match `activeProps`. Returns `undefined` when there are no
+ * overrides or none match. Multiple matches merge additively, in order.
+ */
+export declare function resolveOverrideSlotClasses(overrides: ConditionalOverride[] | undefined, activeProps: Record<string, unknown>): Record<string, string> | undefined;
+/**
+ * Resolve the full slot-class cascade for a component instance, honoring
+ * conditional `overrides` from both provider defaults and the active preset.
+ *
+ * Precedence (weak → strong), conflict-resolved per slot so a later source
+ * wins within the same Tailwind bucket:
+ *
+ *   defaults.slotClasses → defaults.overrides[match]
+ *     → preset.slotClasses → preset.overrides[match] → instance.slotClasses
+ *
+ * The result is handed to the component's `tv()` slot fn as the `class`
+ * override, where it additionally strips conflicting library classes.
+ */
+export declare function resolveSlotClasses(config: BlocksConfig | undefined, component: string, preset: string | undefined, activeProps: Record<string, unknown>, instanceSlotClasses: Record<string, string> | undefined): Record<string, string>;

package/dist/provider/blocks-context.js

@@ -1,4 +1,5 @@
 import { createOptionalContext } from '../utils/optional-context';
+import { matchesCompound, resolveClassChain } from '../utils/variants';
 // BlocksProvider is optional — components must work without one.
 const [getBlocksConfig, setBlocksConfig] = createOptionalContext();
 export { getBlocksConfig, setBlocksConfig };
@@ -34,3 +35,59 @@ export function resolvePresetSlotClasses(presets, component, presetName) {
     }
     return preset.slotClasses;
 }
+/**
+ * Collect the per-slot classes of every `overrides` entry whose prop
+ * conditions match `activeProps`. Returns `undefined` when there are no
+ * overrides or none match. Multiple matches merge additively, in order.
+ */
+export function resolveOverrideSlotClasses(overrides, activeProps) {
+    if (!overrides || overrides.length === 0)
+        return undefined;
+    let result;
+    for (const entry of overrides) {
+        if (!matchesCompound(entry, activeProps))
+            continue;
+        result ??= {};
+        for (const [slot, value] of Object.entries(entry.class)) {
+            if (!value)
+                continue;
+            result[slot] = result[slot] ? `${result[slot]} ${value}` : value;
+        }
+    }
+    return result;
+}
+/**
+ * Resolve the full slot-class cascade for a component instance, honoring
+ * conditional `overrides` from both provider defaults and the active preset.
+ *
+ * Precedence (weak → strong), conflict-resolved per slot so a later source
+ * wins within the same Tailwind bucket:
+ *
+ *   defaults.slotClasses → defaults.overrides[match]
+ *     → preset.slotClasses → preset.overrides[match] → instance.slotClasses
+ *
+ * The result is handed to the component's `tv()` slot fn as the `class`
+ * override, where it additionally strips conflicting library classes.
+ */
+export function resolveSlotClasses(config, component, preset, activeProps, instanceSlotClasses) {
+    const defaults = config?.defaults?.[component];
+    const presetDef = preset ? config?.presets?.[component]?.[preset] : undefined;
+    const sources = [
+        defaults?.slotClasses,
+        resolveOverrideSlotClasses(defaults?.overrides, activeProps),
+        resolvePresetSlotClasses(config?.presets, component, preset),
+        resolveOverrideSlotClasses(presetDef?.overrides, activeProps),
+        instanceSlotClasses
+    ];
+    const result = {};
+    for (const source of sources) {
+        if (!source)
+            continue;
+        for (const [slot, value] of Object.entries(source)) {
+            if (!value)
+                continue;
+            result[slot] = result[slot] ? resolveClassChain(result[slot], value) : value;
+        }
+    }
+    return result;
+}

package/dist/provider/index.d.ts

@@ -1,2 +1,2 @@
 export { default as BlocksProvider } from './BlocksProvider.svelte';
-export { type BlocksConfig, type ComponentDefaults, type ComponentPreset, getBlocksConfig, mergeSlotClasses, type PresetMap, resolvePresetSlotClasses } from './blocks-context';
+export { type BlocksConfig, type ComponentDefaults, type ComponentPreset, type ConditionalOverride, getBlocksConfig, mergeSlotClasses, type PresetMap, resolveOverrideSlotClasses, resolvePresetSlotClasses, resolveSlotClasses } from './blocks-context';

package/dist/provider/index.js

@@ -1,2 +1,2 @@
 export { default as BlocksProvider } from './BlocksProvider.svelte';
-export { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from './blocks-context';
+export { getBlocksConfig, mergeSlotClasses, resolveOverrideSlotClasses, resolvePresetSlotClasses, resolveSlotClasses } from './blocks-context';

package/dist/style/semantic.css

@@ -38,6 +38,11 @@
   --color-surface-selected: light-dark(var(--color-primary-50), var(--color-primary-900));
   --color-surface-subtle: light-dark(var(--color-neutral-50), var(--color-neutral-800));
   --color-surface-inverted: light-dark(var(--color-neutral-900), var(--color-neutral-100));
+  /* Skeleton wave-shimmer highlight (Skeleton animation="wave"). A translucent
+     white glint that sweeps across `surface-interactive`; lower alpha in dark
+     mode so it reads as a subtle sheen, not a flash. light-dark() keeps it
+     mode-aware so the wave needs no `dark:` override. */
+  --color-skeleton-shimmer: light-dark(oklch(1 0 0 / 0.5), oklch(1 0 0 / 0.1));
 
   /* === TEXT ===
      tertiary/quaternary shifted darker (light) so informative text on

package/dist/utils/variants.d.ts

@@ -16,6 +16,23 @@ type CompoundVariant<V extends Record<string, Record<string, unknown>>> = {
 };
 export type TVProps<V extends Record<string, Record<string, unknown>>> = VariantPropsMap<V> & TVClassOverrides;
 export type VariantProps<T extends (...args: never[]) => unknown> = Omit<Exclude<Parameters<T>[0], undefined>, 'class' | 'className'>;
+/**
+ * Extracts the slot-name union from a slotted `tv()` config function — the
+ * companion to {@link VariantProps}. The slot-mode overload returns
+ * `(props?) => { [K in keyof S]: SlotFn }`, so `keyof ReturnType<T>` is exactly
+ * the set of slot names a component declares in `tv({ slots: … })`.
+ *
+ * Use it to type a component's `slotClasses` prop from the single source of
+ * truth (its `*.variants.ts`) instead of hand-maintaining a parallel union
+ * that silently drifts when a slot is added or renamed:
+ *
+ * @example
+ * // button.variants.ts
+ * export type ButtonSlots = SlotNames<typeof buttonVariants>; // 'base' | 'content' | 'spinner'
+ * // index.ts
+ * slotClasses?: Partial<Record<ButtonSlots, string>>;
+ */
+export type SlotNames<T extends (...args: never[]) => unknown> = keyof ReturnType<T> & string;
 /**
  * Concatenate class inputs into a single string. Accepts strings, nested
  * arrays, and falsy values (filtered out). Trims and joins with single
@@ -27,6 +44,21 @@ export type VariantProps<T extends (...args: never[]) => unknown> = Omit<Exclude
  * pass. See `docs/ARCHITECTURE.md` "tv() engine — explicit trade-offs".
  */
 export declare function cx(...inputs: ClassInput[]): string;
+/**
+ * Merge class strings with the same Tailwind conflict resolution `tv()`
+ * applies between stages: a later source's classes strip any earlier class
+ * that shares their conflict bucket, so the last source wins per bucket.
+ * Within a single source, order is preserved and conflicts fall through to
+ * the CSS cascade. Falsy / empty sources are skipped.
+ *
+ * Reuses `tokenize` + `stripConflicts`. Powers the BlocksProvider slot-class
+ * cascade (`resolveSlotClasses`) so a conditional `overrides` entry
+ * deterministically defeats an unconditional `slotClasses` entry in the same
+ * bucket — instead of emitting both and leaving the winner to stylesheet
+ * order.
+ */
+export declare function resolveClassChain(...sources: (string | null | undefined)[]): string;
+export declare function matchesCompound(compound: Record<string, unknown>, effectiveProps: Record<string, unknown>): boolean;
 export declare function tv<V extends Record<string, Record<string, unknown>> = {}>(config: {
     base?: string | string[];
     variants?: V;

package/dist/utils/variants.js

@@ -317,6 +317,31 @@ function tokenize(value) {
         return [];
     return value.split(/\s+/).filter(Boolean);
 }
+/**
+ * Merge class strings with the same Tailwind conflict resolution `tv()`
+ * applies between stages: a later source's classes strip any earlier class
+ * that shares their conflict bucket, so the last source wins per bucket.
+ * Within a single source, order is preserved and conflicts fall through to
+ * the CSS cascade. Falsy / empty sources are skipped.
+ *
+ * Reuses `tokenize` + `stripConflicts`. Powers the BlocksProvider slot-class
+ * cascade (`resolveSlotClasses`) so a conditional `overrides` entry
+ * deterministically defeats an unconditional `slotClasses` entry in the same
+ * bucket — instead of emitting both and leaving the winner to stylesheet
+ * order.
+ */
+export function resolveClassChain(...sources) {
+    let acc = [];
+    for (const source of sources) {
+        if (!source)
+            continue;
+        const tokens = tokenize(source);
+        if (tokens.length === 0)
+            continue;
+        acc = [...stripConflicts(acc, tokens), ...tokens];
+    }
+    return acc.join(' ');
+}
 // ─── Internal Helpers ────────────────────────────────────────────────────────
 function falsyToString(value) {
     if (value === false)
@@ -337,7 +362,7 @@ function stripUndefined(obj) {
     }
     return result;
 }
-function matchesCompound(compound, effectiveProps) {
+export function matchesCompound(compound, effectiveProps) {
     for (const key of Object.keys(compound)) {
         if (key === 'class' || key === 'className')
             continue;