@idealyst/components 1.2.127 → 1.2.129

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/components",
-  "version": "1.2.127",
+  "version": "1.2.129",
   "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.127",
+    "@idealyst/theme": "^1.2.129",
     "@mdi/js": ">=7.0.0",
     "@mdi/react": ">=1.0.0",
     "@react-native-vector-icons/common": ">=12.0.0",
@@ -81,10 +81,10 @@
     "@mdi/react": {
       "optional": true
     },
-    "@react-navigation/bottom-tabs": {
+    "@react-native/normalize-colors": {
       "optional": true
     },
-    "@react-native/normalize-colors": {
+    "@react-navigation/bottom-tabs": {
       "optional": true
     },
     "react-native": {
@@ -111,8 +111,8 @@
   },
   "devDependencies": {
     "@idealyst/blur": "^1.2.40",
-    "@idealyst/theme": "^1.2.127",
-    "@idealyst/tooling": "^1.2.127",
+    "@idealyst/theme": "^1.2.129",
+    "@idealyst/tooling": "^1.2.129",
     "@mdi/react": "^1.6.1",
     "@types/react": "^19.1.0",
     "react": "^19.1.0",

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,
@@ -255,36 +256,34 @@ function TableInner<T = any>({
     return column.footer;
   };
 
-  return (
-    <ScrollView
-      ref={ref}
-      nativeID={id}
-      horizontal
-      style={[containerStyle, style]}
-      testID={testID}
-      {...nativeA11yProps}
-    >
-      <View style={tableStyle}>
-        {/* Header */}
-        <View style={theadStyle}>
-          <View style={{ flexDirection: 'row' }}>
-            {columns.map((column) => (
-              <TH
-                key={column.key}
-                size={size}
-                type={type}
-                align={column.align}
-                width={column.width}
-              >
-                {column.title}
-              </TH>
-            ))}
-          </View>
+  // Split columns into sticky left, scrollable, and sticky right
+  const leftCols = useMemo(() => columns.filter((c) => c.sticky === true || c.sticky === 'left'), [columns]);
+  const rightCols = useMemo(() => columns.filter((c) => c.sticky === 'right'), [columns]);
+  const scrollCols = useMemo(() => columns.filter((c) => !c.sticky), [columns]);
+  const hasStickyColumns = leftCols.length > 0 || rightCols.length > 0;
+
+  // Renders a column group (header + body + footer) for a set of columns
+  const renderColumnGroup = (cols: TableColumn<T>[]) => (
+    <View>
+      {/* Header */}
+      <View style={theadStyle}>
+        <View style={{ flexDirection: 'row' }}>
+          {cols.map((column) => (
+            <TH key={column.key} size={size} type={type} align={column.align} width={column.width}>
+              {column.title}
+            </TH>
+          ))}
         </View>
+      </View>
 
-        {/* Body */}
-        <View style={tbodyStyle}>
-          {data.map((row, rowIndex) => (
+      {/* Body */}
+      <View style={tbodyStyle}>
+        {data.length === 0 && emptyState ? (
+          <View style={{ alignItems: 'center', padding: 16 }}>
+            {emptyState}
+          </View>
+        ) : (
+          data.map((row, rowIndex) => (
             <TR
               key={rowIndex}
               size={size}
@@ -293,39 +292,71 @@ function TableInner<T = any>({
               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}
-                >
+              {cols.map((column) => (
+                <TD key={column.key} size={size} type={type} align={column.align} width={column.width}>
                   {getCellValue(column, row, rowIndex)}
                 </TD>
               ))}
             </TR>
-          ))}
+          ))
+        )}
+      </View>
+
+      {/* Footer */}
+      {hasFooter && (
+        <View style={(tableStyles.tfoot as any)({})}>
+          <View style={{ flexDirection: 'row' }}>
+            {cols.map((column) => (
+              <TF key={column.key} size={size} type={type} align={column.align} width={column.width}>
+                {getFooterContent(column) ?? null}
+              </TF>
+            ))}
+          </View>
         </View>
+      )}
+    </View>
+  );
 
-        {/* Footer */}
-        {hasFooter && (
-          <View style={(tableStyles.tfoot as any)({})}>
-            <View style={{ flexDirection: 'row' }}>
-              {columns.map((column) => (
-                <TF
-                  key={column.key}
-                  size={size}
-                  type={type}
-                  align={column.align}
-                  width={column.width}
-                >
-                  {getFooterContent(column) ?? null}
-                </TF>
-              ))}
-            </View>
+  // When there are sticky columns, render as: [left sticky] [scrollable] [right sticky]
+  if (hasStickyColumns) {
+    return (
+      <View
+        nativeID={id}
+        style={[containerStyle, { flexDirection: 'row' }, style]}
+        testID={testID}
+        {...nativeA11yProps}
+      >
+        {leftCols.length > 0 && (
+          <View style={{ zIndex: 1, backgroundColor: theadStyle.backgroundColor || containerStyle.backgroundColor }}>
+            {renderColumnGroup(leftCols)}
           </View>
         )}
+        <ScrollView ref={ref} horizontal style={{ flex: 1 }}>
+          <View style={tableStyle}>
+            {renderColumnGroup(scrollCols)}
+          </View>
+        </ScrollView>
+        {rightCols.length > 0 && (
+          <View style={{ zIndex: 1, backgroundColor: theadStyle.backgroundColor || containerStyle.backgroundColor }}>
+            {renderColumnGroup(rightCols)}
+          </View>
+        )}
+      </View>
+    );
+  }
+
+  // No sticky columns — original simple layout
+  return (
+    <ScrollView
+      ref={ref}
+      nativeID={id}
+      horizontal
+      style={[containerStyle, style]}
+      testID={testID}
+      {...nativeA11yProps}
+    >
+      <View style={tableStyle}>
+        {renderColumnGroup(columns)}
       </View>
     </ScrollView>
   );

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,9 +1,28 @@
-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';
 import { getWebAriaProps } from '../utils/accessibility';
 
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function getStickyStyle(
+  sticky: boolean | 'left' | 'right' | undefined,
+  offset: number | string | undefined,
+  zIndex: number,
+): React.CSSProperties | undefined {
+  if (!sticky) return undefined;
+  const side = sticky === 'right' ? 'right' : 'left';
+  return {
+    position: 'sticky',
+    [side]: offset ?? 0,
+    zIndex,
+    backgroundColor: 'inherit',
+  };
+}
+
 // ============================================================================
 // Sub-component Props
 // ============================================================================
@@ -23,6 +42,11 @@ interface THProps {
   type?: TableType;
   align?: TableAlignVariant;
   width?: number | string;
+  sticky?: boolean | 'left' | 'right';
+  stickyOffset?: number | string;
+  resizable?: boolean;
+  onResize?: (width: number) => void;
+  minWidth?: number;
   accessibilitySort?: 'ascending' | 'descending' | 'none' | 'other';
 }
 
@@ -32,6 +56,8 @@ interface TDProps {
   type?: TableType;
   align?: TableAlignVariant;
   width?: number | string;
+  sticky?: boolean | 'left' | 'right';
+  stickyOffset?: number | string;
 }
 
 // ============================================================================
@@ -75,6 +101,11 @@ function TH({
   type = 'standard',
   align = 'left',
   width,
+  sticky,
+  stickyOffset,
+  resizable,
+  onResize,
+  minWidth = 50,
   accessibilitySort,
 }: THProps) {
   tableStyles.useVariants({
@@ -84,15 +115,62 @@ 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]);
 
   return (
     <th
       {...headerCellProps}
+      ref={thRef}
       scope="col"
       aria-sort={accessibilitySort}
-      style={{ width }}
+      style={{ width, ...getStickyStyle(sticky, stickyOffset, 11) }}
     >
       {children}
+      {resizable && (
+        <span
+          onPointerDown={handlePointerDown}
+          style={{
+            position: 'absolute',
+            right: 0,
+            top: 0,
+            bottom: 0,
+            width: 4,
+            cursor: 'col-resize',
+            userSelect: 'none',
+          }}
+        />
+      )}
     </th>
   );
 }
@@ -107,6 +185,8 @@ function TD({
   type = 'standard',
   align = 'left',
   width,
+  sticky,
+  stickyOffset,
 }: TDProps) {
   tableStyles.useVariants({
     size,
@@ -119,7 +199,7 @@ function TD({
   return (
     <td
       {...cellProps}
-      style={{ width }}
+      style={{ width, ...getStickyStyle(sticky, stickyOffset, 1) }}
     >
       {children}
     </td>
@@ -136,6 +216,8 @@ interface TFProps {
   type?: TableType;
   align?: TableAlignVariant;
   width?: number | string;
+  sticky?: boolean | 'left' | 'right';
+  stickyOffset?: number | string;
 }
 
 function TF({
@@ -144,6 +226,8 @@ function TF({
   type = 'standard',
   align = 'left',
   width,
+  sticky,
+  stickyOffset,
 }: TFProps) {
   tableStyles.useVariants({
     size,
@@ -156,7 +240,7 @@ function TF({
   return (
     <td
       {...footerCellProps}
-      style={{ width }}
+      style={{ width, ...getStickyStyle(sticky, stickyOffset, 1) }}
     >
       {children}
     </td>
@@ -176,8 +260,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 +327,39 @@ function Table<T = any>({
     return column.footer;
   };
 
+  // Compute cumulative offsets for sticky columns (left and right independently)
+  const stickyOffsetMap = useMemo(() => {
+    const map = new Map<string, number>();
+
+    // Left sticky: accumulate left-to-right
+    let cumulativeLeft = 0;
+    for (const col of columns) {
+      const side = col.sticky === 'right' ? 'right' : col.sticky ? 'left' : null;
+      if (side !== 'left') continue;
+      map.set(col.key, cumulativeLeft);
+      if (typeof col.width === 'number') {
+        cumulativeLeft += col.width;
+      }
+    }
+
+    // Right sticky: accumulate right-to-left
+    let cumulativeRight = 0;
+    for (let i = columns.length - 1; i >= 0; i--) {
+      const col = columns[i];
+      if (col.sticky !== 'right') continue;
+      map.set(col.key, cumulativeRight);
+      if (typeof col.width === 'number') {
+        cumulativeRight += col.width;
+      }
+    }
+
+    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 +368,11 @@ function Table<T = any>({
                 type={type}
                 align={column.align}
                 width={column.width}
+                sticky={column.sticky}
+                stickyOffset={stickyOffsetMap.get(column.key)}
+                resizable={column.resizable}
+                minWidth={column.minWidth}
+                onResize={onColumnResize ? (w) => onColumnResize(column.key, w) : undefined}
                 accessibilitySort={column.accessibilitySort}
               >
                 {column.title}
@@ -261,28 +381,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}
+                    stickyOffset={stickyOffsetMap.get(column.key)}
+                  >
+                    {getCellValue(column, row, rowIndex)}
+                  </TD>
+                ))}
+              </TR>
+            ))
+          )}
         </tbody>
         {hasFooter && (
           <tfoot {...getWebProps([(tableStyles.tfoot as any)({})])}>
@@ -294,6 +424,8 @@ function Table<T = any>({
                   type={type}
                   align={column.align}
                   width={column.width}
+                  sticky={column.sticky}
+                  stickyOffset={stickyOffsetMap.get(column.key)}
                 >
                   {getFooterContent(column) ?? null}
                 </TF>

package/src/Table/types.ts

@@ -17,6 +17,21 @@ 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.
+   * `true` or `'left'` pins to the left, `'right'` pins to the right.
+   * On web uses CSS `position: sticky`, on native renders outside the ScrollView.
+   */
+  sticky?: boolean | 'left' | 'right';
+  /**
+   * 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 +48,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;