@idealyst/components 1.2.126 → 1.2.128

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/components",
-  "version": "1.2.126",
+  "version": "1.2.128",
   "description": "Shared component library for React and React Native",
   "documentation": "https://github.com/IdealystIO/idealyst-framework/tree/main/packages/components#readme",
   "readme": "README.md",
@@ -56,7 +56,7 @@
     "publish:npm": "npm publish"
   },
   "peerDependencies": {
-    "@idealyst/theme": "^1.2.126",
+    "@idealyst/theme": "^1.2.128",
     "@mdi/js": ">=7.0.0",
     "@mdi/react": ">=1.0.0",
     "@react-native-vector-icons/common": ">=12.0.0",
@@ -111,8 +111,8 @@
   },
   "devDependencies": {
     "@idealyst/blur": "^1.2.40",
-    "@idealyst/theme": "^1.2.126",
-    "@idealyst/tooling": "^1.2.126",
+    "@idealyst/theme": "^1.2.128",
+    "@idealyst/tooling": "^1.2.128",
     "@mdi/react": "^1.6.1",
     "@types/react": "^19.1.0",
     "react": "^19.1.0",

package/src/TabBar/TabBar.native.tsx

@@ -173,7 +173,6 @@ const TabBar = forwardRef<IdealystElement, TabBarProps>(({
             // Apply icon variants (size, disabled, iconPosition)
             tabBarIconStyles.useVariants({
               size,
-              active: isActive,
               disabled: Boolean(item.disabled),
               iconPosition,
             });
@@ -181,7 +180,6 @@ const TabBar = forwardRef<IdealystElement, TabBarProps>(({
             // Compute dynamic styles for this tab - call as functions for theme reactivity
             const tabStyle = (tabBarTabStyles.tab as any)({ type, size, active: isActive, pillMode, justify });
             const labelStyle = (tabBarLabelStyles.tabLabel as any)({ type, active: isActive, pillMode });
-            const iconContainerStyle = (tabBarIconStyles.tabIcon as any)({});
 
             const icon = renderIcon(item.icon, isActive, iconSize);
 
@@ -201,7 +199,7 @@ const TabBar = forwardRef<IdealystElement, TabBarProps>(({
                 accessibilityLabel={item.label}
                 accessibilityState={{ selected: isActive, disabled: item.disabled }}
               >
-                {icon && <View style={iconContainerStyle}>{icon}</View>}
+                {icon && <View style={tabBarIconStyles.tabIcon as any}>{icon}</View>}
                 <Text style={labelStyle}>{item.label}</Text>
               </TouchableOpacity>
             );

package/src/TabBar/TabBar.styles.tsx

@@ -92,15 +92,24 @@ export const tabBarStyles = defineStyle('TabBar', (theme: Theme) => ({
     },
 
     tab: ({ type = 'standard', size = 'md', active = false, pillMode: _pillMode = 'light', disabled = false, iconPosition = 'left', justify = 'start' }: TabBarDynamicProps) => {
-        // Tab padding for pills — narrower than standard tabs
-        const pillsPaddingMap: Record<Size, { paddingVertical: number; paddingHorizontal: number }> = {
-            xs: { paddingVertical: 2, paddingHorizontal: 8 },
-            sm: { paddingVertical: 3, paddingHorizontal: 10 },
-            md: { paddingVertical: 4, paddingHorizontal: 12 },
-            lg: { paddingVertical: 6, paddingHorizontal: 16 },
-            xl: { paddingVertical: 8, paddingHorizontal: 20 },
+        // Resolve padding at runtime — can't use $iterator with runtime `type` check
+        // Use explicit top/bottom/left/right for cross-platform compatibility
+        const pillsPaddingMap: Record<Size, { paddingTop: number; paddingBottom: number; paddingLeft: number; paddingRight: number }> = {
+            xs: { paddingTop: 2, paddingBottom: 2, paddingLeft: 8, paddingRight: 8 },
+            sm: { paddingTop: 3, paddingBottom: 3, paddingLeft: 10, paddingRight: 10 },
+            md: { paddingTop: 4, paddingBottom: 4, paddingLeft: 12, paddingRight: 12 },
+            lg: { paddingTop: 6, paddingBottom: 6, paddingLeft: 16, paddingRight: 16 },
+            xl: { paddingTop: 8, paddingBottom: 8, paddingLeft: 20, paddingRight: 20 },
         };
-        const tabPadding = type === 'pills' ? pillsPaddingMap[size] : {};
+        const sizeValues = theme.sizes.tabBar[size];
+        const tabPadding = type === 'pills'
+            ? pillsPaddingMap[size]
+            : {
+                paddingTop: sizeValues.padding,
+                paddingBottom: sizeValues.padding,
+                paddingLeft: sizeValues.padding,
+                paddingRight: sizeValues.padding,
+            };
 
         // Color based on type and active state
         let color = active ? theme.colors.text.primary : theme.colors.text.secondary;
@@ -128,9 +137,6 @@ export const tabBarStyles = defineStyle('TabBar', (theme: Theme) => ({
                 size: {
                     fontSize: theme.sizes.$tabBar.fontSize,
                     lineHeight: theme.sizes.$tabBar.lineHeight,
-                    paddingTop: type === 'pills' ? undefined : theme.sizes.$tabBar.padding,
-                    paddingBottom: type === 'pills' ? undefined : theme.sizes.$tabBar.paddingBottom,
-                    paddingHorizontal: type === 'pills' ? undefined : theme.sizes.$tabBar.padding,
                 },
             },
             _web: {
@@ -165,19 +171,25 @@ export const tabBarStyles = defineStyle('TabBar', (theme: Theme) => ({
         } as const;
     },
 
-    tabIcon: ({ active: _active = false, disabled = false, iconPosition = 'left' }: TabBarDynamicProps) => ({
+    tabIcon: {
         display: 'flex' as const,
         alignItems: 'center' as const,
         justifyContent: 'center' as const,
-        opacity: disabled ? 0.5 : 1,
-        marginBottom: iconPosition === 'top' ? 2 : 0,
         variants: {
             size: {
                 width: theme.sizes.$tabBar.fontSize,
                 height: theme.sizes.$tabBar.fontSize,
             },
+            disabled: {
+                true: { opacity: 0.5 },
+                false: { opacity: 1 },
+            },
+            iconPosition: {
+                top: { marginBottom: 2 },
+                left: { marginBottom: 0 },
+            },
         },
-    }),
+    },
 
     indicator: ({ type = 'standard', pillMode = 'light' }: TabBarDynamicProps) => {
         const backgroundColor = type === 'pills'
@@ -186,8 +198,8 @@ export const tabBarStyles = defineStyle('TabBar', (theme: Theme) => ({
 
         const typeStyles = type === 'pills' ? {
             borderRadius: 9999,
-            bottom: 3,
-            top: 3,
+            top: 4,
+            bottom: 4,
             left: 0,
         } : {
             bottom: -1,

package/src/TabBar/TabBar.web.tsx

@@ -79,7 +79,6 @@ const Tab: React.FC<TabProps> = ({
   // Apply icon variants (size, disabled, iconPosition)
   tabBarIconStyles.useVariants({
     size,
-    active: isActive,
     disabled: Boolean(item.disabled),
     iconPosition,
   });

package/src/Table/Table.native.tsx

@@ -187,6 +187,7 @@ function TableInner<T = any>({
   size = 'md',
   stickyHeader: _stickyHeader = false,
   onRowPress,
+  emptyState,
   // Spacing variants from ContainerStyleProps
   gap,
   padding,
@@ -284,28 +285,34 @@ function TableInner<T = any>({
 
         {/* Body */}
         <View style={tbodyStyle}>
-          {data.map((row, rowIndex) => (
-            <TR
-              key={rowIndex}
-              size={size}
-              type={type}
-              clickable={isClickable}
-              onPress={() => onRowPress?.(row, rowIndex)}
-              testID={testID ? `${testID}-row-${rowIndex}` : undefined}
-            >
-              {columns.map((column) => (
-                <TD
-                  key={column.key}
-                  size={size}
-                  type={type}
-                  align={column.align}
-                  width={column.width}
-                >
-                  {getCellValue(column, row, rowIndex)}
-                </TD>
-              ))}
-            </TR>
-          ))}
+          {data.length === 0 && emptyState ? (
+            <View style={{ alignItems: 'center', padding: 16 }}>
+              {emptyState}
+            </View>
+          ) : (
+            data.map((row, rowIndex) => (
+              <TR
+                key={rowIndex}
+                size={size}
+                type={type}
+                clickable={isClickable}
+                onPress={() => onRowPress?.(row, rowIndex)}
+                testID={testID ? `${testID}-row-${rowIndex}` : undefined}
+              >
+                {columns.map((column) => (
+                  <TD
+                    key={column.key}
+                    size={size}
+                    type={type}
+                    align={column.align}
+                    width={column.width}
+                  >
+                    {getCellValue(column, row, rowIndex)}
+                  </TD>
+                ))}
+              </TR>
+            ))
+          )}
         </View>
 
         {/* Footer */}

package/src/Table/Table.styles.tsx

@@ -176,6 +176,7 @@ export const tableStyles = defineStyle('Table', (theme: Theme) => ({
             },
         },
         _web: {
+            position: 'relative',
             borderBottom: `2px solid ${theme.colors.border.primary}`,
             borderRight: type === 'bordered' ? `1px solid ${theme.colors.border.primary}` : undefined,
             ':last-child': type === 'bordered' ? { borderRight: 'none' } : {},

package/src/Table/Table.web.tsx

@@ -1,4 +1,4 @@
-import { useMemo, ReactNode } from 'react';
+import { useMemo, useRef, useCallback, ReactNode } from 'react';
 import { getWebProps } from 'react-native-unistyles/web';
 import { tableStyles } from './Table.styles';
 import type { TableProps, TableColumn, TableType, TableSizeVariant, TableAlignVariant } from './types';
@@ -23,6 +23,11 @@ interface THProps {
   type?: TableType;
   align?: TableAlignVariant;
   width?: number | string;
+  sticky?: boolean;
+  stickyLeft?: number | string;
+  resizable?: boolean;
+  onResize?: (width: number) => void;
+  minWidth?: number;
   accessibilitySort?: 'ascending' | 'descending' | 'none' | 'other';
 }
 
@@ -32,6 +37,8 @@ interface TDProps {
   type?: TableType;
   align?: TableAlignVariant;
   width?: number | string;
+  sticky?: boolean;
+  stickyLeft?: number | string;
 }
 
 // ============================================================================
@@ -75,6 +82,11 @@ function TH({
   type = 'standard',
   align = 'left',
   width,
+  sticky,
+  stickyLeft,
+  resizable,
+  onResize,
+  minWidth = 50,
   accessibilitySort,
 }: THProps) {
   tableStyles.useVariants({
@@ -84,15 +96,69 @@ function TH({
   });
 
   const headerCellProps = getWebProps([(tableStyles.headerCell as any)({})]);
+  const thRef = useRef<HTMLTableCellElement>(null);
+
+  const handlePointerDown = useCallback((e: React.PointerEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    const th = thRef.current;
+    if (!th) return;
+
+    const startX = e.clientX;
+    const startWidth = th.getBoundingClientRect().width;
+
+    const handlePointerMove = (moveEvent: PointerEvent) => {
+      const newWidth = Math.max(minWidth, startWidth + (moveEvent.clientX - startX));
+      th.style.width = `${newWidth}px`;
+    };
+
+    const handlePointerUp = (_upEvent: PointerEvent) => {
+      document.removeEventListener('pointermove', handlePointerMove);
+      document.removeEventListener('pointerup', handlePointerUp);
+      const finalWidth = th.getBoundingClientRect().width;
+      onResize?.(finalWidth);
+      // Remove inline cursor override
+      document.body.style.cursor = '';
+      document.body.style.userSelect = '';
+    };
+
+    // Prevent text selection and set resize cursor globally during drag
+    document.body.style.cursor = 'col-resize';
+    document.body.style.userSelect = 'none';
+    document.addEventListener('pointermove', handlePointerMove);
+    document.addEventListener('pointerup', handlePointerUp);
+  }, [minWidth, onResize]);
+
+  const stickyStyle: React.CSSProperties | undefined = sticky ? {
+    position: 'sticky',
+    left: stickyLeft ?? 0,
+    zIndex: 11,
+    backgroundColor: 'inherit',
+  } : undefined;
 
   return (
     <th
       {...headerCellProps}
+      ref={thRef}
       scope="col"
       aria-sort={accessibilitySort}
-      style={{ width }}
+      style={{ width, ...stickyStyle }}
     >
       {children}
+      {resizable && (
+        <span
+          onPointerDown={handlePointerDown}
+          style={{
+            position: 'absolute',
+            right: 0,
+            top: 0,
+            bottom: 0,
+            width: 4,
+            cursor: 'col-resize',
+            userSelect: 'none',
+          }}
+        />
+      )}
     </th>
   );
 }
@@ -107,6 +173,8 @@ function TD({
   type = 'standard',
   align = 'left',
   width,
+  sticky,
+  stickyLeft,
 }: TDProps) {
   tableStyles.useVariants({
     size,
@@ -116,10 +184,17 @@ function TD({
 
   const cellProps = getWebProps([(tableStyles.cell as any)({})]);
 
+  const stickyStyle: React.CSSProperties | undefined = sticky ? {
+    position: 'sticky',
+    left: stickyLeft ?? 0,
+    zIndex: 1,
+    backgroundColor: 'inherit',
+  } : undefined;
+
   return (
     <td
       {...cellProps}
-      style={{ width }}
+      style={{ width, ...stickyStyle }}
     >
       {children}
     </td>
@@ -136,6 +211,8 @@ interface TFProps {
   type?: TableType;
   align?: TableAlignVariant;
   width?: number | string;
+  sticky?: boolean;
+  stickyLeft?: number | string;
 }
 
 function TF({
@@ -144,6 +221,8 @@ function TF({
   type = 'standard',
   align = 'left',
   width,
+  sticky,
+  stickyLeft,
 }: TFProps) {
   tableStyles.useVariants({
     size,
@@ -153,10 +232,17 @@ function TF({
 
   const footerCellProps = getWebProps([(tableStyles.footerCell as any)({})]);
 
+  const stickyStyle: React.CSSProperties | undefined = sticky ? {
+    position: 'sticky',
+    left: stickyLeft ?? 0,
+    zIndex: 1,
+    backgroundColor: 'inherit',
+  } : undefined;
+
   return (
     <td
       {...footerCellProps}
-      style={{ width }}
+      style={{ width, ...stickyStyle }}
     >
       {children}
     </td>
@@ -176,8 +262,10 @@ function Table<T = any>({
   data,
   type = 'standard',
   size = 'md',
-  stickyHeader: _stickyHeader = false,
+  stickyHeader = false,
   onRowPress,
+  onColumnResize,
+  emptyState,
   // Spacing variants from ContainerStyleProps
   gap,
   padding,
@@ -241,10 +329,28 @@ function Table<T = any>({
     return column.footer;
   };
 
+  // Compute cumulative left offsets for sticky columns
+  const stickyLeftMap = useMemo(() => {
+    const map = new Map<string, number | string>();
+    let cumulativeLeft = 0;
+    for (const col of columns) {
+      if (!col.sticky) continue;
+      map.set(col.key, cumulativeLeft);
+      if (typeof col.width === 'number') {
+        cumulativeLeft += col.width;
+      } else if (typeof col.width === 'string') {
+        // For string widths (e.g. '200px'), use as-is for the first, then can't accumulate
+        // Only numeric widths support proper multi-column stacking
+        map.set(col.key, cumulativeLeft > 0 ? cumulativeLeft : 0);
+      }
+    }
+    return map;
+  }, [columns]);
+
   return (
     <div {...containerProps} {...ariaProps} id={id} data-testid={testID}>
       <table {...tableProps} role="table">
-        <thead {...getWebProps([(tableStyles.thead as any)({})])}>
+        <thead {...getWebProps([(tableStyles.thead as any)({ sticky: stickyHeader })])}>
           <tr>
             {columns.map((column) => (
               <TH
@@ -253,6 +359,11 @@ function Table<T = any>({
                 type={type}
                 align={column.align}
                 width={column.width}
+                sticky={column.sticky}
+                stickyLeft={stickyLeftMap.get(column.key)}
+                resizable={column.resizable}
+                minWidth={column.minWidth}
+                onResize={onColumnResize ? (w) => onColumnResize(column.key, w) : undefined}
                 accessibilitySort={column.accessibilitySort}
               >
                 {column.title}
@@ -261,28 +372,38 @@ function Table<T = any>({
           </tr>
         </thead>
         <tbody {...getWebProps([(tableStyles.tbody as any)({})])}>
-          {data.map((row, rowIndex) => (
-            <TR
-              key={rowIndex}
-              size={size}
-              type={type}
-              clickable={isClickable}
-              onClick={() => onRowPress?.(row, rowIndex)}
-              testID={testID ? `${testID}-row-${rowIndex}` : undefined}
-            >
-              {columns.map((column) => (
-                <TD
-                  key={column.key}
-                  size={size}
-                  type={type}
-                  align={column.align}
-                  width={column.width}
-                >
-                  {getCellValue(column, row, rowIndex)}
-                </TD>
-              ))}
-            </TR>
-          ))}
+          {data.length === 0 && emptyState ? (
+            <tr>
+              <td colSpan={columns.length} style={{ textAlign: 'center' }}>
+                {emptyState}
+              </td>
+            </tr>
+          ) : (
+            data.map((row, rowIndex) => (
+              <TR
+                key={rowIndex}
+                size={size}
+                type={type}
+                clickable={isClickable}
+                onClick={() => onRowPress?.(row, rowIndex)}
+                testID={testID ? `${testID}-row-${rowIndex}` : undefined}
+              >
+                {columns.map((column) => (
+                  <TD
+                    key={column.key}
+                    size={size}
+                    type={type}
+                    align={column.align}
+                    width={column.width}
+                    sticky={column.sticky}
+                    stickyLeft={stickyLeftMap.get(column.key)}
+                  >
+                    {getCellValue(column, row, rowIndex)}
+                  </TD>
+                ))}
+              </TR>
+            ))
+          )}
         </tbody>
         {hasFooter && (
           <tfoot {...getWebProps([(tableStyles.tfoot as any)({})])}>
@@ -294,6 +415,8 @@ function Table<T = any>({
                   type={type}
                   align={column.align}
                   width={column.width}
+                  sticky={column.sticky}
+                  stickyLeft={stickyLeftMap.get(column.key)}
                 >
                   {getFooterContent(column) ?? null}
                 </TF>

package/src/Table/types.ts

@@ -17,6 +17,20 @@ export interface TableColumn<T = any> extends SortableAccessibilityProps {
   footer?: ReactNode | ((data: T[]) => ReactNode);
   width?: number | string;
   align?: TableAlignVariant;
+  /**
+   * Makes this column sticky (pinned) when scrolling horizontally.
+   * Web only — uses CSS `position: sticky`.
+   */
+  sticky?: boolean;
+  /**
+   * Allows the column to be resized by dragging the right edge of the header.
+   * Web only.
+   */
+  resizable?: boolean;
+  /**
+   * Minimum width when resizing (default: 50).
+   */
+  minWidth?: number;
 }
 
 /**
@@ -33,6 +47,16 @@ export interface TableProps<T = any> extends ContainerStyleProps, AccessibilityP
   size?: TableSizeVariant;
   stickyHeader?: boolean;
   onRowPress?: (row: T, index: number) => void;
+  /**
+   * Called when a column is resized via drag handle.
+   * Receives the column key and the new width in pixels.
+   */
+  onColumnResize?: (key: string, width: number) => void;
+  /**
+   * Content to display when `data` is empty.
+   * Renders in place of the table body.
+   */
+  emptyState?: ReactNode;
   style?: StyleProp<ViewStyle>;
   testID?: string;
 }

package/src/TextArea/TextArea.native.tsx

@@ -1,13 +1,12 @@
-import { useState, forwardRef, useMemo, useEffect, useRef } from 'react';
+import { useState, forwardRef, useMemo, useEffect, useRef, useImperativeHandle } from 'react';
 import { View, TextInput, NativeSyntheticEvent, TextInputContentSizeChangeEventData, TextInput as RNTextInput } from 'react-native';
 import { textAreaStyles } from './TextArea.styles';
 import Text from '../Text';
 import type { TextAreaProps } from './types';
 import { getNativeFormAccessibilityProps } from '../utils/accessibility';
-import type { IdealystElement } from '../utils/refTypes';
-import useMergeRefs from '../hooks/useMergeRefs';
+import type { TextInputHandle } from '../utils/refTypes';
 
-const TextArea = forwardRef<IdealystElement, TextAreaProps>(({
+const TextArea = forwardRef<TextInputHandle, TextAreaProps>(({
   value: controlledValue,
   defaultValue = '',
   onChange,
@@ -52,6 +51,12 @@ const TextArea = forwardRef<IdealystElement, TextAreaProps>(({
   const [contentHeight, setContentHeight] = useState<number | undefined>(undefined);
   const textInputRef = useRef<RNTextInput>(null);
 
+  // Expose focus/blur via imperative handle
+  useImperativeHandle(ref, () => ({
+    focus: () => textInputRef.current?.focus(),
+    blur: () => textInputRef.current?.blur(),
+  }), []);
+
   const value = controlledValue !== undefined ? controlledValue : internalValue;
 
   // When value is cleared externally, trigger a layout recalculation via setNativeProps
@@ -175,7 +180,7 @@ const TextArea = forwardRef<IdealystElement, TextAreaProps>(({
 
       <View style={[textareaContainerStyleComputed, fill && { flex: 1 }]}>
         <TextInput
-          ref={useMergeRefs(textInputRef, ref as any)}
+          ref={textInputRef}
           {...nativeA11yProps}
           style={[
             textareaStyleComputed,

package/src/TextArea/TextArea.web.tsx

@@ -1,16 +1,16 @@
-import React, { useState, useRef, useEffect, forwardRef, useMemo, useCallback } from 'react';
+import React, { useState, useRef, useEffect, forwardRef, useMemo, useCallback, useImperativeHandle } from 'react';
 import { getWebProps } from 'react-native-unistyles/web';
 import { textAreaStyles } from './TextArea.styles';
 import type { TextAreaProps } from './types';
 import useMergeRefs from '../hooks/useMergeRefs';
 import { getWebFormAriaProps, combineIds, generateAccessibilityId } from '../utils/accessibility';
-import type { IdealystElement } from '../utils/refTypes';
+import type { TextInputHandle } from '../utils/refTypes';
 
 /**
  * Multi-line text input with auto-grow, character counting, and validation support.
  * Includes label, helper text, and error message display.
  */
-const TextArea = forwardRef<IdealystElement, TextAreaProps>(({
+const TextArea = forwardRef<TextInputHandle, TextAreaProps>(({
   value: controlledValue,
   defaultValue = '',
   onChange,
@@ -61,6 +61,12 @@ const TextArea = forwardRef<IdealystElement, TextAreaProps>(({
   const [isFocused, setIsFocused] = useState(false);
   const textareaRef = useRef<HTMLTextAreaElement>(null);
 
+  // Expose focus/blur via imperative handle
+  useImperativeHandle(ref, () => ({
+    focus: () => textareaRef.current?.focus(),
+    blur: () => textareaRef.current?.blur(),
+  }), []);
+
   const value = controlledValue !== undefined ? controlledValue : internalValue;
   const hasError = Boolean(error);
 
@@ -240,11 +246,10 @@ const TextArea = forwardRef<IdealystElement, TextAreaProps>(({
     overflowStyle,
   ].filter(Boolean));
 
-  const mergedRef = useMergeRefs(ref, containerProps.ref);
   const mergedTextareaRef = useMergeRefs(textareaRef, computedTextareaProps.ref);
 
   return (
-    <div {...containerProps} ref={mergedRef} id={id} data-testid={testID} style={{ ...containerProps.style as any, ...(fill ? { flex: 1, display: 'flex', flexDirection: 'column' } : {}) }}>
+    <div {...containerProps} id={id} data-testid={testID} style={{ ...(containerProps as any).style, ...(fill ? { flex: 1, display: 'flex', flexDirection: 'column' } : {}) }}>
       {label && (
         <label {...labelProps} id={labelId} htmlFor={textareaId}>{label}</label>
       )}

package/src/TextInput/TextInput.native.tsx

@@ -1,11 +1,11 @@
-import React, { useState, isValidElement, useMemo, useEffect, useRef, useCallback } from 'react';
+import React, { useState, isValidElement, useMemo, useEffect, useRef, useCallback, useImperativeHandle } from 'react';
 import { View, TextInput as RNTextInput, TouchableOpacity, Platform, TextInputProps as RNTextInputProps } from 'react-native';
 import MaterialDesignIcons from '@react-native-vector-icons/material-design-icons';
 import { useUnistyles } from 'react-native-unistyles';
 import { TextInputProps } from './types';
 import { textInputStyles } from './TextInput.styles';
 import { getNativeFormAccessibilityProps } from '../utils/accessibility';
-import type { IdealystElement } from '../utils/refTypes';
+import type { TextInputHandle } from '../utils/refTypes';
 import Text from '../Text';
 
 // Inner TextInput component that can be memoized to prevent re-renders
@@ -52,7 +52,7 @@ const InnerRNTextInput = React.memo<InnerTextInputProps>(
   }
 );
 
-const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
+const TextInput = React.forwardRef<TextInputHandle, TextInputProps>(({
   value,
   onChangeText,
   onFocus,
@@ -94,6 +94,13 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
 }, ref) => {
   const [isFocused, setIsFocused] = useState(false);
   const [isPasswordVisible, setIsPasswordVisible] = useState(false);
+  const inputRef = useRef<RNTextInput>(null);
+
+  // Expose focus/blur via imperative handle
+  useImperativeHandle(ref, () => ({
+    focus: () => inputRef.current?.focus(),
+    blur: () => inputRef.current?.blur(),
+  }), []);
 
   // Derive hasError from error prop or hasError boolean
   const computedHasError = Boolean(error) || hasError;
@@ -311,7 +318,7 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
 
         {/* Input */}
         <InnerRNTextInput
-          inputRef={ref}
+          inputRef={inputRef}
           value={value}
           onChangeText={handleChangeText}
           isAndroidSecure={needsAndroidSecureWorkaround}
@@ -359,7 +366,7 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
 
         {/* Input */}
         <InnerRNTextInput
-          inputRef={ref}
+          inputRef={inputRef}
           value={value}
           onChangeText={handleChangeText}
           isAndroidSecure={needsAndroidSecureWorkaround}

package/src/TextInput/TextInput.web.tsx

@@ -1,4 +1,4 @@
-import React, { isValidElement, useState, useMemo, useRef } from 'react';
+import React, { isValidElement, useState, useMemo, useRef, useImperativeHandle } from 'react';
 import { getWebProps } from 'react-native-unistyles/web';
 import { useUnistyles } from 'react-native-unistyles';
 import { IconSvg } from '../Icon/IconSvg/IconSvg.web';
@@ -7,14 +7,14 @@ import useMergeRefs from '../hooks/useMergeRefs';
 import { textInputStyles } from './TextInput.styles';
 import { TextInputProps } from './types';
 import { getWebFormAriaProps, combineIds, generateAccessibilityId } from '../utils/accessibility';
-import type { IdealystElement } from '../utils/refTypes';
+import type { TextInputHandle } from '../utils/refTypes';
 import { flattenStyle } from '../utils/flattenStyle';
 
 /**
  * Single-line text input field with support for icons, password visibility toggle, and validation states.
  * Available in outlined and filled variants with multiple sizes.
  */
-const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
+const TextInput = React.forwardRef<TextInputHandle, TextInputProps>(({
   value,
   onChangeText,
   onFocus,
@@ -234,8 +234,15 @@ const TextInput = React.forwardRef<IdealystElement, TextInputProps>(({
     accessibilityAutoComplete,
   ]);
 
-  // Merge the forwarded ref with unistyles ref for the input
-  const mergedInputRef = useMergeRefs(ref, inputWebProps.ref);
+  // Internal ref for the actual <input> element
+  const inputRef = useRef<HTMLInputElement>(null);
+  const mergedInputRef = useMergeRefs(inputRef, inputWebProps.ref);
+
+  // Expose focus/blur via imperative handle
+  useImperativeHandle(ref, () => ({
+    focus: () => inputRef.current?.focus(),
+    blur: () => inputRef.current?.blur(),
+  }), []);
 
   // Helper to render left icon
   const renderLeftIcon = () => {

package/src/index.ts

@@ -210,6 +210,7 @@ export * from './utils/buildViewStyleVariants';
 // Cross-platform ref types
 export type {
   IdealystElement,
+  TextInputHandle,
   AnchorElement,
   AnchorRef,
   ComponentElement,

package/src/utils/refTypes.ts

@@ -44,6 +44,24 @@ export type CrossPlatformElement = IdealystElement;
  */
 export type CrossPlatformRef = React.RefObject<IdealystElement>;
 
+/**
+ * Imperative handle for text input components (TextInput, TextArea).
+ * Provides cross-platform focus/blur control via refs.
+ *
+ * @example
+ * ```tsx
+ * const inputRef = React.useRef<TextInputHandle>(null);
+ * inputRef.current?.focus();
+ * inputRef.current?.blur();
+ * ```
+ */
+export interface TextInputHandle {
+  /** Programmatically focus the input */
+  focus: () => void;
+  /** Programmatically blur the input */
+  blur: () => void;
+}
+
 // Legacy exports kept for backwards compatibility
 export type WebElement = IdealystElement;
 export type NativeElement = IdealystElement;