@capillarytech/blaze-ui 5.20.0 → 5.22.0

package/CapForm/README.md

@@ -1,132 +0,0 @@
-# CapForm Migration: Ant Design v3 → v6
-
-## Migration Summary
-
-CapForm has been migrated from Ant Design v3 to v6. This component is a thin wrapper around Ant Design's Form component that provides consistent styling and layout defaults.
-
-## Breaking Changes
-
-### Form.create() No Longer Exported
-
-**Breaking Change:** The original `cap-ui-library` component exported `Form.create` as part of its API. This is **no longer exported** in the migrated component.
-
-**Before (cap-ui-library):**
-```javascript
-import CapForm from '@capillarytech/cap-ui-library/CapForm';
-
-// Form.create was available
-const WrappedForm = CapForm.create()(MyComponent);
-```
-
-**After (blaze-ui):**
-```tsx
-import { Form } from 'antd-v5';
-import CapForm from '@capillarytech/blaze-ui';
-
-// Use Form.useForm() hook instead
-const [form] = Form.useForm();
-
-<CapForm form={form}>
-  {/* form content */}
-</CapForm>
-```
-
-**Migration:** Replace `Form.create()` HOC pattern with `Form.useForm()` hook pattern, which is the recommended approach in Ant Design v6.
-
-### All Other Props
-
-All other CapForm props maintain full backward compatibility. All Ant Design Form props are passed through unchanged.
-
-## Deprecated Props
-
-### Ant Design Form Component Props
-
-**Status:** ✅ **No deprecated props**
-
-The Ant Design `Form` component does not have any deprecated props in v6 that require backward compatibility mapping. Unlike other Ant Design components (Dropdown, Tooltip, Tabs, etc.), the Form component's prop API remained stable during the v3 → v6 migration.
-
-**Verified Ant Design Form Props (All Supported):**
-- `layout` - Form layout type (`'horizontal' | 'vertical' | 'inline'`)
-- `labelCol` - Label layout configuration
-- `wrapperCol` - Wrapper layout configuration
-- `colon` - Whether to show colon after label
-- `preserve` - Whether to preserve field values
-- `scrollToFirstError` - Whether to scroll to first error on submit
-- `size` - Form size (`'small' | 'middle' | 'large'`)
-- `requiredMark` - Required mark style
-- `form` - Form instance (from `Form.useForm()`)
-- All other `FormProps` from Ant Design v6
-
-**Note:** The Form component API changed from using `Form.create()` HOC to `Form.useForm()` hook, but this is an API pattern change, not a prop deprecation.
-
-## API Changes
-
-CapForm maintains full compatibility with Ant Design v6 Form API:
-- Uses `Form.useForm()` hook pattern (recommended in v6)
-- Passes through all `FormProps` from Ant Design v6
-- Maintains the same prop interface (except `Form.create` export)
-
-## Styling Migration
-
-### Before (v3/v5)
-- Used `:global` SCSS blocks to override Ant Design form styles
-- Multiple `.ant-form-*` class overrides for spacing and layout
-
-### After (v6)
-- All form styling migrated to theme tokens in `getCapThemeConfig.ts`
-- Removed all `:global` blocks and `.ant-*` selectors from `styles.scss`
-- Form spacing controlled via Ant Design design tokens:
-  - `components.Form.itemMarginBottom` - Form item spacing (24px)
-  - `components.Form.labelColonMarginInlineEnd` - Label padding (16px)
-
-### Custom Styles
-
-The component now only includes minimal wrapper styles. All Ant Design form styling is handled through the theme configuration system.
-
-## Usage
-
-```tsx
-import CapForm from '@capillarytech/blaze-ui';
-import { Form } from 'antd-v5';
-
-// Basic usage
-<CapForm layout="vertical">
-  <Form.Item name="username">
-    <Input />
-  </Form.Item>
-</CapForm>
-
-// With form instance (v6 recommended pattern)
-const [form] = Form.useForm();
-
-<CapForm form={form} layout="horizontal">
-  <Form.Item name="email">
-    <Input />
-  </Form.Item>
-</CapForm>
-```
-
-## Theme Configuration
-
-Form styling is controlled via `getCapThemeConfig()`. To customize form appearance:
-
-```tsx
-import { getCapThemeConfig } from '@capillarytech/blaze-ui/utils';
-
-const customTheme = getCapThemeConfig({
-  components: {
-    Form: {
-      itemMarginBottom: 32, // Custom spacing
-      labelColonMarginInlineEnd: 20, // Custom label padding
-    },
-  },
-});
-```
-
-## Migration Notes
-
-- **Breaking Change:** If you were using `CapForm.create()`, you must migrate to `Form.useForm()` hook pattern
-- **No prop changes required** - All Form props work identically to v5/v6
-- Form validation, layout, and styling work identically to v5
-- Component is fully compatible with Ant Design v6 Form API
-- All Ant Design Form props are passed through unchanged (no deprecated props to handle)

package/CapForm/Status.md

@@ -1,40 +0,0 @@
-# Migration Status: CapForm
-
-**Last Updated**: 2026-01-31 19:17:58
-
-## 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**: Migration Prompt 4 (Visual test cases)
-- [x] **Step 5**: Linting (ESLint)
-- [x] **Step 6**: Pre-build Validation
-- [] **Step 7**: Build blaze-ui
-- [] **Step 8**: Visual Testing
-- [] **Step 9**: CSS Analysis (if mismatches found)
-- [] **Step 9.5**: CSS Analysis Completed
-- [] **Step 10**: Git Commit & Push to branch (pre-commit hook will run tests)
-- [] **Step 11**: Create Pull Request
-
-## Visual Testing Results
-
-**Last Test**: 2026-01-31 19:17:58
-**Maximum Mismatch**: 0%
-
-### Mismatched Variants:
-- 
-
-
-## CSS Fixes Applied
-
-**Date**: 2026-01-31 12:41:18
-**Summary**: CSS fixes applied based on visual testing analysis.
-
-_See full analysis in: `/Users/sarahkhader/repos/migration/blaze-ui/tools/visual-testing/report/CapForm/css-fix-analysis.md`_
-
-
-## Notes
-
-_No notes yet._

package/CapForm/tests/PHASE1_UNFULFILLED_USE_CASES.md

@@ -1,113 +0,0 @@
-# Phase 1: CapForm Use Cases NOT Currently Fulfilled
-
-## Overview
-This document identifies use cases that CapForm component does **NOT** currently fulfill or support out-of-the-box.
-
-## ⚠️ Use Cases NOT Fulfilled
-
-### 1. Form Instance Access via Ref Forwarding
-**Status**: ❌ **NOT Supported**
-- **Issue**: Component doesn't expose Form instance methods via ref forwarding
-- **Current Behavior**: 
-  - Users must use `Form.useForm()` hook separately
-  - No `ref` prop that forwards to Form instance
-  - Cannot access form methods directly from parent component via ref
-- **Workaround**: Users must use `Form.useForm()` hook and pass `form` prop
-- **Impact**: Medium - Requires additional boilerplate code
-- **Recommendation**: Consider adding `React.forwardRef` to expose form instance methods
-
-### 2. Built-in Loading State Management
-**Status**: ❌ **NOT Built-in**
-- **Issue**: No built-in loading state management during form submission
-- **Current Behavior**: 
-  - Users must manage loading state manually
-  - No `loading` prop on CapForm
-  - Form doesn't automatically disable during async submission
-- **Expected Behavior** (if required):
-  - Add `loading` prop that disables form fields during submission
-  - Or provide loading state management helper
-- **Impact**: Low - Typically handled at application level
-- **Recommendation**: This is typically handled at application level, but could be a convenience feature
-
-### 3. Nested Forms Support
-**Status**: ❌ **NOT Supported/Recommended**
-- **Issue**: Ant Design doesn't officially support nested forms, and CapForm doesn't prevent or handle this
-- **Current Behavior**: 
-  - Nested forms may cause unexpected behavior
-  - Not tested or documented
-  - No validation or prevention mechanism
-- **Impact**: Low - Nested forms are anti-pattern
-- **Recommendation**: Document that nested forms are not supported and may cause issues
-
-### 4. Form.create() HOC Pattern
-**Status**: ❌ **NOT Supported** (Breaking Change from v3)
-- **Issue**: Original `cap-ui-library` component exported `Form.create` HOC, which is no longer available
-- **Current Behavior**: 
-  - `Form.create()` is not exported
-  - Must use `Form.useForm()` hook pattern instead
-- **Migration Required**: Replace `Form.create()` HOC with `Form.useForm()` hook
-- **Impact**: High - Breaking change for existing codebases
-- **Recommendation**: Document migration path clearly
-
-## ✅ Use Cases Supported (But Require Explicit Implementation)
-
-The following use cases ARE supported via Ant Design FormProps passthrough, but require users to implement them explicitly:
-
-### 5. Form List/Dynamic Fields
-**Status**: ✅ Supported (via Ant Design Form.List)
-- **Note**: Component passes through all FormProps, so Form.List works
-- **Requirement**: Users must implement Form.List manually
-- **Test Coverage**: ✅ Now tested
-
-### 6. Form Field Dependencies
-**Status**: ✅ Supported (via Ant Design Form.Item dependencies)
-- **Note**: Component passes through FormProps, so dependencies work
-- **Requirement**: Users must implement `shouldUpdate` or `dependencies` manually
-- **Test Coverage**: ✅ Now tested
-
-### 7. Custom Validation Rules
-**Status**: ✅ Supported (via Ant Design Form.Item rules)
-- **Note**: Component passes through FormProps, so custom validation rules work
-- **Requirement**: Users must implement custom validators manually
-- **Test Coverage**: ✅ Now tested
-
-### 8. Form Reset Functionality
-**Status**: ✅ Supported (via Ant Design Form instance methods)
-- **Note**: Form reset is available via form instance methods
-- **Requirement**: Users must call `form.resetFields()` manually
-- **Test Coverage**: ✅ Now tested
-
-### 9. Form Field Value Watching
-**Status**: ✅ Supported (via Ant Design Form.Item shouldUpdate or Form.useWatch)
-- **Note**: Component supports this via Ant Design APIs
-- **Requirement**: Users must implement `Form.useWatch` or `shouldUpdate` manually
-- **Test Coverage**: ✅ Now tested
-
-### 10. Form Validation Feedback Timing
-**Status**: ✅ Supported (via Ant Design validateTrigger)
-- **Note**: Component passes through FormProps, so validateTrigger works
-- **Requirement**: Users must set `validateTrigger` prop manually
-- **Test Coverage**: ✅ Now tested
-
-## Summary
-
-### Critical Gaps (Must Address)
-1. **Form.create() HOC removal** - Breaking change requiring migration
-2. **No ref forwarding** - Cannot access form instance via ref
-
-### Nice-to-Have Features
-1. **Built-in loading state** - Convenience feature, typically handled at app level
-2. **Nested forms prevention** - Documentation/warning needed
-
-### Well-Supported (Via Passthrough)
-- All Ant Design Form features work via FormProps passthrough
-- Form instance methods available via `Form.useForm()` hook
-- Dynamic fields, dependencies, validation all supported
-- Test coverage now comprehensive
-
-## Recommendations
-
-1. **High Priority**: Document `Form.create()` migration path clearly
-2. **Medium Priority**: Consider adding ref forwarding for form instance access
-3. **Low Priority**: Add `loading` prop if commonly needed across codebase
-4. **Low Priority**: Add warning/documentation for nested forms anti-pattern

package/CapForm/tests/USE_CASES_ANALYSIS.md

@@ -1,119 +0,0 @@
-# CapForm Use Cases Analysis
-
-## Component Overview
-CapForm is a wrapper around Ant Design v5 Form component that adds:
-- Custom wrapper div with styling (`cap-form-wrapper`)
-- Default layout of 'vertical'
-- Custom className support
-- Passes through all Ant Design FormProps
-
-## Phase 1: Use Cases NOT Currently Fulfilled
-
-### 1. Form Instance Access
-**Status**: ⚠️ Not Explicitly Documented/Tested
-**Issue**: Component doesn't expose Form instance methods (getFieldsValue, setFieldsValue, validateFields, etc.) in a convenient way
-**Current Behavior**: 
-- Form instance is available via `Form.useForm()` hook, but CapForm doesn't provide a ref or instance prop
-- Users must use Ant Design's Form.useForm() hook separately
-
-**Expected Behavior** (if required):
-- Provide form instance via ref forwarding
-- Or expose form methods through a prop
-
-**Recommendation**: Document that users should use `Form.useForm()` hook and pass `form` prop to CapForm, or add ref forwarding if needed.
-
-### 2. Form List/Dynamic Fields
-**Status**: ✅ Supported (via Ant Design Form.List)
-**Note**: Component passes through all FormProps, so Form.List should work, but it's not explicitly tested or documented in CapForm context.
-
-**Recommendation**: Add test cases and examples for Form.List usage.
-
-### 3. Form Dependencies (shouldUpdate, dependencies)
-**Status**: ✅ Supported (via Ant Design Form.Item dependencies)
-**Note**: Component passes through FormProps, so dependencies work, but not explicitly tested.
-
-**Recommendation**: Add test cases for form field dependencies.
-
-### 4. Custom Validation Rules
-**Status**: ✅ Supported (via Ant Design Form.Item rules)
-**Note**: Component passes through FormProps, so custom validation rules work via Form.Item, but not explicitly tested at CapForm level.
-
-**Recommendation**: Add test cases demonstrating custom validation.
-
-### 5. Form Reset Functionality
-**Status**: ✅ Supported (via Ant Design Form instance methods)
-**Note**: Form reset is available via form instance methods, but not explicitly tested.
-
-**Recommendation**: Add test cases for form reset scenarios.
-
-### 6. Form Field Value Watching
-**Status**: ✅ Supported (via Ant Design Form.Item shouldUpdate or Form.useWatch)
-**Note**: Component supports this via Ant Design APIs, but not explicitly tested.
-
-**Recommendation**: Add test cases for value watching scenarios.
-
-### 7. Form Submission Loading State
-**Status**: ⚠️ Not Built-in
-**Issue**: No built-in loading state management during form submission
-**Current Behavior**: 
-- Users must manage loading state manually
-- No `loading` prop on CapForm
-
-**Expected Behavior** (if required):
-- Add `loading` prop that disables form during submission
-- Or provide loading state management helper
-
-**Recommendation**: This is typically handled at application level, but could be a convenience feature.
-
-### 8. Form Validation Feedback Timing
-**Status**: ✅ Supported (via Ant Design validateTrigger)
-**Note**: Component passes through FormProps, so validateTrigger works, but not explicitly tested.
-
-**Recommendation**: Add test cases for different validation trigger scenarios (onChange, onBlur, onSubmit).
-
-### 9. Nested Forms
-**Status**: ⚠️ Not Recommended/Tested
-**Issue**: Ant Design doesn't officially support nested forms, and CapForm doesn't prevent or handle this
-**Current Behavior**: 
-- Nested forms may cause unexpected behavior
-- Not tested or documented
-
-**Recommendation**: Document that nested forms are not supported and may cause issues.
-
-### 10. Form Field Array Operations
-**Status**: ✅ Supported (via Ant Design Form.List)
-**Note**: Component supports Form.List for dynamic fields, but array operations (add, remove, move) are not explicitly tested.
-
-**Recommendation**: Add test cases for Form.List add/remove/move operations.
-
-## Test Coverage Summary
-
-The comprehensive test suite covers:
-✅ Default rendering and initialization
-✅ Layout variations (horizontal, vertical, inline)
-✅ Custom className application
-✅ Form callbacks (onFinish, onFinishFailed)
-✅ Initial values handling
-✅ Form props passthrough (size, requiredMark, colon, preserve, labelCol, wrapperCol, scrollToFirstError)
-✅ User interactions (form submission, input changes)
-✅ Edge cases (empty form, null/undefined children, multiple classNames)
-✅ Accessibility (form role, ARIA attributes, keyboard navigation)
-✅ Data flow and state management (re-renders, initialValues changes)
-✅ Conditional rendering
-
-## Recommendations
-
-1. **High Priority**: Add test cases for Form.List (dynamic fields)
-2. **High Priority**: Add test cases for form instance methods (getFieldsValue, setFieldsValue, validateFields, resetFields)
-3. **Medium Priority**: Add test cases for form field dependencies
-4. **Medium Priority**: Add test cases for custom validation rules
-5. **Low Priority**: Consider adding loading state prop if commonly needed
-6. **Low Priority**: Document form instance usage patterns
-7. **Low Priority**: Add test cases for validateTrigger variations
-
-## Notes
-
-- CapForm is a thin wrapper around Ant Design Form
-- Most functionality comes from Ant Design FormProps passthrough
-- Component focuses on styling and default layout configuration
-- All Ant Design Form features are available but may need explicit testing/documentation