@tangible/ui 0.0.1

package/utils/merge-props.js

@@ -0,0 +1,60 @@
+/**
+ * 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 function mergeProps(slotProps, overrideProps) {
+    const result = { ...slotProps };
+    for (const key of Object.keys(overrideProps)) {
+        const slotValue = slotProps[key];
+        const overrideValue = overrideProps[key];
+        // Compose event handlers
+        if (key.startsWith('on') &&
+            typeof slotValue === 'function' &&
+            typeof overrideValue === 'function') {
+            result[key] = composeEventHandlers(slotValue, overrideValue);
+        }
+        // Concatenate classNames
+        else if (key === 'className') {
+            result[key] = [slotValue, overrideValue].filter(Boolean).join(' ');
+        }
+        // Merge style objects (overrideProps wins conflicts)
+        else if (key === 'style' &&
+            typeof slotValue === 'object' &&
+            typeof overrideValue === 'object') {
+            result[key] = { ...slotValue, ...overrideValue };
+        }
+        // overrideProps takes precedence for everything else
+        else if (overrideValue !== undefined) {
+            result[key] = overrideValue;
+        }
+    }
+    return result;
+}
+/**
+ * Composes two event handlers into one that calls both.
+ * The slot handler runs first, then the override handler.
+ */
+function composeEventHandlers(slotHandler, overrideHandler) {
+    return (...args) => {
+        slotHandler(...args);
+        overrideHandler(...args);
+    };
+}

package/utils/polymorphic.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Check if props indicate the component should render as an anchor.
+ */
+export declare function isAnchor<T extends {
+    href?: string;
+}>(props: T): props is T & {
+    href: string;
+};
+/**
+ * Get safe rel attribute for anchor elements.
+ * Adds noopener noreferrer for target="_blank" to prevent security issues.
+ */
+export declare function getSafeRel(target: React.HTMLAttributeAnchorTarget | undefined, rel: string | undefined): string | undefined;
+/**
+ * Common anchor props for disabled state.
+ */
+export declare function getDisabledAnchorProps(isDisabled: boolean, href: string | undefined, tabIndex: number | undefined): {
+    readonly href: string | undefined;
+    readonly tabIndex: number | undefined;
+    readonly 'aria-disabled': true | undefined;
+};
+/**
+ * Common button props for disabled state.
+ */
+export declare function getDisabledButtonProps(isDisabled: boolean): {
+    readonly disabled: boolean;
+    readonly 'aria-disabled': true | undefined;
+};

package/utils/polymorphic.js

@@ -0,0 +1,44 @@
+import { cx } from './cx.js';
+// =============================================================================
+// Polymorphic Button/Anchor Utilities
+// =============================================================================
+//
+// Shared logic for components that render as <button> or <a> based on href.
+// Used by Button and IconButton.
+//
+// =============================================================================
+/**
+ * Check if props indicate the component should render as an anchor.
+ */
+export function isAnchor(props) {
+    return typeof props.href === 'string';
+}
+/**
+ * Get safe rel attribute for anchor elements.
+ * Adds noopener noreferrer for target="_blank" to prevent security issues.
+ */
+export function getSafeRel(target, rel) {
+    if (target === '_blank') {
+        return cx(rel, 'noopener', 'noreferrer') || undefined;
+    }
+    return rel;
+}
+/**
+ * Common anchor props for disabled state.
+ */
+export function getDisabledAnchorProps(isDisabled, href, tabIndex) {
+    return {
+        href: isDisabled ? undefined : href,
+        tabIndex: isDisabled ? -1 : tabIndex,
+        'aria-disabled': isDisabled || undefined,
+    };
+}
+/**
+ * Common button props for disabled state.
+ */
+export function getDisabledButtonProps(isDisabled) {
+    return {
+        disabled: isDisabled,
+        'aria-disabled': isDisabled || undefined,
+    };
+}

package/utils/portal.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Gets or creates a portal root inside the first .tui-interface.
+ * If no interface wrapper exists, creates a global one at body level.
+ */
+export declare function getPortalRoot(): HTMLElement;
+/**
+ * Gets portal root for a specific element (finds its nearest .tui-interface ancestor).
+ * Reuses existing portal roots per interface container to prevent DOM accumulation.
+ * Always returns a valid portal root inside .tui-interface scope.
+ */
+export declare function getPortalRootFor(element: HTMLElement | null): HTMLElement;

package/utils/portal.js

@@ -0,0 +1,105 @@
+// =============================================================================
+// Portal Root Utility
+// =============================================================================
+//
+// GUARANTEE: Always returns a node inside `.tui-interface` scope.
+//
+// If no interface wrapper exists, creates one at document.body level.
+// Components using this utility can rely on token inheritance and
+// should NOT add their own `.tui-interface` wrapper.
+//
+// Usage:
+//   const root = getPortalRootFor(triggerRef.current);
+//   <FloatingPortal root={root}>...</FloatingPortal>
+//
+// =============================================================================
+import { PREFIX, INTERFACE_CLASS } from '../constants.js';
+const PORTAL_ID = `${PREFIX}-portal-root`;
+// Track which interface elements have portal roots (prevents accumulation)
+const portalRoots = new WeakMap();
+/**
+ * Creates a portal root element with proper styling.
+ */
+function createPortalRoot(id) {
+    const root = document.createElement('div');
+    root.id = id;
+    // Fixed positioning avoids issues with ancestor transforms/positioning
+    // pointer-events: none allows clicks to pass through to content below
+    // High z-index ensures portaled content (modals, tooltips) appears above page content
+    root.style.cssText =
+        'position: fixed; inset: 0; pointer-events: none; z-index: var(--tui-layer-portal, 9999);';
+    return root;
+}
+const GLOBAL_INTERFACE_ID = `${PREFIX}-global-interface`;
+/**
+ * Gets or creates a global .tui-interface wrapper at body level.
+ * Used as fallback when no interface wrapper exists in the DOM.
+ */
+function getOrCreateGlobalInterface() {
+    let globalInterface = document.getElementById(GLOBAL_INTERFACE_ID);
+    if (!globalInterface) {
+        globalInterface = document.createElement('div');
+        globalInterface.id = GLOBAL_INTERFACE_ID;
+        globalInterface.className = INTERFACE_CLASS;
+        document.body.appendChild(globalInterface);
+    }
+    return globalInterface;
+}
+/**
+ * Gets or creates a portal root inside the first .tui-interface.
+ * If no interface wrapper exists, creates a global one at body level.
+ */
+export function getPortalRoot() {
+    // Check if we already have a global portal root
+    let portalRoot = document.getElementById(PORTAL_ID);
+    if (portalRoot)
+        return portalRoot;
+    // Find the interface wrapper, or create global fallback
+    let interfaceEl = document.querySelector(`.${INTERFACE_CLASS}`);
+    if (!interfaceEl) {
+        interfaceEl = getOrCreateGlobalInterface();
+    }
+    // Create portal root inside the interface
+    portalRoot = createPortalRoot(PORTAL_ID);
+    interfaceEl.appendChild(portalRoot);
+    portalRoots.set(interfaceEl, portalRoot);
+    return portalRoot;
+}
+/**
+ * Gets portal root for a specific element (finds its nearest .tui-interface ancestor).
+ * Reuses existing portal roots per interface container to prevent DOM accumulation.
+ * Always returns a valid portal root inside .tui-interface scope.
+ */
+export function getPortalRootFor(element) {
+    if (!element)
+        return getPortalRoot();
+    // Find nearest interface ancestor
+    const interfaceEl = element.closest(`.${INTERFACE_CLASS}`);
+    if (!interfaceEl)
+        return getPortalRoot();
+    // Check WeakMap first (most common case after first render)
+    const cached = portalRoots.get(interfaceEl);
+    if (cached && interfaceEl.contains(cached))
+        return cached;
+    // Check if global portal root is inside this interface
+    const globalRoot = document.getElementById(PORTAL_ID);
+    if (globalRoot && interfaceEl.contains(globalRoot)) {
+        portalRoots.set(interfaceEl, globalRoot);
+        return globalRoot;
+    }
+    // Check for any existing portal root in this interface (handles SSR/hydration)
+    const existingRoot = interfaceEl.querySelector(`[id^="${PORTAL_ID}"]`);
+    if (existingRoot) {
+        portalRoots.set(interfaceEl, existingRoot);
+        return existingRoot;
+    }
+    // Create a scoped portal root for this interface
+    // Use a deterministic ID based on interface position to aid debugging
+    const allInterfaces = document.querySelectorAll(`.${INTERFACE_CLASS}`);
+    const index = Array.from(allInterfaces).indexOf(interfaceEl);
+    const scopedId = index === 0 ? PORTAL_ID : `${PORTAL_ID}-${index}`;
+    const portalRoot = createPortalRoot(scopedId);
+    interfaceEl.appendChild(portalRoot);
+    portalRoots.set(interfaceEl, portalRoot);
+    return portalRoot;
+}