@capillarytech/blaze-ui 5.20.0 → 5.22.0

package/CapInput/README.md

@@ -1,196 +0,0 @@
-# CapInput Component
-
-An extended version of Ant Design Input component with additional features for error handling and verification states.
-
-## Migration from cap-ui-library to blaze-ui
-
-### Summary of Changes
-
-This component has been migrated from JavaScript to TypeScript with the following improvements:
-
-1. **TypeScript Conversion**
-   - Converted from JavaScript to TypeScript
-   - Added comprehensive TypeScript interfaces in `CapInput.interfaces.ts`
-   - Replaced PropTypes with TypeScript types
-   - Proper ref typing with `InputRef` from Ant Design v6
-
-2. **Modern React Patterns**
-   - Converted to functional component with React hooks
-   - Uses `React.forwardRef` for proper ref forwarding
-   - Uses `useRef` and `useEffect` hooks for focus management
-   - Better type safety with TypeScript
-
-3. **Styling**
-   - Converted to SCSS modules
-   - Uses SCSS variables from `components/styled/variables.scss`
-   - Icon styles for error and success states
-   - Global styles for consistent input styling across the app
-
-4. **Ant Design v6 Migration**
-   - Updated to use `antd-v5` (Ant Design v6)
-   - Uses `@ant-design-v5/icons` for icons
-   - Proper TypeScript types from Ant Design v6
-
-### Breaking Changes
-
-**No breaking changes from cap-ui-library v8.x**
-
-All props remain backward compatible. The component maintains the same API and behavior as the cap-ui-library version.
-
-### Props
-
-| Prop Name | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `alwaysShowFocus` | `boolean` | `undefined` | Whether to automatically focus the input when mounted |
-| `errorMessage` | `React.ReactNode` | `undefined` | Error message to display. When provided, shows error icon and sets input status to 'error' |
-| `isVerified` | `boolean` | `undefined` | Whether to show verified indicator (success icon) |
-| `showSuffix` | `boolean` | `true` | Whether to show suffix icons (error/verified icons) |
-| `size` | `'large' \| 'middle' \| 'small'` | `'large'` | The size of the input |
-| `suffix` | `React.ReactNode` | `undefined` | Custom suffix element |
-| `...rest` | `InputProps` | - | All standard Ant Design Input props |
-
-### Behavioral Changes
-
-- The component uses Ant Design v6's `status` prop to indicate error state when `errorMessage` is provided
-- Error and success icons are displayed in the suffix area
-- When `showSuffix` is `false`, no suffix icons are displayed (including error/verified icons)
-- The component applies global styles to all Ant Design inputs for consistent styling
-
-### Icon States
-
-- **Error State**: When `errorMessage` is provided, a red warning icon (`WarningOutlined`) is displayed
-- **Success State**: When `isVerified` is `true`, a green check icon (`CheckCircleOutlined`) is displayed
-- **Priority**: Error state takes precedence over verified state
-
-### Usage Examples
-
-#### Basic Usage
-
-```tsx
-import { CapInput } from '@capillarytech/blaze-ui';
-
-function MyComponent() {
-  return (
-    <CapInput 
-      placeholder="Enter your name"
-      size="large"
-    />
-  );
-}
-```
-
-#### With Error Message
-
-```tsx
-import { CapInput } from '@capillarytech/blaze-ui';
-
-function MyComponent() {
-  return (
-    <CapInput 
-      placeholder="Enter email"
-      errorMessage="This field is required"
-    />
-  );
-}
-```
-
-#### With Verified State
-
-```tsx
-import { CapInput } from '@capillarytech/blaze-ui';
-
-function MyComponent() {
-  return (
-    <CapInput 
-      placeholder="Enter username"
-      isVerified={true}
-    />
-  );
-}
-```
-
-#### With Custom Suffix
-
-```tsx
-import { CapInput } from '@capillarytech/blaze-ui';
-import { UserOutlined } from '@ant-design-v5/icons';
-
-function MyComponent() {
-  return (
-    <CapInput 
-      placeholder="Enter username"
-      suffix={<UserOutlined />}
-    />
-  );
-}
-```
-
-#### Auto Focus
-
-```tsx
-import { CapInput } from '@capillarytech/blaze-ui';
-
-function MyComponent() {
-  return (
-    <CapInput 
-      placeholder="Auto-focused input"
-      alwaysShowFocus={true}
-    />
-  );
-}
-```
-
-#### Hide Suffix Icons
-
-```tsx
-import { CapInput } from '@capillarytech/blaze-ui';
-
-function MyComponent() {
-  return (
-    <CapInput 
-      placeholder="No suffix icons"
-      showSuffix={false}
-      errorMessage="Error message"
-    />
-  );
-}
-```
-
-### Deprecated
-
-- **`CapSearchBar`** — Deprecated. Use `CapInput.Search` or `CapInputSearch` from the main export instead. The alias `CapSearchBar` is still exported from `@capillarytech/blaze-ui` for backward compatibility but will be removed in a future version.
-
-### Related Components
-
-- `CapInputSearch` - Search input variant
-- `CapInputTextArea` - Textarea input variant
-- `CapInputNumber` - Number input variant
-
-### Import Examples
-
-```tsx
-// Default import
-import CapInput from '@capillarytech/blaze-ui/components/CapInput';
-
-// Named import
-import { CapInput } from '@capillarytech/blaze-ui';
-
-// With type
-import { CapInput } from '@capillarytech/blaze-ui';
-import type { CapInputProps } from '@capillarytech/blaze-ui';
-
-// Related components
-import { 
-  CapInput, 
-  CapInputSearch, 
-  CapInputTextArea, 
-  CapInputNumber 
-} from '@capillarytech/blaze-ui';
-```
-
-### Notes
-
-- The component applies global styles to all Ant Design inputs for consistent styling
-- Error and verified states are mutually exclusive - error state takes precedence
-- The component uses Ant Design v6's built-in error status styling
-- All standard Ant Design Input props are supported through spread props

package/CapInput/Status.md

@@ -1,123 +0,0 @@
-# Migration Status: CapInput
-
-**Last Updated**: 2026-01-16 08:56:19
-
-## Migration Steps
-
-- [x] **Step 0**: Setup branch and remote tracking
-- [x] **Step 1**: Migration Prompt 1 (Main migration)
-- [x] **Step 2**: Migration Prompt 2 (Storybook support)
-- [x] **Step 3**: Migration Prompt 3 (Unit tests)
-- [x] **Step 4**: Linting (ESLint)
-- [x] **Step 5**: Pre-build Validation
-- [x] **Step 6**: Build blaze-ui
-- [x] **Step 7**: Visual Testing
-- [x] **Step 8**: CSS Analysis (if mismatches found)
-- [x] **Step 8.5**: CSS Fixes Applied (if mismatches found)
-- [x] **Step 9**: Git Commit & Push to branch
-- [x] **Step 10**: Create Pull Request
-
-## Visual Testing Results
-
-**Last Test**: 2026-01-16 08:56:01
-**Maximum Mismatch**: 2.16%
-
-### Mismatched Variants:
-- ✅ All variants match perfectly!
-
-
-## CSS Fix Analysis
-
-**Last Analysis**: 2026-01-16 08:56:01
-**Analysis File**: `/Users/sarahkhader/repos/migration/blaze-ui/tools/visual-testing/report/CapInput/css-fix-analysis.md`
-
-```
-
-## Summary
-
-- 12/12 variants failing (1.53%–2.16% mismatch)
-- Root cause: width differences (100% of mismatches)
-- Primary issue: padding values don't match target widths
-
-## Findings
-
-1. Base inputs: 27px width difference (197px target vs 170px current)
-   - Need 13.5px padding per side, but may need to account for 1px borders
-   - Current: `0.964rem` (13.5px) → Try: `0.893rem` (12.5px) if borders are included
-
-2. Affix wrapper:
-   - Prefix: 24px difference → needs 12px per side (`0.857rem`) — already set
-   - Suffix: 5px difference → needs 2.5px end padding (`0.179rem`) — missing
-
-3. Small size: 31px difference → needs 15.5px per side (`1.107rem`) — already set
-
-4. Addon variants: ~30px difference → need ~15px per side (`1.071rem`) — missing
-
-## Specific CSS fixes
-
-### Fix 1: Adjust base input padding (accounts for borders)
-
-```scss
-.ant-input,
-.ant-input-number,
-.ant-input-textarea {
-  // Change from 0.964rem to 0.893rem to account for 1px borders
-  padding-inline-start: 0.893rem; // 12.5px (was 13.5px)
-  padding-inline-end: 0.893rem;   // 12.5px (was 13.5px)
-}
-```
-
-### Fix 2: Add suffix-only padding rule
-
-```scss
-.ant-input-affix-wrapper {
-  padding-inline-start: 0.857rem; // 12px (for prefix)
-  padding-inline-end: 0.857rem;   // 12px base
-  
-  // Add this for suffix-only case
-  &:not(:has(.ant-input-prefix)):has(.ant-input-suffix) {
-    padding-inline-end: 0.179rem; // 2.5px
-  }
-}
-```
-
-### Fix 3: Add addon variant styles
-
-```scss
-.ant-input-group-wrapper,
-.ant-input-group {
-  .ant-input,
-  .ant-input-affix-wrapper {
-    padding-inline-start: 1.071rem; // ~15px
-    padding-inline-end: 1.071rem;   // ~15px
-  }
-}
-```
-
-## Priority
-
-- High (>2%): readonly (2.16%), with-addon-before (2.10%), with-value (2.06%)
-- Medium (1.8–2%): password, with-prefix, with-addon-after, large, with-suffix
-- Low (<1.8%): small, default, textarea, disabled
-
-## Expected outcome
-
-After fixes:
-- Width differences: 27px → <2px
-- Visual mismatch: 1.5–2.2% → <0.5%
-- All variants should pass (<1% threshold)
-
-Detailed analysis and complete CSS code are in:
-- `/tools/visual-testing/report/CapInput/SPECIFIC_CSS_FIXES.md`
-- `/tools/visual-testing/report/CapInput/CSS_FIXES_ANALYSIS.md`
-
-Should I apply these CSS fixes to `styles.scss`?
-```
-
-_See full analysis in: `/Users/sarahkhader/repos/migration/blaze-ui/tools/visual-testing/report/CapInput/css-fix-analysis.md`_
-
-
-## Notes
-
-_No notes yet._
-

package/CapInput/tests/USE_CASES_ANALYSIS.md

@@ -1,169 +0,0 @@
-# CapInput Use Cases Analysis
-
-## Component Overview
-CapInput is a wrapper around Ant Design v5 Input component that adds:
-- Custom error/verified state indicators
-- Auto-focus capability
-- Customizable suffix display
-- Default size of 'large'
-
-## Use Cases NOT Currently Fulfilled
-
-### 1. Error Message Display
-**Issue**: The `errorMessage` prop only displays a warning icon and sets the error status, but the actual error message text is never rendered to the user.
-
-**Current Behavior**:
-- Shows `WarningOutlined` icon when `errorMessage` is provided
-- Sets `status="error"` on the Input component
-- The error message text itself is not displayed
-
-**Expected Behavior** (if required):
-- Display the error message text below or near the input
-- Or show it in a tooltip on hover/focus
-
-**Recommendation**: If error message text display is required, consider:
-- Adding a helper text area below the input
-- Using Ant Design's Form.Item with `help` prop
-- Adding a tooltip to the error icon
-
-### 2. Warning Status Support
-**Issue**: Component only supports error status, not warning status.
-
-**Current Behavior**:
-- Only `errorMessage` prop exists (maps to error status)
-- No `warningMessage` prop
-
-**Expected Behavior** (if required):
-- Support for warning state with warning icon
-- Similar to error but with different styling
-
-### 3. Success Status Support
-**Issue**: Component has `isVerified` which shows a checkmark icon, but no explicit success status.
-
-**Current Behavior**:
-- `isVerified` shows `CheckCircleOutlined` icon
-- No `status="success"` is set on the Input
-
-**Expected Behavior** (if required):
-- Set `status="success"` when `isVerified` is true
-- Or add a separate `successMessage` prop
-
-### 4. Ref Handling with alwaysShowFocus
-**Issue**: When an external ref is provided, `alwaysShowFocus` uses the internal ref which may not be the same as the external ref.
-
-**Current Behavior**:
-```typescript
-ref={ref || inputRef}  // Uses external ref if provided
-// But alwaysShowFocus uses inputRef
-if (alwaysShowFocus && inputRef.current) {
-  inputRef.current.focus();
-}
-```
-
-**Expected Behavior** (if required):
-- If external ref is provided, use it for focus
-- If no external ref, use internal ref
-
-**Recommendation**: Update the focus logic to use the same ref that's passed to Input:
-```typescript
-useEffect(() => {
-  if (alwaysShowFocus) {
-    const refToUse = ref || inputRef;
-    if (refToUse && 'current' in refToUse && refToUse.current) {
-      refToUse.current.focus();
-    }
-  }
-}, [alwaysShowFocus, ref]);
-```
-
-### 5. Input Validation Helpers
-**Issue**: No built-in validation or formatting helpers.
-
-**Current Behavior**:
-- Component is a presentational wrapper
-- No validation logic
-
-**Expected Behavior** (if required):
-- Email validation
-- Phone number formatting
-- Credit card formatting
-- Custom validation rules
-
-**Recommendation**: Keep validation logic separate (in Form.Item or custom hooks) to maintain component simplicity.
-
-### 6. Input Groups (Deprecated)
-**Issue**: Ant Design v5 deprecated `addonBefore` and `addonAfter` props in favor of `Space.Compact`.
-
-**Current Behavior**:
-- These props are passed through but deprecated
-
-**Expected Behavior** (if required):
-- Document that these are deprecated
-- Provide examples using `Space.Compact` instead
-
-### 7. Accessibility - Error Message Announcement
-**Issue**: Error messages are not announced to screen readers.
-
-**Current Behavior**:
-- Error icon is present but no aria-describedby linking to error message
-- Error message text is not in the DOM
-
-**Expected Behavior** (if required):
-- Add `aria-describedby` pointing to error message
-- Ensure error message is accessible to screen readers
-
-### 8. Loading State
-**Issue**: No loading/spinner state support.
-
-**Current Behavior**:
-- No loading prop
-
-**Expected Behavior** (if required):
-- Show spinner icon when loading
-- Disable input during loading
-
-### 9. Character Count
-**Issue**: No built-in character count display.
-
-**Current Behavior**:
-- No character count feature
-
-**Expected Behavior** (if required):
-- Show "X / Y characters" when maxLength is set
-- Or add a `showCount` prop similar to TextArea
-
-### 10. Password Visibility Toggle
-**Issue**: Component doesn't have built-in password visibility toggle (though Ant Design Input.Password exists).
-
-**Current Behavior**:
-- Can use `type="password"` but no visibility toggle
-
-**Expected Behavior** (if required):
-- Use `Input.Password` from Ant Design or create `CapInputPassword` variant
-
-## Test Coverage Summary
-
-The comprehensive test suite covers:
-✅ Default rendering
-✅ All size variants (small, middle, large)
-✅ All variant types (outlined, borderless, filled, underlined)
-✅ Disabled and readOnly states
-✅ Value and placeholder handling
-✅ Prefix support
-✅ Suffix priority logic (error > verified > custom > null)
-✅ Error message handling (icon and status)
-✅ User interactions (typing, clicking, focusing, blurring)
-✅ All callbacks (onChange, onFocus, onBlur, onPressEnter, onClick)
-✅ Ref forwarding
-✅ Focus behavior with alwaysShowFocus
-✅ Edge cases (empty values, long text, combinations)
-✅ Accessibility (keyboard navigation, ARIA)
-✅ Ant Design InputProps passthrough
-✅ Snapshot tests for all major variations
-
-## Recommendations
-
-1. **High Priority**: Fix ref handling for `alwaysShowFocus` when external ref is provided
-2. **Medium Priority**: Consider displaying error message text if that's a requirement
-3. **Low Priority**: Add warning status support if needed
-4. **Low Priority**: Improve accessibility with aria-describedby for error messages

package/CapLanguageProvider/CapLanguageProvider-use-cases.md

@@ -1,56 +0,0 @@
-# Test Cases: CapLanguageProvider (Antd v3→v6)
-
-## Role
-Senior frontend engineer documenting ESSENTIAL test cases for Storybook stories and migration validation.
-
-## Input
-- **Component**: CapLanguageProvider
-- **Complexity**: medium (≤20 test cases)
-- **Source**: blaze-ui/components/CapLanguageProvider/
-
-## Use Cases
-
-| ID | Use Case | Props/Config | Expected Visual/Behavior | Priority | Storybook Story | Notes |
-|----|----------|--------------|-------------------------|----------|-----------------|-------|
-| UC-001 | Basic rendering with children | children: ReactNode, actions: {getSupportedLocales, getLocizeMessage}, language: {locale: 'en'}, messages: {} | Component renders child content wrapped in ConfigProvider and IntlProvider. Calls getSupportedLocales on mount. | P0 | BasicRendering | Essential baseline test |
-| UC-002 | All locale source variants | user.iso_lang: 'en_US' \| 'en-US' \| 'fr-FR', localStorage.locale: 'en_US' \| 'fr-FR', supportedLocales: [{locale, locize_locale}] | Locale loaded from user.iso_lang (priority 1), falls back to localStorage.locale (priority 2), defaults to 'en-US'. Correctly converts hyphen/underscore formats. | P0 | LocaleSources | Grouped all locale source scenarios |
-| UC-003 | Locale format conversion | lang: 'en-US' \| 'en_US' \| 'fr-FR' \| 'fr_FR' | Converts to antd format (en_US), react-intl format (en), and locize format (en-US). Handles both hyphen and underscore separators. | P0 | LocaleConversion | Grouped all format conversion scenarios |
-| UC-004 | Spinner visibility states | spinnerVisible: true \| false, language.localeLoading: 'REQUEST' \| 'IDLE' \| 'COMPLETE', supportedLocalesDetails.fetchSupportedLocalesStatus: 'REQUEST' \| 'IDLE' \| 'COMPLETE', isLoginPage: true \| false | Spinner shows when spinnerVisible=true AND not on login page AND (localeLoading='REQUEST' OR fetchSupportedLocalesStatus='REQUEST'). Hidden otherwise. | P1 | SpinnerStates | Grouped all spinner visibility conditions |
-| UC-005 | Login page skip behavior | window.location.pathname includes '/login' | getSupportedLocales and getLocizeMessage called with isSkip=true. Spinner never shows on login page regardless of loading state. | P1 | LoginPageSkip | Critical for login UX |
-| UC-006 | Messages prop variants | messages: {} \| {key: 'value'} \| undefined, language.messages: {} \| {key: 'value'} \| undefined | Uses language.messages if available, falls back to messages prop. Passes to IntlProvider. Empty object handled gracefully. | P1 | MessagesVariants | Grouped messages prop scenarios |
-| UC-007 | Supported locales loading | supportedLocalesDetails: {} \| {supportedLocales: [], fetchSupportedLocalesStatus: 'REQUEST'/'IDLE'/'COMPLETE'} | Waits for supportedLocales before calling getLocizeMessage. Handles empty/missing supportedLocales array. | P1 | SupportedLocalesLoading | Critical for locale initialization |
-| UC-008 | Locale update on user/supportedLocales change | user: {} → {iso_lang: 'en_US'}, supportedLocalesDetails: {} → {supportedLocales: [...]} | Calls updateLocale() when both user and supportedLocales become available. Updates antd locale, react-intl locale, moment locale, and dayjs locale. | P0 | LocaleUpdate | Core functionality |
-| UC-009 | Antd locale dynamic import | antdLocale: 'en_US' \| 'fr_FR' \| 'invalid_locale' | Dynamically imports antd-v5/locale/{antdLocale}. On error, falls back to en_US. Updates state.locale with imported module. | P1 | AntdLocaleImport | Critical for antd localization |
-| UC-010 | Moment and dayjs locale sync | locale: 'en-US' \| 'fr-FR' \| 'de-DE' | Calls moment.locale(locale) and dayjs.locale(locale) when locale updates. Keeps both libraries in sync. | P1 | MomentDayjsSync | Ensures date library consistency |
-| UC-011 | Locize locale mapping | supportedLocales: [{locale: 'en_US', locize_locale: 'en-US'}, {locale: 'fr-FR', locize_locale: 'fr-FR'}] | Maps user locale to locize_locale from supportedLocales. Calls getLocizeMessage with correct locize locale. | P1 | LocizeMapping | Critical for translation loading |
-| UC-012 | Styling props | className: string \| undefined | Applies className to CapSpin wrapper. Does not break layout when undefined. | P2 | StylingProps | Simple styling test |
-| UC-013 | API configuration props | supportedLocalesApi: string \| undefined, locizeApi: string \| undefined | Passes supportedLocalesApi to getSupportedLocales, locizeApi to getLocizeMessage. Handles undefined gracefully. | P2 | ApiConfigProps | Grouped API config props |
-| UC-014 | Empty/missing user data | user: {} \| undefined, localStorage.user: '' \| invalid JSON | Handles empty user object, missing iso_lang, invalid localStorage JSON. Falls back to localStorage.locale or default. | P1 | EmptyUserData | Edge case handling |
-| UC-015 | Empty/missing supported locales | supportedLocalesDetails: {} \| {supportedLocales: []} \| {supportedLocales: undefined} | Handles empty/missing supportedLocales array. Does not call getLocizeMessage until supportedLocales available. | P1 | EmptySupportedLocales | Edge case handling |
-| UC-016 | React.Children.only constraint | children: single child \| multiple children \| no children | Wraps children with React.Children.only(). Should handle single child correctly. Multiple children may cause error (expected behavior). | P2 | ChildrenOnly | React API constraint |
-| UC-017 | IntlProvider configuration | locale: 'en' \| 'fr' \| 'de', messages: {}, key: locale | IntlProvider receives correct locale, messages, and key prop based on language.locale. Defaults to 'en' if locale missing. | P1 | IntlProviderConfig | Critical for i18n |
-| UC-018 | ConfigProvider locale | state.locale: Locale object | ConfigProvider receives state.locale (antd Locale object). Updates when antd locale module loads. Defaults to enUS initially. | P1 | ConfigProviderLocale | Critical for antd i18n |
-| UC-019 | Component lifecycle | componentDidMount, componentDidUpdate | Calls getSupportedLocales on mount. Calls updateLocale in componentDidUpdate when user and supportedLocales become available. Prevents duplicate calls. | P1 | ComponentLifecycle | Core lifecycle behavior |
-| UC-020 | Migration parity (v3→v6) | ConfigProvider from antd-v5, IntlProvider from react-intl | ConfigProvider and IntlProvider behavior matches v3 expectations. Locale loading, message passing, and error handling work identically. | P0 | MigrationParity | Critical for migration validation |
-
-## Summary
-- **Total Test Cases**: 20 (within medium complexity limit)
-- **P0 (Blocking)**: 4 cases
-- **P1 (High)**: 13 cases  
-- **P2 (Medium)**: 3 cases
-
-## Grouping Rationale
-- **UC-002**: Grouped all locale source scenarios (user.iso_lang, localStorage, defaults)
-- **UC-003**: Grouped all locale format conversion scenarios (hyphen/underscore handling)
-- **UC-004**: Grouped all spinner visibility conditions (loading states, login page check)
-- **UC-006**: Grouped messages prop scenarios (language.messages vs messages prop)
-- **UC-012**: Grouped styling props (className)
-- **UC-013**: Grouped API configuration props (supportedLocalesApi, locizeApi)
-
-## Notes
-- Component uses Redux connect (HOC pattern) - test with mocked store/actions
-- Requires localStorage mocking for locale/user data tests
-- Dynamic imports require jest.mock for antd locale modules
-- Login page detection uses window.location.pathname - mock for tests
-- Component syncs moment and dayjs locales - verify both libraries update
-- React.Children.only constraint means only single child supported