@tangible/ui 0.0.1

package/types/index.d.ts

@@ -0,0 +1,2 @@
+export type { Size, SizeExtended, SizeCompact, SizeStandard } from './sizes';
+export type { Theme, ThemeIntent, ThemeStatus } from './themes';

package/types/index.js

@@ -0,0 +1 @@
+export {};

package/types/index.ts

@@ -0,0 +1,2 @@
+export type { Size, SizeExtended, SizeCompact, SizeStandard } from './sizes';
+export type { Theme, ThemeIntent, ThemeStatus } from './themes';

package/types/sizes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared size type definitions for components.
+ *
+ * Components use different subsets of the size scale based on their use case:
+ * - Size: Standard range (xs→lg) for buttons, progress indicators
+ * - SizeExtended: Full range (xs→xxl) for icons and typography
+ * - SizeCompact: Smaller range (xs→md) for inline elements like chips
+ * - SizeStandard: Medium range (sm→lg) for containers like modals
+ */
+/** Standard size scale: xs, sm, md, lg */
+export type Size = 'xs' | 'sm' | 'md' | 'lg';
+/** Extended size scale for icons/typography: xs, sm, md, lg, xl, xxl */
+export type SizeExtended = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+/** Compact size scale for inline elements: xs, sm, md */
+export type SizeCompact = 'xs' | 'sm' | 'md';
+/** Standard size scale for containers: sm, md, lg */
+export type SizeStandard = 'sm' | 'md' | 'lg';

package/types/sizes.js

@@ -0,0 +1,10 @@
+/**
+ * Shared size type definitions for components.
+ *
+ * Components use different subsets of the size scale based on their use case:
+ * - Size: Standard range (xs→lg) for buttons, progress indicators
+ * - SizeExtended: Full range (xs→xxl) for icons and typography
+ * - SizeCompact: Smaller range (xs→md) for inline elements like chips
+ * - SizeStandard: Medium range (sm→lg) for containers like modals
+ */
+export {};

package/types/sizes.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared size type definitions for components.
+ *
+ * Components use different subsets of the size scale based on their use case:
+ * - Size: Standard range (xs→lg) for buttons, progress indicators
+ * - SizeExtended: Full range (xs→xxl) for icons and typography
+ * - SizeCompact: Smaller range (xs→md) for inline elements like chips
+ * - SizeStandard: Medium range (sm→lg) for containers like modals
+ */
+
+/** Standard size scale: xs, sm, md, lg */
+export type Size = 'xs' | 'sm' | 'md' | 'lg';
+
+/** Extended size scale for icons/typography: xs, sm, md, lg, xl, xxl */
+export type SizeExtended = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+
+/** Compact size scale for inline elements: xs, sm, md */
+export type SizeCompact = 'xs' | 'sm' | 'md';
+
+/** Standard size scale for containers: sm, md, lg */
+export type SizeStandard = 'sm' | 'md' | 'lg';

package/types/svg.d.ts

@@ -0,0 +1,5 @@
+declare module '*.svg?react' {
+  import * as React from 'react';
+  const ReactComponent: React.FC<React.SVGProps<SVGSVGElement>>;
+  export default ReactComponent;
+}

package/types/themes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared theme type definitions for components.
+ *
+ * Components use different subsets of the theme palette based on their purpose:
+ * - ThemeIntent: Core action themes (primary, secondary, danger) for buttons
+ * - Theme: Full palette including status colors for general use
+ * - ThemeStatus: Semantic status themes for notices and alerts
+ */
+/** Core action themes for buttons and interactive elements */
+export type ThemeIntent = 'primary' | 'secondary' | 'danger';
+/** Full theme palette including status colors */
+export type Theme = 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+/** Semantic status themes for notices, alerts, feedback */
+export type ThemeStatus = 'info' | 'success' | 'warning' | 'danger';

package/types/themes.js

@@ -0,0 +1,9 @@
+/**
+ * Shared theme type definitions for components.
+ *
+ * Components use different subsets of the theme palette based on their purpose:
+ * - ThemeIntent: Core action themes (primary, secondary, danger) for buttons
+ * - Theme: Full palette including status colors for general use
+ * - ThemeStatus: Semantic status themes for notices and alerts
+ */
+export {};

package/types/themes.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared theme type definitions for components.
+ *
+ * Components use different subsets of the theme palette based on their purpose:
+ * - ThemeIntent: Core action themes (primary, secondary, danger) for buttons
+ * - Theme: Full palette including status colors for general use
+ * - ThemeStatus: Semantic status themes for notices and alerts
+ */
+
+/** Core action themes for buttons and interactive elements */
+export type ThemeIntent = 'primary' | 'secondary' | 'danger';
+
+/** Full theme palette including status colors */
+export type Theme = 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+
+/** Semantic status themes for notices, alerts, feedback */
+export type ThemeStatus = 'info' | 'success' | 'warning' | 'danger';

package/utils/color/contrast.d.ts

@@ -0,0 +1,33 @@
+export type ContrastTone = 'light' | 'dark';
+/**
+ * Determine whether light or dark foreground provides better contrast.
+ * Uses WCAG relative luminance with 0.179 threshold.
+ *
+ * @param hex - Background color in #rgb or #rrggbb format
+ * @returns 'light' for dark backgrounds, 'dark' for light backgrounds
+ *
+ * Invalid input returns 'dark' (assumes light background).
+ * Relies on tests to catch invalid usage - no runtime throws.
+ *
+ * Approved use cases:
+ * - Avatar initials / fallback glyphs
+ * - User-selected background chips (reactions, labels)
+ * - One-off inline visuals where no semantic token exists
+ *
+ * NOT for core component theming - use semantic tokens instead.
+ */
+export declare function getContrastTone(hex: string): ContrastTone;
+/**
+ * Get a concrete foreground color value for a given background.
+ *
+ * @param hex - Background color in #rgb or #rrggbb format
+ * @param options.light - Color for dark backgrounds (default '#fff')
+ * @param options.dark - Color for light backgrounds (default '#000')
+ * @returns The appropriate foreground color
+ *
+ * Invalid input returns options.dark (assumes light background).
+ */
+export declare function getContrastForeground(hex: string, options?: {
+    light?: string;
+    dark?: string;
+}): string;

package/utils/color/contrast.js

@@ -0,0 +1,88 @@
+// Supports #rgb, #rrggbb, #rgba, #rrggbbaa (alpha is ignored for contrast calc)
+const HEX_PATTERN = /^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const LUMINANCE_THRESHOLD = 0.179;
+/**
+ * Parse hex color to RGB components (0-255).
+ * Supports #rgb, #rrggbb, #rgba, #rrggbbaa formats.
+ * Alpha channel is ignored (contrast is calculated on opaque color).
+ * Trims whitespace (common in user input).
+ * Returns null for invalid input.
+ */
+function parseHex(hex) {
+    const match = hex.trim().match(HEX_PATTERN);
+    if (!match)
+        return null;
+    const value = match[1];
+    if (value.length === 3 || value.length === 4) {
+        // #rgb or #rgba -> extract RGB only
+        return [
+            parseInt(value[0] + value[0], 16),
+            parseInt(value[1] + value[1], 16),
+            parseInt(value[2] + value[2], 16),
+        ];
+    }
+    // #rrggbb or #rrggbbaa -> extract RGB only
+    return [
+        parseInt(value.slice(0, 2), 16),
+        parseInt(value.slice(2, 4), 16),
+        parseInt(value.slice(4, 6), 16),
+    ];
+}
+/**
+ * Apply sRGB gamma correction to a channel value.
+ * Uses 0.04045 threshold (correct sRGB spec, not the common 0.03928 bug).
+ */
+function gammaCorrect(channel) {
+    const srgb = channel / 255;
+    return srgb <= 0.04045
+        ? srgb / 12.92
+        : Math.pow((srgb + 0.055) / 1.055, 2.4);
+}
+/**
+ * Calculate WCAG relative luminance.
+ */
+function getRelativeLuminance(r, g, b) {
+    return (0.2126 * gammaCorrect(r) +
+        0.7152 * gammaCorrect(g) +
+        0.0722 * gammaCorrect(b));
+}
+/**
+ * Determine whether light or dark foreground provides better contrast.
+ * Uses WCAG relative luminance with 0.179 threshold.
+ *
+ * @param hex - Background color in #rgb or #rrggbb format
+ * @returns 'light' for dark backgrounds, 'dark' for light backgrounds
+ *
+ * Invalid input returns 'dark' (assumes light background).
+ * Relies on tests to catch invalid usage - no runtime throws.
+ *
+ * Approved use cases:
+ * - Avatar initials / fallback glyphs
+ * - User-selected background chips (reactions, labels)
+ * - One-off inline visuals where no semantic token exists
+ *
+ * NOT for core component theming - use semantic tokens instead.
+ */
+export function getContrastTone(hex) {
+    const rgb = parseHex(hex);
+    // Invalid input: return 'dark' fallback (assumes light background)
+    if (!rgb)
+        return 'dark';
+    const luminance = getRelativeLuminance(...rgb);
+    return luminance <= LUMINANCE_THRESHOLD ? 'light' : 'dark';
+}
+/**
+ * Get a concrete foreground color value for a given background.
+ *
+ * @param hex - Background color in #rgb or #rrggbb format
+ * @param options.light - Color for dark backgrounds (default '#fff')
+ * @param options.dark - Color for light backgrounds (default '#000')
+ * @returns The appropriate foreground color
+ *
+ * Invalid input returns options.dark (assumes light background).
+ */
+export function getContrastForeground(hex, options = {}) {
+    const { light = '#fff', dark = '#000' } = options;
+    const tone = getContrastTone(hex);
+    return tone === 'light' ? light : dark;
+}

package/utils/color-scheme.d.ts

@@ -0,0 +1,25 @@
+export type ColorScheme = 'light' | 'dark' | 'auto';
+/**
+ * Set color scheme on a .tui-interface element.
+ *
+ * - 'light': Removes data-theme attribute (default state)
+ * - 'dark': Sets data-theme="dark"
+ * - 'auto': Sets data-theme="auto" (respects prefers-color-scheme)
+ *
+ * Note: 'auto' falls back to light if matchMedia is unsupported.
+ */
+export declare function setColorScheme(scheme: ColorScheme, root?: Element | null): void;
+/**
+ * Get current color scheme from a .tui-interface element.
+ * Returns 'light' if no data-theme attribute present.
+ */
+export declare function getColorScheme(root?: Element | null): ColorScheme;
+/**
+ * Get the resolved color scheme (what's actually displayed).
+ * For 'auto', checks prefers-color-scheme media query.
+ */
+export declare function getResolvedColorScheme(root?: Element | null): 'light' | 'dark';
+/**
+ * Toggle between light and dark (skips auto).
+ */
+export declare function toggleColorScheme(root?: Element | null): ColorScheme;

package/utils/color-scheme.js

@@ -0,0 +1,55 @@
+import { INTERFACE_SELECTOR } from '../constants.js';
+const ATTR = 'data-theme';
+/**
+ * Set color scheme on a .tui-interface element.
+ *
+ * - 'light': Removes data-theme attribute (default state)
+ * - 'dark': Sets data-theme="dark"
+ * - 'auto': Sets data-theme="auto" (respects prefers-color-scheme)
+ *
+ * Note: 'auto' falls back to light if matchMedia is unsupported.
+ */
+export function setColorScheme(scheme, root) {
+    const el = root ?? document.querySelector(INTERFACE_SELECTOR);
+    if (!el)
+        return;
+    if (scheme === 'light') {
+        el.removeAttribute(ATTR);
+    }
+    else {
+        el.setAttribute(ATTR, scheme);
+    }
+}
+/**
+ * Get current color scheme from a .tui-interface element.
+ * Returns 'light' if no data-theme attribute present.
+ */
+export function getColorScheme(root) {
+    const el = root ?? document.querySelector(INTERFACE_SELECTOR);
+    const attr = el?.getAttribute(ATTR);
+    return attr === 'dark' || attr === 'auto' ? attr : 'light';
+}
+/**
+ * Get the resolved color scheme (what's actually displayed).
+ * For 'auto', checks prefers-color-scheme media query.
+ */
+export function getResolvedColorScheme(root) {
+    const scheme = getColorScheme(root);
+    if (scheme === 'auto') {
+        // Fallback to light if matchMedia unavailable
+        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+            return 'light';
+        }
+        return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    }
+    return scheme;
+}
+/**
+ * Toggle between light and dark (skips auto).
+ */
+export function toggleColorScheme(root) {
+    const current = getColorScheme(root);
+    const next = current === 'dark' ? 'light' : 'dark';
+    setColorScheme(next, root);
+    return next;
+}

package/utils/compose-refs.d.ts

@@ -0,0 +1,17 @@
+import type { Ref, RefCallback } from 'react';
+/**
+ * Combines multiple refs into a single ref callback.
+ * Useful for components that need to forward refs while also maintaining
+ * an internal ref, or when using asChild pattern with ref composition.
+ *
+ * @example
+ * const MyComponent = forwardRef((props, forwardedRef) => {
+ *   const internalRef = useRef(null);
+ *   return <div ref={composeRefs(forwardedRef, internalRef)} />;
+ * });
+ */
+export declare function composeRefs<T>(...refs: (Ref<T> | undefined | null)[]): RefCallback<T>;
+/**
+ * Sets a single ref value. Handles both callback refs and ref objects.
+ */
+export declare function setRef<T>(ref: Ref<T> | undefined | null, value: T | null): void;

package/utils/compose-refs.js

@@ -0,0 +1,38 @@
+/**
+ * Combines multiple refs into a single ref callback.
+ * Useful for components that need to forward refs while also maintaining
+ * an internal ref, or when using asChild pattern with ref composition.
+ *
+ * @example
+ * const MyComponent = forwardRef((props, forwardedRef) => {
+ *   const internalRef = useRef(null);
+ *   return <div ref={composeRefs(forwardedRef, internalRef)} />;
+ * });
+ */
+export function composeRefs(...refs) {
+    return (node) => {
+        refs.forEach((ref) => {
+            if (!ref)
+                return;
+            if (typeof ref === 'function') {
+                ref(node);
+            }
+            else {
+                ref.current = node;
+            }
+        });
+    };
+}
+/**
+ * Sets a single ref value. Handles both callback refs and ref objects.
+ */
+export function setRef(ref, value) {
+    if (!ref)
+        return;
+    if (typeof ref === 'function') {
+        ref(value);
+    }
+    else {
+        ref.current = value;
+    }
+}

package/utils/cx.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Simple class name joiner - replaces clsx dependency
+ *
+ * Joins class name arguments, filtering out falsy values.
+ * Supports string, boolean, undefined, and null arguments.
+ *
+ * @example
+ * cx('base', 'modifier') // 'base modifier'
+ * cx('base', false && 'hidden') // 'base'
+ * cx('base', isActive && 'is-active', className) // 'base is-active custom'
+ */
+export declare function cx(...args: (string | boolean | undefined | null)[]): string;

package/utils/cx.js

@@ -0,0 +1,14 @@
+/**
+ * Simple class name joiner - replaces clsx dependency
+ *
+ * Joins class name arguments, filtering out falsy values.
+ * Supports string, boolean, undefined, and null arguments.
+ *
+ * @example
+ * cx('base', 'modifier') // 'base modifier'
+ * cx('base', false && 'hidden') // 'base'
+ * cx('base', isActive && 'is-active', className) // 'base is-active custom'
+ */
+export function cx(...args) {
+    return args.filter(Boolean).join(' ');
+}

package/utils/focus-trap.d.ts

@@ -0,0 +1,40 @@
+/**
+ * CSS selector for focusable elements.
+ * Used by focus trap and initial focus logic.
+ */
+export declare const FOCUSABLE_SELECTOR: string;
+/**
+ * Options for the focus trap hook.
+ */
+export type UseFocusTrapOptions = {
+    /** Whether the trap is currently active */
+    isActive: boolean;
+    /** Optional callback when Escape is pressed */
+    onEscape?: () => void;
+    /** Whether Escape should trigger onEscape (default: true) */
+    escapeDeactivates?: boolean;
+};
+/**
+ * Traps focus within a container element.
+ * Tab and Shift+Tab cycle through focusable elements inside the container.
+ * If no focusable elements exist, focus returns to the container itself.
+ *
+ * @param containerRef - Ref to the container element
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * const dialogRef = useRef<HTMLDivElement>(null);
+ * useFocusTrap(dialogRef, { isActive: isOpen, onEscape: onClose });
+ * ```
+ */
+export declare function useFocusTrap(containerRef: React.RefObject<HTMLElement | null>, options: UseFocusTrapOptions): void;
+/**
+ * Finds the first focusable element within a container.
+ * Optionally accepts a custom selector to try first.
+ *
+ * @param container - The container element to search within
+ * @param preferredSelector - Optional selector to try before fallback
+ * @returns The found element, or the container if nothing found
+ */
+export declare function getInitialFocus(container: HTMLElement, preferredSelector?: string): HTMLElement;

package/utils/focus-trap.js

@@ -0,0 +1,93 @@
+import { useEffect } from 'react';
+/**
+ * CSS selector for focusable elements.
+ * Used by focus trap and initial focus logic.
+ */
+export const FOCUSABLE_SELECTOR = [
+    '[data-autofocus]',
+    'a[href]',
+    'area[href]',
+    'button:not([disabled])',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    'iframe',
+    'audio[controls]',
+    'video[controls]',
+    '[contenteditable]:not([contenteditable="false"])',
+    '[tabindex]:not([tabindex="-1"])',
+].join(',');
+/**
+ * Traps focus within a container element.
+ * Tab and Shift+Tab cycle through focusable elements inside the container.
+ * If no focusable elements exist, focus returns to the container itself.
+ *
+ * @param containerRef - Ref to the container element
+ * @param options - Configuration options
+ *
+ * @example
+ * ```tsx
+ * const dialogRef = useRef<HTMLDivElement>(null);
+ * useFocusTrap(dialogRef, { isActive: isOpen, onEscape: onClose });
+ * ```
+ */
+export function useFocusTrap(containerRef, options) {
+    const { isActive, onEscape, escapeDeactivates = true } = options;
+    useEffect(() => {
+        if (!isActive)
+            return;
+        const container = containerRef.current;
+        if (!container)
+            return;
+        const handleKeyDown = (e) => {
+            // Escape handling
+            if (e.key === 'Escape' && escapeDeactivates && onEscape) {
+                onEscape();
+                return;
+            }
+            // Tab trap
+            if (e.key !== 'Tab')
+                return;
+            const nodes = Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((n) => n.offsetParent !== null || n === document.activeElement);
+            if (nodes.length === 0) {
+                e.preventDefault();
+                container.focus();
+                return;
+            }
+            const first = nodes[0];
+            const last = nodes[nodes.length - 1];
+            const active = document.activeElement;
+            if (e.shiftKey) {
+                if (active === first || !container.contains(active)) {
+                    e.preventDefault();
+                    last.focus();
+                }
+            }
+            else {
+                if (active === last || !container.contains(active)) {
+                    e.preventDefault();
+                    first.focus();
+                }
+            }
+        };
+        document.addEventListener('keydown', handleKeyDown);
+        return () => document.removeEventListener('keydown', handleKeyDown);
+    }, [isActive, containerRef, onEscape, escapeDeactivates]);
+}
+/**
+ * Finds the first focusable element within a container.
+ * Optionally accepts a custom selector to try first.
+ *
+ * @param container - The container element to search within
+ * @param preferredSelector - Optional selector to try before fallback
+ * @returns The found element, or the container if nothing found
+ */
+export function getInitialFocus(container, preferredSelector) {
+    if (preferredSelector) {
+        const preferred = container.querySelector(preferredSelector);
+        if (preferred)
+            return preferred;
+    }
+    const firstFocusable = container.querySelector(FOCUSABLE_SELECTOR);
+    return firstFocusable ?? container;
+}

package/utils/index.d.ts

@@ -0,0 +1,10 @@
+export { setColorScheme, getColorScheme, getResolvedColorScheme, toggleColorScheme } from './color-scheme';
+export type { ColorScheme } from './color-scheme';
+export { getPortalRoot, getPortalRootFor } from './portal';
+export { useFocusTrap, getInitialFocus, FOCUSABLE_SELECTOR } from './focus-trap';
+export { isAnchor, getSafeRel, getDisabledAnchorProps, getDisabledButtonProps, } from './polymorphic';
+export { composeRefs } from './compose-refs';
+export { mergeProps } from './merge-props';
+export { cx } from './cx';
+export { getContrastTone, getContrastForeground } from './color/contrast';
+export type { ContrastTone } from './color/contrast';

package/utils/index.js

@@ -0,0 +1,16 @@
+// Color scheme utilities
+export { setColorScheme, getColorScheme, getResolvedColorScheme, toggleColorScheme } from './color-scheme.js';
+// Portal utilities
+export { getPortalRoot, getPortalRootFor } from './portal.js';
+// Focus trap utilities
+export { useFocusTrap, getInitialFocus, FOCUSABLE_SELECTOR } from './focus-trap.js';
+// Polymorphic component utilities
+export { isAnchor, getSafeRel, getDisabledAnchorProps, getDisabledButtonProps, } from './polymorphic.js';
+// Ref composition
+export { composeRefs } from './compose-refs.js';
+// Prop merging
+export { mergeProps } from './merge-props.js';
+// Class name joining (replaces clsx)
+export { cx } from './cx.js';
+// Contrast utilities (for user-selected colors)
+export { getContrastTone, getContrastForeground } from './color/contrast.js';

package/utils/math.d.ts

@@ -0,0 +1,4 @@
+export declare const clamp: (value: number, min?: number, max?: number) => number;
+export declare const normalize: (value: number, currentScaleMin: number, currentScaleMax: number, newScaleMin?: number, newScaleMax?: number) => number;
+export declare const clampedNormalize: (value: number, currentScaleMin: number, currentScaleMax: number, newScaleMin?: number, newScaleMax?: number) => number;
+export declare const exponentialNormalize: (value: number, currentScaleMin: number, currentScaleMax: number, newScaleMin?: number, newScaleMax?: number, exponent?: number) => number;

package/utils/math.js

@@ -0,0 +1,19 @@
+export const clamp = (value, min = 0, max = 1) => {
+    if (min > max) {
+        [min, max] = [max, min];
+    }
+    return Math.max(min, Math.min(max, value));
+};
+export const normalize = (value, currentScaleMin, currentScaleMax, newScaleMin = 0, newScaleMax = 1) => {
+    const standardNormalization = (value - currentScaleMin) / (currentScaleMax - currentScaleMin);
+    return ((newScaleMax - newScaleMin) * standardNormalization + newScaleMin);
+};
+export const clampedNormalize = (value, currentScaleMin, currentScaleMax, newScaleMin = 0, newScaleMax = 1) => {
+    return clamp(normalize(value, currentScaleMin, currentScaleMax, newScaleMin, newScaleMax), newScaleMin, newScaleMax);
+};
+// Exponential interpolation, input is mapped onto a curved line rather than a straight one
+export const exponentialNormalize = (value, currentScaleMin, currentScaleMax, newScaleMin = 0, newScaleMax = 1, exponent = 2) => {
+    const normalizedInput = (value - currentScaleMin) / (currentScaleMax - currentScaleMin);
+    const exponentialOutput = Math.pow(normalizedInput, exponent);
+    return (newScaleMin + (newScaleMax - newScaleMin) * exponentialOutput);
+};

package/utils/merge-props.d.ts

@@ -0,0 +1,25 @@
+type AnyProps = Record<string, unknown>;
+/**
+ * Merges two sets of props, composing event handlers so both fire.
+ * Useful for extending component props without clobbering existing values.
+ *
+ * Merge rules:
+ * - Event handlers (on*): Both called in sequence (slotProps first, then overrideProps)
+ * - className: Concatenated with a space
+ * - style: Shallow merged (overrideProps wins conflicts)
+ * - Other props: overrideProps takes precedence
+ *
+ * Note: For asChild patterns where parent props must not be overridden
+ * (e.g., data-* attributes for registration), spread them after the merge:
+ *
+ * @example
+ * // Event handler composition
+ * mergeProps({ onClick: logClick }, { onClick: doAction })
+ * // Result: { onClick: [calls logClick, then doAction] }
+ *
+ * @example
+ * // Ensuring parent attribute wins
+ * cloneElement(child, { ...child.props, 'data-toolbar-item': '' })
+ */
+export declare function mergeProps<T extends AnyProps, U extends AnyProps>(slotProps: T, overrideProps: U): T & U;
+export {};