@hero-design/rn-work-uikit 1.9.0 → 1.9.2

package/.cursor/rules/performance-optimization.mdc

@@ -0,0 +1,64 @@
+---
+pattern: "**/*.{ts,tsx}"
+description: "Performance optimization rules for React Native components in rn-work-uikit package"
+---
+
+# Performance Optimization Rules for RN Work UIKit
+
+## React Native Performance Best Practices
+
+### Component Optimization
+- Use `React.memo()` for components that receive stable props
+- Implement `useMemo()` for expensive calculations
+- Use `useCallback()` for event handlers passed to child components
+- Avoid creating objects/functions in render methods
+- Prefer `useState` functional updates when state depends on previous state
+
+### List Performance
+- Use `FlatList` or `SectionList` instead of `ScrollView` with `map()`
+- Implement `getItemLayout` for `FlatList` when item heights are known
+- Use `keyExtractor` prop for consistent item identification
+- Implement `removeClippedSubviews` for large lists
+- Use `windowSize` and `initialNumToRender` for performance tuning
+
+### Memory Management
+- Clean up subscriptions in `useEffect` cleanup functions
+- Use `InteractionManager.runAfterInteractions()` for non-critical operations
+- Avoid memory leaks by properly unmounting components
+- Use `React.useRef()` instead of `useState` for mutable values
+- Implement proper error boundaries to prevent crashes
+
+### Animation Performance
+- Use `Animated` API for smooth 60fps animations
+- Prefer `transform` and `opacity` animations over layout changes
+- Use `useNativeDriver: true` when possible
+- Avoid animating `width`, `height`, or `top` properties
+- Use `LayoutAnimation` for list item changes
+
+### Bundle Size Optimization
+- Use dynamic imports for large components (`React.lazy()`)
+- Implement code splitting for feature modules
+- Remove unused dependencies and imports
+- Use tree shaking compatible libraries
+- Optimize asset sizes and formats
+
+### Work-Specific Performance Considerations
+- Test with work-typical data sizes (large datasets, complex forms)
+- Optimize for work app's specific use cases
+- Ensure smooth performance on older devices
+- Test with work theme overrides and custom styling
+- Monitor performance metrics in work environment
+
+### Performance Monitoring
+- Use React DevTools Profiler for component analysis
+- Implement performance logging for critical paths
+- Monitor memory usage during development
+- Test performance on various device types
+- Use Flipper for React Native debugging
+
+### Anti-Patterns to Avoid
+- Don't use `console.log` in production builds
+- Avoid inline object/function creation in render
+- Don't use `setState` in render methods
+- Avoid unnecessary re-renders with proper dependency arrays
+- Don't ignore performance warnings from React Native

package/.cursor/rules/rn-work-uikit-rules.mdc

@@ -0,0 +1,202 @@
+---
+pattern: "**/*.{ts,tsx}"
+description: "Work-specific React Native component library rules extending base rn package"
+alwaysApply: false
+---
+
+# RN Work UIKit Specific Rules
+
+## Package Context
+This is the work-specific React Native component library that extends @hero-design/rn with work-focused components like TextInput, specialized themes, and work-specific patterns.
+
+## Component Structure Guidelines
+
+### File Organization
+- **Component files**: `ComponentName/index.tsx` (main component)
+- **Styled components**: `ComponentName/StyledComponentName.tsx` (e.g., `StyledTextInput.tsx`)
+- **Sub-components**: `ComponentName/SubComponent.tsx` (e.g., `FloatingLabel.tsx`, `ErrorOrHelpText.tsx`)
+- **Types**: `ComponentName/types.ts` (if complex types are needed)
+- **Tests**: `ComponentName/__tests__/ComponentName.spec.tsx`
+
+### Component Structure Example
+```tsx
+// TextInput/index.tsx
+import React, { forwardRef, useCallback } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { StyledContainer, StyledBorder, StyledInputWrapper } from './StyledTextInput';
+import { useTheme } from '../../theme';
+import FloatingLabel from './FloatingLabel';
+import InputRow from './InputRow';
+import type { TextInputProps, TextInputHandles } from './types';
+
+export interface TextInputProps {
+  /** Label for the input field */
+  label?: string;
+  /** Error message to display */
+  error?: string;
+  /** Help text to display below input */
+  helpText?: string;
+  /** Whether the field is required */
+  required?: boolean;
+  /** Whether the field is disabled */
+  disabled?: boolean;
+  /** Input value */
+  value?: string;
+  /** Input variant */
+  variant?: 'text' | 'textarea';
+  /** Additional style */
+  style?: StyleProp<ViewStyle>;
+  /** Testing id */
+  testID?: string;
+}
+
+export const InternalTextInput = forwardRef<TextInputHandles, TextInputProps>(
+  ({ label, error, helpText, required, disabled = false, value, variant = 'text', style, testID, ...props }, ref) => {
+    const [isFocused, setIsFocused] = React.useState(false);
+    const theme = useTheme();
+    
+    const handleFocus = useCallback(() => setIsFocused(true), []);
+    const handleBlur = useCallback(() => setIsFocused(false), []);
+
+    return (
+      <StyledContainer
+        style={style}
+        themeFocused={isFocused}
+        themeHasError={!!error}
+        testID={testID}
+      >
+        <StyledBorder themeFocused={isFocused} themeState={getState({ disabled, error })} />
+        <StyledInputWrapper>
+          {!!label && (
+            <FloatingLabel
+              label={label}
+              variant={variant}
+              isFocused={isFocused}
+              required={required}
+            />
+          )}
+          <InputRow
+            variant={variant}
+            nativeInputProps={{
+              ...props,
+              onFocus: handleFocus,
+              onBlur: handleBlur,
+              value,
+            }}
+          />
+          <ErrorOrHelpText error={error} helpText={helpText} />
+        </StyledInputWrapper>
+      </StyledContainer>
+    );
+  }
+);
+```
+
+### Styled Component Conventions
+- **Naming**: `const StyledComponentName = styled.View\`\``
+- **Props naming**: Use descriptive names like `themeFocused`, `themeHasError`, `themeState`
+- **Theme access**: Use component-specific theme tokens via `theme.__hd__.componentName.*` instead of global theme tokens
+
+```tsx
+// StyledTextInput.tsx
+import styled from '@emotion/native';
+
+interface StyledTextInputProps {
+  themeFocused: boolean;
+  themeHasError: boolean;
+}
+
+const StyledContainer = styled.View<StyledTextInputProps>`
+  ${({ theme, themeFocused, themeHasError }) => `
+    background-color: ${theme.__hd__.textInput.colors.containerBackground};
+    border-color: ${themeFocused 
+      ? theme.__hd__.textInput.colors.border.focused 
+      : theme.__hd__.textInput.colors.border.default};
+    border-width: ${theme.__hd__.textInput.borderWidth};
+    border-radius: ${theme.__hd__.textInput.borderRadius};
+  `}
+`;
+```
+
+## Theme Token Usage
+
+### Adding Theme Tokens
+1. **Define in theme**: Add new tokens to work-specific theme files
+2. **Use consistently**: Apply tokens across work components
+3. **Document usage**: Add JSDoc comments for token purposes
+
+### Theme Token Examples
+```tsx
+// Using work-specific theme tokens
+background-color: ${theme.__hd__.textInput.colors.containerBackground};
+border-color: ${theme.__hd__.textInput.colors.border.focused};
+border-width: ${theme.__hd__.textInput.borderWidth};
+border-radius: ${theme.__hd__.textInput.borderRadius};
+
+// Using global theme tokens when needed
+margin: ${theme.spacing.md};  // Global spacing
+font-family: ${theme.typography.fontFamily}; // Global typography
+```
+
+### Modifying Theme Tokens
+- **Work-specific changes**: Update work theme files
+- **Component-specific**: Use component theme overrides
+- **Testing**: Verify changes across all work components
+
+## Component Development Rules
+
+### Basic Rules
+- **Prefer functional components with hooks over class components**
+- Import `styled` from `@hero-design/rn` for consistency with base theme
+- Use `useTheme()` hook instead of prop drilling theme
+- Extend base components from `@hero-design/rn` when possible
+- Follow work-specific design patterns and accessibility requirements
+- Use TypeScript strictly - no `any` types without good reason
+- Fix linting errors immediately
+- Use proper React Native components (`Text`, `View`) instead of HTML elements
+
+### Props Interface Guidelines
+```tsx
+// Good example from TextInput component
+export interface TextInputProps {
+  /** Label for the input field */
+  label?: string;
+  /** Error message to display */
+  error?: string;
+  /** Help text to display below input */
+  helpText?: string;
+  /** Whether the field is required */
+  required?: boolean;
+  /** Whether the field is disabled */
+  disabled?: boolean;
+  /** Input value */
+  value?: string;
+  /** Input variant */
+  variant?: 'text' | 'textarea';
+  /** Additional style */
+  style?: StyleProp<ViewStyle>;
+  /** Testing id */
+  testID?: string;
+}
+```
+
+## Documentation Rules
+- Document Props interfaces with JSDoc comments directly on each property: `/** Description */`
+- Use simplified @param comments: `@param props - The component props (see [ComponentName]Props interface for details)`
+- Avoid mentioning implementation details like "memoized component" in JSDoc comments
+- Focus JSDoc comments on what the component does, not how it's implemented
+- Keep type information in the Props interface, not duplicated in @param comments
+
+## Work-Specific Patterns
+- Components should work with work theme overrides
+- Test with work-specific color palettes and spacing
+- Ensure compatibility with work app requirements
+- Follow work accessibility guidelines
+- Test performance with work-typical data sizes
+
+## Quality Gates
+- All tests must pass with 100% coverage on main components
+- No linting errors
+- No TypeScript errors
+- Components must work with both base and work themes
+- Accessibility compliance for work environment

package/.cursor/rules/testing-rules.mdc

@@ -0,0 +1,114 @@
+---
+pattern: "**/*.spec.{ts,tsx}"
+description: "Comprehensive testing guidelines for React Native components in rn-work-uikit package"
+---
+
+# Testing Guidelines for RN Work UIKit
+
+## Testing Philosophy
+- Write user-behavior focused tests that describe what users see and experience
+- Use descriptive test names like "when user sees an empty input field" instead of "idle state"
+- Group related assertions with explanatory comments about user expectations
+- Focus on user interactions and outcomes rather than implementation details
+- Test the component's public API, not internal implementation
+- Write tests that will catch regressions and ensure reliability
+
+## Testing Tools and Setup
+- Use `@testing-library/react-native` for all component testing
+- Use `renderWithTheme()` from `../../../../testUtils/renderWithTheme` for components that need theme context
+- Use semantic matchers like `toBeDisabled()`, `toHaveProp()` when available
+- For complex React Native styles, use manual checking when `toHaveStyle()` doesn't work
+- Handle React Native's nested style arrays with `StyleSheet.flatten()` or custom helpers
+- Use `jest` for test runner and assertion library
+- Use `@testing-library/jest-native` for additional React Native matchers
+
+## Test Structure and Organization
+- Follow AAA pattern: Arrange, Act, Assert
+- Use `describe` blocks to group related tests
+- Use descriptive `it` statements that explain the expected behavior
+- Keep tests focused and test one thing at a time
+- Use `beforeEach` and `afterEach` for setup and cleanup
+- Mock external dependencies and APIs
+- Use `test.each` for parameterized tests when testing multiple scenarios
+
+## Test Coverage Requirements
+- Aim for 100% line coverage on main component files
+- Create dedicated test files for each component (not just integration tests)
+- Separate large test files by component responsibility
+- Use consistent naming: `ComponentName.spec.tsx`
+- Keep test utilities in `testUtils/` directory at package root
+- Use snapshot testing for visual regression prevention
+- Create README.md files in test directories explaining testing approach
+
+## Component Testing Patterns
+- Test component rendering with different props
+- Test user interactions (press, type, scroll)
+- Test component state changes
+- Test prop changes and their effects
+- Test conditional rendering based on props/state
+- Test component lifecycle methods
+- Test ref forwarding and imperative APIs
+
+## Accessibility Testing
+- Test screen reader support with `getByRole`, `getByLabelText`
+- Test keyboard navigation and focus management
+- Test accessibility props like `accessibilityLabel`, `accessibilityHint`
+- Test accessibility states like `accessibilityState`
+- Test with accessibility tools and screen readers
+- Ensure proper semantic markup and ARIA attributes
+
+## Error Handling and Edge Cases
+- Test error states and error boundaries
+- Test with invalid or missing props
+- Test with extreme values (empty strings, null, undefined)
+- Test component behavior with network failures
+- Test graceful degradation when features are unavailable
+- Test component recovery from error states
+
+## Performance Testing
+- Test component rendering performance with large datasets
+- Test memory leaks and cleanup
+- Test component re-rendering behavior
+- Test with work-typical data sizes
+- Use React DevTools Profiler for performance analysis
+- Test component performance on different device types
+
+## Work-Specific Testing
+- Test with work-specific color palettes and spacing
+- Test component behavior with work theme overrides
+- Test compatibility with work app requirements
+- Test work-specific accessibility guidelines
+- Test performance with work-typical data sizes
+- Test integration with work-specific APIs and services
+
+## Mocking and Test Utilities
+- Mock React Native modules that aren't available in test environment
+- Create custom render functions for common test scenarios
+- Use `jest.mock()` for external dependencies
+- Create test data factories for consistent test data
+- Use `@testing-library/user-event` for user interaction simulation
+- Mock navigation and routing for component tests
+
+## Test Data Management
+- Use consistent test data across tests
+- Create reusable test data factories
+- Use realistic data that matches production scenarios
+- Test with both valid and invalid data
+- Use work-specific data patterns and structures
+- Keep test data minimal but representative
+
+## Integration Testing
+- Test component integration with other components
+- Test component behavior within larger feature flows
+- Test component interaction with global state
+- Test component behavior with routing and navigation
+- Test component behavior with work-specific services
+- Use integration tests sparingly, prefer unit tests
+
+## Continuous Integration
+- Ensure all tests pass in CI environment
+- Use consistent test commands across environments
+- Set up test coverage reporting
+- Use parallel test execution for faster CI runs
+- Ensure tests are deterministic and don't flake
+- Use proper test isolation to avoid test interference

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @hero-design/rn-work-uikit
 
+## 1.9.2
+
+### Patch Changes
+
+- [#4310](https://github.com/Thinkei/hero-design/pull/4310) [`4742897580f05ae3d5f089df7aa0b1a34a90e15c`](https://github.com/Thinkei/hero-design/commit/4742897580f05ae3d5f089df7aa0b1a34a90e15c) Thanks [@vinhphan-eh](https://github.com/vinhphan-eh)! - [TimePicker] Correct 12-hour format for iOS picker
+
+- Updated dependencies [[`4742897580f05ae3d5f089df7aa0b1a34a90e15c`](https://github.com/Thinkei/hero-design/commit/4742897580f05ae3d5f089df7aa0b1a34a90e15c)]:
+  - @hero-design/rn@8.112.1
+
+## 1.9.1
+
+### Patch Changes
+
+- [#4303](https://github.com/Thinkei/hero-design/pull/4303) [`ee5b1d700200af991bb360e3f514f29790e33511`](https://github.com/Thinkei/hero-design/commit/ee5b1d700200af991bb360e3f514f29790e33511) Thanks [@ngvuthanhnhan-eh-hi](https://github.com/ngvuthanhnhan-eh-hi)! - Suppress `lint` warnings in CI Logs
+
+- Updated dependencies [[`ee5b1d700200af991bb360e3f514f29790e33511`](https://github.com/Thinkei/hero-design/commit/ee5b1d700200af991bb360e3f514f29790e33511), [`02ecf1c8ab33f3d95dcc2d168d70f11d8c415883`](https://github.com/Thinkei/hero-design/commit/02ecf1c8ab33f3d95dcc2d168d70f11d8c415883)]:
+  - @hero-design/react-native-month-year-picker@8.43.2
+  - @hero-design/rn@8.112.0
+
 ## 1.9.0
 
 ### Minor Changes