@urbicon-ui/blocks 6.1.8 → 6.2.0

package/README.md

@@ -45,10 +45,10 @@ Available effects: `scale`, `ripple`, `translate`, `glow`, `bounce`, `pulse`, `s
 
 ## Presets & Defaults
 
-`BlocksProvider` registers project-wide defaults and named presets. Override hierarchy:
+`BlocksProvider` registers project-wide defaults, named presets, and prop-conditional `overrides`. Override hierarchy (conflict-resolved per Tailwind bucket — a later source wins):
 
 ```
-tv()-Defaults → BlocksProvider defaults → BlocksProvider presets → Instance slotClasses → Instance class
+tv() defaults → defaults.slotClasses → defaults.overrides → preset.slotClasses → preset.overrides → instance slotClasses → instance class
 ```
 
 ```svelte
@@ -61,6 +61,16 @@ tv()-Defaults → BlocksProvider defaults → BlocksProvider presets → Instanc
 </BlocksProvider>
 ```
 
+Use `overrides` for **prop-conditional** rules an unconditional `slotClasses` cannot express (e.g. only the `outlined` variant). Each entry is a `compoundVariant`-shaped matcher; the tv() conflict resolver strips the library's conflicting class:
+
+```svelte
+<BlocksProvider
+  defaults={{ Badge: { overrides: [{ variant: 'outlined', class: { base: 'border' } }] } }}
+>
+  <!-- outlined badges get a 1px border; other variants untouched -->
+</BlocksProvider>
+```
+
 ## Icons
 
 156 hand-rolled SVG icons in `src/lib/icons/`, registered via `IconProvider`. Metadata (`ICON_METADATA`) enables search by name, keyword, or category. See the icon-design rules in [AGENTS.md → Icon Design Rules](../../AGENTS.md#icon-design-rules).

package/dist/primitives/Badge/Badge.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import { Button, mintRegistry } from '../..';
-  import { getBlocksConfig, mergeSlotClasses, resolvePresetSlotClasses } from '../../provider';
+  import { getBlocksConfig, resolveSlotClasses } from '../../provider';
   import { resolveIcon } from '../../icons';
   import CloseIconDefault from '../../icons/CloseIcon.svelte';
   import { useBlocksI18n } from '../..';
@@ -42,13 +42,6 @@
 
   const blocksConfig = getBlocksConfig();
   const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
-  const slotClasses = $derived(
-    mergeSlotClasses(
-      blocksConfig?.defaults?.Badge?.slotClasses,
-      resolvePresetSlotClasses(blocksConfig?.presets, 'Badge', preset),
-      slotClassesProp
-    )
-  );
 
   let badgeElement = $state<HTMLElement>();
   let isHovered = $state(false);
@@ -57,20 +50,24 @@
   const isInteractive = $derived(interactive || !!onclick);
   const isRemovable = $derived(removable && !isDot);
 
-  const styles = $derived(
-    badgeVariants({
-      tier: effectiveTier,
-      intent,
-      variant,
-      size,
-      counter: counter || undefined,
-      pulse: pulse || undefined,
-      removable: isRemovable || undefined,
-      interactive: isInteractive || undefined,
-      disabled: disabled || undefined,
-      placement,
-      border: border || undefined
-    })
+  const variantProps = $derived({
+    tier: effectiveTier,
+    intent,
+    variant,
+    size,
+    counter: counter || undefined,
+    pulse: pulse || undefined,
+    removable: isRemovable || undefined,
+    interactive: isInteractive || undefined,
+    disabled: disabled || undefined,
+    placement,
+    border: border || undefined
+  });
+
+  const styles = $derived(badgeVariants(variantProps));
+
+  const slotClasses = $derived(
+    resolveSlotClasses(blocksConfig, 'Badge', preset, variantProps, slotClassesProp)
   );
 
   $effect(() => {

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/utils/variants.d.ts

@@ -27,6 +27,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/blocks",
-  "version": "6.1.8",
+  "version": "6.2.0",
   "description": "Svelte 5 UI component library with Tailwind CSS 4, OKLCH design tokens and zero runtime dependencies",
   "license": "MIT",
   "repository": {
@@ -90,8 +90,8 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@tailwindcss/vite": "^4.3.1",
-    "@urbicon-ui/i18n": "6.1.8",
-    "@urbicon-ui/shared-types": "6.1.8",
+    "@urbicon-ui/i18n": "6.2.0",
+    "@urbicon-ui/shared-types": "6.2.0",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",