@capillarytech/blaze-ui 5.21.0 → 5.22.0

package/CapModal/README.md

@@ -1,357 +0,0 @@
-# CapModal Migration Guide
-
-## Summary
-
-CapModal has been migrated from `cap-ui-library` to `blaze-ui` with the following changes:
-
-- Converted from JavaScript to TypeScript
-- Uses SCSS modules for styling (imported as `import * as styles from './styles.scss'`)
-- Migrated to Ant Design v6 APIs
-- Added backward compatibility for deprecated props
-- Added TypeScript interfaces for props
-- Maintained backward compatibility with the existing API
-
-## Breaking Changes
-
-**No breaking changes from cap-ui-library v8.x**
-
-The component maintains backward compatibility with deprecated props. However, deprecated props will show console warnings in development mode and should be migrated to the new API.
-
-## Prop Changes
-
-### New Props (v6 API)
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `open` | `boolean` | `undefined` | Whether the modal is open (Ant Design v6 API) |
-| `onOpenChange` | `(open: boolean) => void` | `undefined` | Callback when modal open state changes (Ant Design v6 API) |
-
-### Deprecated Props
-
-The following Ant Design Modal component props are deprecated but still supported for backward compatibility:
-
-#### `visible` (deprecated)
-
-- **Status:** Deprecated
-- **Ant Design Component:** Modal
-- **Replacement:** Use `open` prop instead
-- **Migration:** Replace `visible={...}` with `open={...}`
-- **Removal:** Will be removed in v10.0.0
-
-**Example:**
-
-```tsx
-// ❌ Deprecated (Ant Design v3/v4/v5 API)
-<CapModal visible={isOpen} onVisibleChange={setIsOpen}>
-  <p>Modal content</p>
-</CapModal>
-
-// ✅ Recommended (Ant Design v6 API)
-<CapModal open={isOpen} onOpenChange={setIsOpen}>
-  <p>Modal content</p>
-</CapModal>
-```
-
-**Note:** If both `open` and `visible` are provided, `open` takes precedence. A console warning will be shown in development mode when using the deprecated `visible` prop.
-
-#### `onVisibleChange` (deprecated)
-
-- **Status:** Deprecated
-- **Ant Design Component:** Modal
-- **Replacement:** Use `onOpenChange` prop instead
-- **Migration:** Replace `onVisibleChange={...}` with `onOpenChange={...}`
-- **Removal:** Will be removed in v10.0.0
-
-**Example:**
-
-```tsx
-// ❌ Deprecated (Ant Design v3/v4/v5 API)
-<CapModal 
-  visible={isOpen} 
-  onVisibleChange={(visible) => setIsOpen(visible)}
->
-  <p>Modal content</p>
-</CapModal>
-
-// ✅ Recommended (Ant Design v6 API)
-<CapModal 
-  open={isOpen} 
-  onOpenChange={(open) => setIsOpen(open)}
->
-  <p>Modal content</p>
-</CapModal>
-```
-
-**Note:** If both `onOpenChange` and `onVisibleChange` are provided, `onOpenChange` takes precedence. A console warning will be shown in development mode when using the deprecated `onVisibleChange` prop.
-
-### Prop Changes Summary
-
-| Prop | Type | Status | Notes |
-|------|------|--------|-------|
-| `open` | `boolean` | ✅ New | Preferred prop name for modal visibility (Ant Design v6 API) |
-| `visible` | `boolean` | ⚠️ Deprecated | Use `open` instead. Still supported for backward compatibility |
-| `onOpenChange` | `(open: boolean) => void` | ✅ New | Preferred callback for modal state changes (Ant Design v6 API) |
-| `onVisibleChange` | `(visible: boolean) => void` | ⚠️ Deprecated | Use `onOpenChange` instead. Still supported for backward compatibility |
-| `defaultOpen` | `boolean` | ✅ Unchanged | Default open state for uncontrolled mode |
-
-### Custom Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `okText` | `string` | - | Text for the OK button |
-| `closeText` | `string` | - | Text for the Cancel/Close button |
-| `cancelButtonType` | `'flat' \| 'default' \| 'primary' \| 'dashed' \| 'link' \| 'text'` | `'flat'` | Type of the cancel button |
-
-### Other Props
-
-All standard Ant Design Modal props are supported. Refer to [Ant Design Modal documentation](https://ant.design/components/modal) for complete API reference.
-
-## API Changes
-
-### Controlled vs Uncontrolled Mode
-
-The component now supports both controlled and uncontrolled modes:
-
-**Controlled Mode:**
-```tsx
-const [open, setOpen] = useState(false);
-
-<CapModal 
-  title="Controlled Modal" 
-  open={open} 
-  onOpenChange={setOpen}
->
-  <p>Modal content</p>
-</CapModal>
-```
-
-**Uncontrolled Mode:**
-```tsx
-<CapModal 
-  title="Uncontrolled Modal" 
-  defaultOpen={false}
->
-  <p>Modal content</p>
-</CapModal>
-```
-
-## Migration Examples
-
-### Basic Usage
-
-**Before (v3/v4/v5):**
-```tsx
-<CapModal 
-  visible={isOpen}
-  onVisibleChange={setIsOpen}
-  okText="Confirm"
-  closeText="Cancel"
->
-  <p>Modal content</p>
-</CapModal>
-```
-
-**After (v6):**
-```tsx
-<CapModal 
-  open={isOpen}
-  onOpenChange={setIsOpen}
-  okText="Confirm"
-  closeText="Cancel"
->
-  <p>Modal content</p>
-</CapModal>
-```
-
-### Static Methods
-
-The static methods (`info`, `success`, `error`, `warning`, `confirm`) remain unchanged:
-
-```tsx
-// Success modal
-CapModal.success({
-  title: 'Success',
-  content: 'Operation completed successfully!',
-});
-
-// Confirm modal
-CapModal.confirm({
-  title: 'Confirm',
-  content: 'Are you sure you want to proceed?',
-  onOk: () => {
-    // Handle confirmation
-  },
-});
-```
-
-## Styling Changes
-
-### Theme Tokens
-
-The following Modal tokens have been added to `getCapThemeConfig`:
-
-- `bodyPadding`: Custom padding for modal body (top: 4px, bottom: 0)
-- `footerPadding`: Custom padding for modal footer (bottom: 24px)
-- `closeIconColor`: Color for the close icon (#091e42)
-
-### SCSS Classes
-
-The component uses custom SCSS classes applied via `classNames` prop:
-
-- `.cap-modal-v2-content`: Max-width constraint (372px)
-- `.cap-modal-v2-header`: Header styling (no border bottom)
-- `.cap-modal-v2-body`: Body styling (custom padding)
-- `.cap-modal-v2-footer`: Footer styling (no border top, custom padding)
-- `.cap-modal-v2-close`: Close icon styling (custom color)
-
-**Note**: All styling uses component-specific classes without `.ant-` selectors, following Ant Design v6 best practices.
-
-## Behavioral Changes
-
-### No Breaking Changes
-
-The component maintains **100% backward compatibility** with `cap-ui-library` v8.x. All existing code will continue to work without modifications.
-
-### Enhanced Features
-
-- **Controlled State**: Full support for controlled modal state management
-- **TypeScript Support**: Complete type definitions for all props
-- **Deprecation Warnings**: Development warnings for deprecated prop usage
-- **Theme Integration**: Automatic theming via `getCapThemeConfig`
-
-## Examples
-
-### Basic Modal
-
-```tsx
-import { CapModal, CapButton } from '@capillarytech/blaze-ui';
-import { useState } from 'react';
-
-const MyComponent = () => {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <>
-      <CapButton onClick={() => setOpen(true)}>Open Modal</CapButton>
-      <CapModal
-        title="Basic Modal"
-        open={open}
-        onOpenChange={setOpen}
-        okText="OK"
-        closeText="Close"
-      >
-        <p>This is a basic modal example.</p>
-      </CapModal>
-    </>
-  );
-};
-```
-
-### Custom Footer
-
-```tsx
-<CapModal
-  title="Custom Footer"
-  open={open}
-  onOpenChange={setOpen}
-  footer={[
-    <CapButton key="custom" onClick={handleCustom}>
-      Custom Action
-    </CapButton>,
-  ]}
->
-  <p>Modal with custom footer buttons.</p>
-</CapModal>
-```
-
-### Using Deprecated Props (Still Works)
-
-```tsx
-// ⚠️ Deprecated but still functional
-<CapModal
-  visible={isOpen}
-  onVisibleChange={setIsOpen}
-  okText="Confirm"
-  closeText="Cancel"
->
-  <p>This will show deprecation warnings in development.</p>
-</CapModal>
-```
-
-## Technical Details
-
-### Import Changes
-
-**Before:**
-```tsx
-import { Modal } from 'antd';
-```
-
-**After:**
-```tsx
-import { Modal } from 'antd-v5';
-```
-
-### Type Exports
-
-```tsx
-import type { CapModalProps } from '@capillarytech/blaze-ui';
-```
-
-### LocaleHoc Integration
-
-The component uses `LocaleHoc` for internationalization support. Translation keys are under `app.commonUtils.capUiLibrary.CapModal`:
-
-- `okText`: Default OK button text
-- `closeText`: Default Close button text
-
-## Troubleshooting
-
-### Modal Not Opening
-
-**Issue**: Modal doesn't open when using `visible` prop.
-
-**Solution**: Migrate to `open` prop:
-```tsx
-// ❌ Deprecated
-<CapModal visible={true} />
-
-// ✅ Correct
-<CapModal open={true} />
-```
-
-### Styling Not Applied
-
-**Issue**: Custom styles not appearing.
-
-**Solution**: Ensure `getCapThemeConfig` is applied via `ConfigProvider`:
-```tsx
-import { ConfigProvider } from 'antd-v5';
-import { getCapThemeConfig } from '@capillarytech/blaze-ui';
-
-<ConfigProvider theme={getCapThemeConfig()}>
-  <YourApp />
-</ConfigProvider>
-```
-
-### Type Errors
-
-**Issue**: TypeScript errors with props.
-
-**Solution**: Import types from the component:
-```tsx
-import type { CapModalProps } from '@capillarytech/blaze-ui';
-```
-
-## Additional Resources
-
-- [Ant Design Modal Documentation](https://ant.design/components/modal)
-- [Ant Design v6 Migration Guide](https://ant.design/docs/react/migration-v6)
-- [Cap UI Storybook](http://localhost:6006) - See CapModal in action
-
-## Support
-
-For issues or questions:
-- Check the [README.md](../../README.md) for general usage
-- Review Ant Design v6 Modal documentation
-- Open an issue in the repository

package/CapModal/Status.md

@@ -1,52 +0,0 @@
-# Migration Status: CapModal
-
-**Last Updated**: 2026-02-06 10:35:26
-
-## Migration Steps
-
-- [x] **Step 0**: Setup branch and remote tracking
-- [x] **Step 1**: Migration Prompt 1 (Main migration)
-- [x] **Step 1.5**: Export component in blaze-ui/components/index.ts
-- [x] **Step 2**: Migration Prompt 2 (Storybook support)
-- [x] **Step 2.5**: Verify deprecated props and prop changes (REQUIRED - enforced)
-- [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
-- [x] **Step 7**: Build blaze-ui
-- [x] **Step 8**: Visual Testing
-- [x] **Step 9**: CSS Analysis (if mismatches found)
-- [x] **Step 9.5**: CSS Analysis Completed
-- [x] **Step 10**: Git Commit & Push to branch (pre-commit hook will run tests)
-- [x] **Step 11**: Create Pull Request
-
-## Deprecated Props Verification
-
-_No deprecated props verification results yet._
-
-**Note**: Step 2.5 is REQUIRED and enforced. 
-- Focus: **Ant Design component prop changes** (e.g., Dropdown, Input, Alert, Tooltip, etc.)
-- Reference: MIGRATION_CHANGELOG_TEMPLATE.md for format, ANTD_V6_MIGRATION.md for Ant Design deprecated APIs
-- Skip: If original component doesn't exist in cap-ui-library
-- All deprecated Ant Design props and prop changes must be documented before proceeding.
-
-## Visual Testing Results
-
-**Last Test**: 2026-02-06 10:35:26
-**Maximum Mismatch**: 0%
-
-### Mismatched Variants:
-- 
-
-
-## CSS Fixes Applied
-
-**Date**: 2026-02-01 11:49:36
-**Summary**: CSS fixes applied based on visual testing analysis.
-
-_See full analysis in: `/Users/sarahkhader/repos/migration/blaze-ui/tools/visual-testing/report/CapModal/css-fix-analysis.md`_
-
-
-## Notes
-
-_No notes yet._

package/CapModal/tests/USE_CASES_GAPS.md

@@ -1,207 +0,0 @@
-# CapModal Use Cases Analysis - Gaps Identified
-
-**Date**: 2026-02-01  
-**Component**: CapModal  
-**Analysis Type**: Use Cases Not Fulfilled
-
-## Overview
-
-This document identifies use cases and features that the CapModal component may not fully support based on code analysis. Since Google Sheets access was unavailable, this analysis is based on component implementation review.
-
----
-
-## Use Cases NOT Fully Fulfilled
-
-### 1. **OK Button Does Not Auto-Close Modal**
-
-**Issue**: When the OK button is clicked, `onOk` callback is called but `onOpenChange(false)` is NOT automatically called. The modal remains open unless the parent component explicitly closes it.
-
-**Current Behavior**:
-```tsx
-const handleOk = React.useCallback(
-  (e: React.MouseEvent<HTMLElement>) => {
-    if (originalOnOk) {
-      originalOnOk(e as unknown as React.MouseEvent<HTMLButtonElement>);
-    }
-    // Missing: onOpenChange(false) is not called
-  },
-  [originalOnOk]
-);
-```
-
-**Expected Use Case**: Users may expect the modal to close automatically when OK is clicked, similar to how Close button works.
-
-**Impact**: Medium - Requires manual state management in parent components.
-
-**Recommendation**: Consider adding an `autoCloseOnOk` prop (default: false) or making OK button behavior consistent with Close button.
-
----
-
-### 2. **Limited okButtonProps Support**
-
-**Issue**: Only `okButtonProps.disabled` is passed to the OK button. Other Ant Design Button props (like `loading`, `danger`, `icon`, etc.) are not supported.
-
-**Current Implementation**:
-```tsx
-<CapButton
-  onClick={handleOk}
-  disabled={restProps?.okButtonProps?.disabled}
-  type="primary"
->
-  {okText}
-</CapButton>
-```
-
-**Expected Use Case**: Users may want to show loading state on OK button, add icons, or apply danger styling.
-
-**Impact**: Low-Medium - Limits customization options.
-
-**Recommendation**: Spread all `okButtonProps` to CapButton:
-```tsx
-<CapButton
-  onClick={handleOk}
-  type="primary"
-  {...restProps?.okButtonProps}
->
-  {okText}
-</CapButton>
-```
-
----
-
-### 3. **No okButtonType Prop**
-
-**Issue**: The OK button is hardcoded to `type="primary"`. There's no way to customize it, unlike `cancelButtonType` for the Close button.
-
-**Current Implementation**:
-```tsx
-<CapButton
-  onClick={handleOk}
-  disabled={restProps?.okButtonProps?.disabled}
-  type="primary"  // Hardcoded
->
-  {okText}
-</CapButton>
-```
-
-**Expected Use Case**: Users may want a secondary or flat OK button in certain contexts.
-
-**Impact**: Low - Most use cases use primary OK buttons.
-
-**Recommendation**: Add `okButtonType` prop similar to `cancelButtonType`.
-
----
-
-### 4. **Footer Cannot Be Completely Hidden**
-
-**Issue**: The component always renders a footer (either default or custom). Setting `footer={null}` removes the footer, but there's no prop to conditionally hide it while keeping modal functionality.
-
-**Current Behavior**: 
-- `footer={undefined}` → Default footer rendered
-- `footer={null}` → No footer rendered
-- `footer={<Custom />}` → Custom footer rendered
-
-**Expected Use Case**: Users may want a footer-less modal for certain scenarios (e.g., full-screen content modals).
-
-**Impact**: Low - Workaround exists (footer={null}).
-
-**Recommendation**: Document the `footer={null}` pattern or add a `showFooter` prop for clarity.
-
----
-
-### 5. **Static Methods Don't Use LocaleHoc Defaults**
-
-**Issue**: Static methods (`info`, `success`, `error`, `warning`, `confirm`) are directly attached from Ant Design Modal and don't use the default `okText`/`closeText` from LocaleHoc.
-
-**Current Implementation**:
-```tsx
-CapModalWithHoc.info = info;  // Direct assignment from Ant Design
-```
-
-**Expected Use Case**: Users may expect static methods to respect i18n defaults.
-
-**Impact**: Low - Static methods typically provide their own text.
-
-**Recommendation**: Consider wrapping static methods to inject default translations, or document that static methods require explicit text.
-
----
-
-### 6. **onOpenChange Not Called on OK Click**
-
-**Issue**: When OK button is clicked, `onOpenChange` is never called, even if provided. Only `onOk` is called.
-
-**Current Behavior**:
-- Close button → Calls both `onCancel` and `onOpenChange(false)`
-- OK button → Calls only `onOk`, does NOT call `onOpenChange`
-
-**Expected Use Case**: Users may want consistent state management where both buttons trigger `onOpenChange`.
-
-**Impact**: Medium - Inconsistent behavior between OK and Close buttons.
-
-**Recommendation**: Consider calling `onOpenChange(false)` when OK is clicked, or add a prop to control this behavior.
-
----
-
-### 7. **No Built-in Loading State Management**
-
-**Issue**: There's no built-in way to show loading state on buttons during async operations. Users must manually manage loading state.
-
-**Expected Use Case**: Common pattern where OK button shows loading during form submission or API calls.
-
-**Impact**: Low-Medium - Can be handled via `okButtonProps`, but requires manual state management.
-
-**Recommendation**: Consider adding `loading` prop that automatically manages button loading states.
-
----
-
-### 8. **classNames 'close' Key Ignored**
-
-**Issue**: The `classNames.close` key is filtered out and not applied, even though it's accepted in the type definition.
-
-**Current Implementation**:
-```tsx
-...(Object.fromEntries(
-  Object.entries(existingClassNames).filter(([key]) => !['content', 'close'].includes(key))
-```
-
-**Expected Use Case**: Users may want to style the close icon via classNames.
-
-**Impact**: Low - Workaround exists via CSS selectors.
-
-**Recommendation**: Document that `classNames.close` is not supported, or implement support for it.
-
----
-
-## Summary
-
-### High Priority Gaps
-- None identified
-
-### Medium Priority Gaps
-1. OK button doesn't auto-close modal (inconsistent with Close button)
-2. `onOpenChange` not called on OK click
-3. Limited `okButtonProps` support
-
-### Low Priority Gaps
-1. No `okButtonType` prop
-2. Static methods don't use LocaleHoc defaults
-3. Footer visibility not explicitly documented
-4. No built-in loading state management
-5. `classNames.close` ignored
-
----
-
-## Notes
-
-- **Google Sheets Access**: Unable to access Google Sheets to compare against documented use cases. This analysis is based on code review.
-- **Component Purpose**: CapModal is a wrapper around Ant Design Modal, so some limitations may be intentional design decisions.
-- **Backward Compatibility**: Component maintains 100% backward compatibility with cap-ui-library v8.x.
-
----
-
-## Recommendations
-
-1. **Documentation**: Add clear documentation about OK vs Close button behavior differences.
-2. **Consistency**: Consider making OK and Close button behavior more consistent.
-3. **Enhancement**: Add `okButtonType` and full `okButtonProps` support for better customization.
-4. **Testing**: All identified gaps are covered in the test suite to ensure current behavior is maintained.