@capillarytech/blaze-ui 5.20.0 → 5.22.0

package/CapDropdown/README.md

@@ -1,515 +0,0 @@
-# CapDropdown Migration Guide
-
-## Summary
-
-CapDropdown has been migrated from `cap-ui-library` to `blaze-ui` with the following changes:
-
-- Converted from JavaScript to TypeScript
-- Converted from styled-components to SCSS modules
-- 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 dropdown menu is open (v6 API) |
-| `onOpenChange` | `(open: boolean) => void` | `undefined` | Callback when dropdown open state changes (v6 API) |
-| `classNames` | `DropdownProps['classNames']` | `undefined` | Custom class names for dropdown parts (v6 API) |
-
-### Deprecated Props (Still Supported)
-
-| Prop | Type | Status | Migration |
-|------|------|--------|-----------|
-| `visible` | `boolean` | ⚠️ Deprecated | Use `open` instead |
-| `onVisibleChange` | `(visible: boolean) => void` | ⚠️ Deprecated | Use `onOpenChange` instead |
-| `overlayClassName` | `string` | ⚠️ Deprecated | Use `classNames.root` instead |
-| `overlayStyle` | `React.CSSProperties` | ⚠️ Deprecated | Use `styles.root` instead |
-| `overlay` | `React.ReactNode` | ⚠️ Deprecated | Use `menu` prop for menu configurations or `dropdownRender` for custom ReactNodes |
-| `placement` (topCenter/bottomCenter) | `string` | ⚠️ Deprecated | Use `top`/`bottom` instead |
-
-### Placement Values
-
-**Deprecated placements:**
-- `topCenter` → Use `top` instead
-- `bottomCenter` → Use `bottom` instead
-
-**Valid placements:**
-- `topLeft`, `top`, `topRight`
-- `bottomLeft`, `bottom`, `bottomRight`
-
-### Other Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | `undefined` | Additional CSS class name |
-| `menu` | `DropdownProps['menu']` | `undefined` | Menu configuration object |
-| `trigger` | `Array<'click' \| 'hover' \| 'contextMenu'>` | `['hover']` | Trigger actions |
-| `placement` | `DeprecatedPlacement \| V6Placement` | `'bottomLeft'` | Dropdown placement |
-| `disabled` | `boolean` | `false` | Whether dropdown is disabled |
-| `children` | `React.ReactNode` | - | Trigger element |
-
-## CapDropdown.Button
-
-CapDropdown includes a `Button` subcomponent that replaces the deprecated `Dropdown.Button` from Ant Design v3.
-
-### CapDropdown.Button Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `React.ReactNode` | - | Button content |
-| `onClick` | `ButtonProps['onClick']` | `undefined` | Click handler for main button |
-| `type` | `ButtonProps['type']` | `'default'` | Button type |
-| `size` | `ButtonProps['size']` | `undefined` | Button size |
-| `danger` | `boolean` | `false` | Danger button style |
-| `loading` | `boolean` | `false` | Loading state |
-| `icon` | `React.ReactNode` | `'▼'` | Icon for dropdown trigger button |
-| `menu` | `DropdownProps['menu']` | `undefined` | Dropdown menu configuration |
-| `disabled` | `boolean` | `false` | Disabled state |
-| `buttonsRender` | `(buttons: [React.ReactNode, React.ReactNode]) => [React.ReactNode, React.ReactNode]` | `undefined` | Custom render function for buttons |
-| `...dropdownProps` | `CapDropdownProps` | - | All other CapDropdown props |
-
-## API Changes
-
-### Controlled Open State (v6 API)
-
-```tsx
-// New v6 API (recommended)
-const [open, setOpen] = useState(false);
-
-<CapDropdown
-  open={open}
-  onOpenChange={setOpen}
-  menu={menu}
->
-  <Button>Hover me</Button>
-</CapDropdown>
-
-// Old API (deprecated, still works)
-const [visible, setVisible] = useState(false);
-
-<CapDropdown
-  visible={visible}
-  onVisibleChange={setVisible}
-  menu={menu}
->
-  <Button>Hover me</Button>
-</CapDropdown>
-```
-
-### Overlay Class Names (v6 API)
-
-```tsx
-// New v6 API (recommended)
-<CapDropdown
-  classNames={{
-    root: 'custom-overlay-class'
-  }}
-  menu={menu}
->
-  <Button>Hover me</Button>
-</CapDropdown>
-
-// Old API (deprecated, still works)
-<CapDropdown
-  overlayClassName="custom-overlay-class"
-  menu={menu}
->
-  <Button>Hover me</Button>
-</CapDropdown>
-```
-
-### Placement Values
-
-```tsx
-// New v6 API (recommended)
-<CapDropdown placement="top" menu={menu}>
-  <Button>Hover me</Button>
-</CapDropdown>
-
-// Old API (deprecated, still works but mapped to new values)
-<CapDropdown placement="topCenter" menu={menu}>
-  <Button>Hover me</Button>
-</CapDropdown>
-```
-
-## Behavioral Changes
-
-### Development Warnings
-
-When using deprecated props in development mode, console warnings will be displayed:
-
-```
-[CapDropdown] "visible" prop is deprecated. Use "open" instead.
-[CapDropdown] "onVisibleChange" prop is deprecated. Use "onOpenChange" instead.
-```
-
-### CapDropdown.Button Implementation
-
-The `CapDropdown.Button` component uses the `Space.Compact` pattern recommended by Ant Design v6, replacing the deprecated `Dropdown.Button` component.
-
-## Migration Steps
-
-### 1. Update Import
-
-```tsx
-// Before (cap-ui-library)
-import CapDropdown from '@capillarytech/cap-ui-library/CapDropdown';
-
-// After (blaze-ui)
-import { CapDropdown } from '@capillarytech/blaze-ui';
-// or
-import CapDropdown from '@capillarytech/blaze-ui/CapDropdown';
-```
-
-### 2. Update Controlled State Props
-
-```tsx
-// Before (deprecated)
-const [visible, setVisible] = useState(false);
-
-<CapDropdown
-  visible={visible}
-  onVisibleChange={setVisible}
-  menu={menu}
->
-  <Button>Hover me</Button>
-</CapDropdown>
-
-// After (v6 API)
-const [open, setOpen] = useState(false);
-
-<CapDropdown
-  open={open}
-  onOpenChange={setOpen}
-  menu={menu}
->
-  <Button>Hover me</Button>
-</CapDropdown>
-```
-
-### 3. Update Overlay Class Names
-
-```tsx
-// Before (deprecated)
-<CapDropdown overlayClassName="custom-class" menu={menu}>
-  <Button>Hover me</Button>
-</CapDropdown>
-
-// After (v6 API)
-<CapDropdown classNames={{ root: 'custom-class' }} menu={menu}>
-  <Button>Hover me</Button>
-</CapDropdown>
-```
-
-### 4. Update Placement Values
-
-```tsx
-// Before (deprecated)
-<CapDropdown placement="topCenter" menu={menu}>
-  <Button>Hover me</Button>
-</CapDropdown>
-
-// After (v6 API)
-<CapDropdown placement="top" menu={menu}>
-  <Button>Hover me</Button>
-</CapDropdown>
-```
-
-### 5. Migrate from `overlay` Prop to `menu` Prop
-
-The `overlay` prop is deprecated but still supported for backward compatibility. It will show deprecation warnings in development mode.
-
-```tsx
-// Before (deprecated - using overlay with CapMenu)
-import { CapDropdown, CapMenu, CapIcon } from '@capillarytech/blaze-ui';
-
-<CapDropdown
-  overlay={
-    <CapMenu>
-      <CapMenu.Item onClick={handleEdit}>Edit</CapMenu.Item>
-      <CapMenu.Item onClick={handleRemove}>Remove</CapMenu.Item>
-    </CapMenu>
-  }
-  placement="bottomRight"
->
-  <CapIcon type="more" />
-</CapDropdown>
-
-// After (v6 API - recommended)
-import { CapDropdown, CapIcon } from '@capillarytech/blaze-ui';
-import type { MenuProps } from 'antd-v5';
-
-const menu: MenuProps = {
-  items: [
-    {
-      key: 'edit',
-      label: 'Edit',
-      onClick: handleEdit,
-    },
-    {
-      key: 'remove',
-      label: 'Remove',
-      onClick: handleRemove,
-    },
-  ],
-};
-
-<CapDropdown menu={menu} placement="bottomRight">
-  <CapIcon type="more" />
-</CapDropdown>
-```
-
-**Note**: The `overlay` prop is still functional and will continue to work, but it uses the deprecated `dropdownRender` API internally. For custom ReactNodes that don't fit the menu structure, consider using `dropdownRender` directly or migrating to `Popover` component for more flexibility.
-
-### 5. TypeScript Support (New Benefit)
-
-If using TypeScript, you now get full type checking:
-
-```tsx
-import { CapDropdown, CapDropdownProps, CapDropdownButtonProps } from '@capillarytech/blaze-ui';
-
-// Type-safe props
-const props: CapDropdownProps = {
-  open: true,
-  onOpenChange: (open) => console.log(open),
-  menu: { items: [{ key: '1', label: 'Item 1' }] }
-};
-
-// Type-safe button props
-const buttonProps: CapDropdownButtonProps = {
-  children: 'Actions',
-  onClick: () => console.log('clicked'),
-  menu: { items: [{ key: '1', label: 'Item 1' }] }
-};
-```
-
-## Examples
-
-### Basic Usage
-
-```tsx
-import { CapDropdown } from '@capillarytech/blaze-ui';
-import { Button } from 'antd-v5';
-
-const menu = {
-  items: [
-    { key: '1', label: 'Item 1' },
-    { key: '2', label: 'Item 2' },
-    { key: '3', label: 'Item 3' },
-  ],
-};
-
-function App() {
-  return (
-    <CapDropdown menu={menu}>
-      <Button>Hover me</Button>
-    </CapDropdown>
-  );
-}
-```
-
-### Controlled Open State
-
-```tsx
-import { CapDropdown } from '@capillarytech/blaze-ui';
-import { Button } from 'antd-v5';
-import { useState } from 'react';
-
-function App() {
-  const [open, setOpen] = useState(false);
-  const menu = {
-    items: [
-      { key: '1', label: 'Item 1' },
-      { key: '2', label: 'Item 2' },
-    ],
-  };
-
-  return (
-    <CapDropdown
-      open={open}
-      onOpenChange={setOpen}
-      menu={menu}
-      trigger={['click']}
-    >
-      <Button>Click me</Button>
-    </CapDropdown>
-  );
-}
-```
-
-### CapDropdown.Button Usage
-
-```tsx
-import { CapDropdown } from '@capillarytech/blaze-ui';
-
-function App() {
-  const menu = {
-    items: [
-      { key: '1', label: 'Action 1' },
-      { key: '2', label: 'Action 2' },
-    ],
-  };
-
-  return (
-    <CapDropdown.Button
-      onClick={() => console.log('Main button clicked')}
-      menu={menu}
-    >
-      Actions
-    </CapDropdown.Button>
-  );
-}
-```
-
-### With Custom Overlay Styling
-
-```tsx
-import { CapDropdown } from '@capillarytech/blaze-ui';
-import { Button } from 'antd-v5';
-
-function App() {
-  const menu = {
-    items: [
-      { key: '1', label: 'Item 1' },
-      { key: '2', label: 'Item 2' },
-    ],
-  };
-
-  return (
-    <CapDropdown
-      menu={menu}
-      classNames={{
-        root: 'custom-dropdown-overlay'
-      }}
-    >
-      <Button>Hover me</Button>
-    </CapDropdown>
-  );
-}
-```
-
-### With Menu Item Handlers
-
-```tsx
-import { CapDropdown } from '@capillarytech/blaze-ui';
-import { Button } from 'antd-v5';
-import type { MenuProps } from 'antd-v5';
-
-function App() {
-  const menu: MenuProps = {
-    items: [
-      {
-        key: '1',
-        label: 'Item 1',
-        onClick: () => console.log('Item 1 clicked'),
-      },
-      {
-        key: '2',
-        label: 'Item 2',
-        onClick: () => console.log('Item 2 clicked'),
-      },
-    ],
-  };
-
-  return (
-    <CapDropdown menu={menu}>
-      <Button>Hover me</Button>
-    </CapDropdown>
-  );
-}
-```
-
-### Legacy Overlay Prop (Deprecated)
-
-The `overlay` prop is supported for backward compatibility but is deprecated. It will show console warnings in development mode.
-
-```tsx
-import { CapDropdown, CapMenu, CapIcon } from '@capillarytech/blaze-ui';
-
-function App() {
-  const handleEdit = () => {
-    console.log('Edit clicked');
-  };
-
-  const handleRemove = () => {
-    console.log('Remove clicked');
-  };
-
-  return (
-    <CapDropdown
-      overlay={
-        <CapMenu>
-          <CapMenu.Item onClick={handleEdit}>Edit</CapMenu.Item>
-          <CapMenu.Item onClick={handleRemove}>Remove</CapMenu.Item>
-        </CapMenu>
-      }
-      placement="bottomRight"
-      trigger={['click']}
-    >
-      <CapIcon type="more" />
-    </CapDropdown>
-  );
-}
-```
-
-**Migration**: Convert `overlay` with `CapMenu` to the `menu` prop format shown in the "With Menu Item Handlers" example above.
-
-## TypeScript Types
-
-```typescript
-import type {
-  CapDropdownProps,
-  CapDropdownButtonProps,
-  DeprecatedPlacement,
-  V6Placement,
-} from '@capillarytech/blaze-ui/CapDropdown';
-
-// Main component props
-interface CapDropdownProps extends Omit<DropdownProps, 'menu' | 'visible' | 'onVisibleChange' | 'overlayClassName' | 'placement' | 'overlay' | 'overlayStyle'> {
-  className?: string;
-  classNames?: DropdownProps['classNames'];
-  styles?: DropdownProps['styles'];
-  overlayClassName?: string; // @deprecated
-  overlayStyle?: React.CSSProperties; // @deprecated
-  menu?: DropdownProps['menu'];
-  overlay?: React.ReactNode; // @deprecated - Use menu prop for menu configurations or dropdownRender for custom ReactNodes
-  trigger?: Array<'click' | 'hover' | 'contextMenu'>;
-  placement?: DeprecatedPlacement | V6Placement;
-  open?: boolean;
-  onOpenChange?: (open: boolean) => void;
-  visible?: boolean; // @deprecated
-  onVisibleChange?: (visible: boolean) => void; // @deprecated
-  disabled?: boolean;
-}
-
-// Button subcomponent props
-interface CapDropdownButtonProps extends Omit<CapDropdownProps, 'children'> {
-  children?: React.ReactNode;
-  onClick?: ButtonProps['onClick'];
-  type?: ButtonProps['type'];
-  size?: ButtonProps['size'];
-  danger?: boolean;
-  loading?: boolean;
-  icon?: React.ReactNode;
-  buttonsRender?: (buttons: [React.ReactNode, React.ReactNode]) => [React.ReactNode, React.ReactNode];
-}
-```
-
-## Notes
-
-- The component uses SCSS modules for styling to avoid style conflicts
-- All deprecated props are backward compatible but will show console warnings in development
-- The component uses Ant Design v6 APIs internally
-- `CapDropdown.Button` replaces the deprecated `Dropdown.Button` pattern
-- Placement values `topCenter` and `bottomCenter` are automatically mapped to `top` and `bottom`

package/CapDropdown/Status.md

@@ -1,45 +0,0 @@
-# Migration Status: CapDropdown
-
-**Last Updated**: 2026-01-19 03:33:12
-
-## 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 Analysis Completed
-- [x] **Step 9**: Git Commit & Push to branch (pre-commit hook will run tests)
-- [x] **Step 10**: Create Pull Request
-
-## Visual Testing Results
-
-**Last Test**: 2026-01-19 03:31:42
-**Maximum Mismatch**: 3.60%
-
-### Mismatched Variants:
-- default:2.04%
-- placement-top:2.35%
-- trigger-click:2.60%
-- disabled:3.60%
-- open (with 2 interactions):3.41%
-- hover-open (with 2 interactions):3.41%
-
-
-## CSS Fixes Applied
-
-**Date**: 2026-01-19 03:32:15
-**Summary**: CSS fixes applied based on visual testing analysis.
-
-_See full analysis in: `/Users/sarahkhader/repos/migration/blaze-ui/tools/visual-testing/report/CapDropdown/css-fix-analysis.md`_
-
-
-## Notes
-
-_No notes yet._
-

package/CapDropdown/tests/USE_CASES_ANALYSIS.md

@@ -1,137 +0,0 @@
-# CapDropdown Use Cases Analysis
-
-## Phase 1: Use Cases NOT Fulfilled by Component
-
-Based on analysis of the CapDropdown component implementation and comparison with Ant Design v6 Dropdown API, the following use cases may NOT be fully fulfilled:
-
-### 1. **Menu Item Disabled State**
-- **Status**: ✅ Supported (via Ant Design menu items API)
-- **Note**: Component passes through menu prop, so disabled items should work via `menu.items[].disabled`
-
-### 2. **Submenu/Nested Menus**
-- **Status**: ✅ Supported (via Ant Design menu items API)
-- **Note**: Component passes through menu prop, so nested menus should work via `menu.items[].children`
-
-### 3. **Menu Item Icons**
-- **Status**: ✅ Supported (via Ant Design menu items API)
-- **Note**: Component passes through menu prop, so icons work via `menu.items[].icon`
-
-### 4. **Menu Item Danger State**
-- **Status**: ✅ Supported (via Ant Design menu items API)
-- **Note**: Component passes through menu prop, so danger items work via `menu.items[].danger`
-
-### 5. **Custom Menu Rendering**
-- **Status**: ⚠️ Limited Support
-- **Issue**: Component doesn't expose `menu` render prop or custom menu component support
-- **Workaround**: Can use `menu` prop with `items` array, but cannot use render props pattern
-
-### 6. **Menu Item Click Prevention**
-- **Status**: ✅ Supported
-- **Note**: Can prevent default behavior in `onClick` handler
-
-### 7. **Menu Positioning with getPopupContainer**
-- **Status**: ⚠️ Not Explicitly Supported
-- **Issue**: Component doesn't expose `getPopupContainer` prop from Ant Design Dropdown
-- **Impact**: Menus always render in document.body portal, cannot be scoped to specific container
-- **Workaround**: None - would need to add prop passthrough
-
-### 8. **Menu Destroy on Hide**
-- **Status**: ⚠️ Not Explicitly Supported
-- **Issue**: Component doesn't expose `destroyPopupOnHide` prop from Ant Design Dropdown
-- **Impact**: Menu DOM persists when closed (may affect performance with many dropdowns)
-- **Workaround**: None - would need to add prop passthrough
-
-### 9. **Menu Animation Control**
-- **Status**: ⚠️ Not Explicitly Supported
-- **Issue**: Component doesn't expose `transitionName` or animation-related props
-- **Impact**: Cannot customize menu open/close animations
-- **Workaround**: None - would need to add prop passthrough
-
-### 10. **Menu Arrow Indicator**
-- **Status**: ⚠️ Not Explicitly Supported
-- **Issue**: Component doesn't expose `arrow` prop from Ant Design Dropdown
-- **Impact**: Cannot show/hide arrow indicator on dropdown menu
-- **Workaround**: None - would need to add prop passthrough
-
-### 11. **Menu Overlay Style/ClassName per Part**
-- **Status**: ⚠️ Partially Supported
-- **Issue**: Component only supports `classNames.root` and deprecated `overlayClassName`
-- **Missing**: `classNames.menu` and other v6 classNames API parts
-- **Workaround**: Limited - can only style root overlay, not individual menu parts
-
-### 12. **Menu Auto Adjust Placement**
-- **Status**: ⚠️ Not Explicitly Supported
-- **Issue**: Component doesn't expose `autoAdjustOverflow` prop
-- **Impact**: Menu may overflow viewport if placement doesn't fit
-- **Workaround**: None - would need to add prop passthrough
-
-### 13. **Menu Trigger Element Ref Access**
-- **Status**: ⚠️ Not Explicitly Supported
-- **Issue**: Component doesn't expose ref forwarding for trigger element
-- **Impact**: Cannot programmatically access trigger element
-- **Workaround**: Wrap trigger in ref-accessible element
-
-### 14. **Menu onMenuClick Callback**
-- **Status**: ⚠️ Not Explicitly Supported
-- **Issue**: Component doesn't expose `onMenuClick` prop from Ant Design Dropdown
-- **Impact**: Cannot listen to all menu clicks at dropdown level
-- **Workaround**: Use individual item `onClick` handlers
-
-### 15. **Menu Item Selection State**
-- **Status**: ⚠️ Not Explicitly Supported
-- **Issue**: Component doesn't expose menu selection state management
-- **Impact**: Cannot create selectable menu items (like radio/checkbox menus)
-- **Workaround**: None - would need custom menu implementation
-
-### 16. **Menu Keyboard Navigation**
-- **Status**: ✅ Supported (via Ant Design)
-- **Note**: Ant Design handles keyboard navigation automatically
-
-### 17. **Menu Accessibility (ARIA)**
-- **Status**: ✅ Supported (via Ant Design)
-- **Note**: Ant Design provides ARIA attributes automatically
-
-### 18. **Menu Loading State**
-- **Status**: ⚠️ Not Explicitly Supported
-- **Issue**: Component doesn't expose menu loading state
-- **Impact**: Cannot show loading indicator in menu
-- **Workaround**: Use menu items with loading icons
-
-### 19. **Menu Empty State**
-- **Status**: ⚠️ Not Explicitly Supported
-- **Issue**: Component doesn't expose empty state rendering
-- **Impact**: Empty menu shows nothing (no empty message)
-- **Workaround**: Check menu.items.length and conditionally render
-
-### 20. **Menu Item Tooltips**
-- **Status**: ⚠️ Not Explicitly Supported
-- **Issue**: Component doesn't expose tooltip support for menu items
-- **Impact**: Cannot show tooltips on hover for truncated items
-- **Workaround**: Use menu item `title` attribute or wrap in CapTooltip
-
-## Summary
-
-**Total Use Cases Analyzed**: 20
-**Fully Supported**: 6 (30%)
-**Partially Supported**: 4 (20%)
-**Not Supported**: 10 (50%)
-
-### Recommendations
-
-1. **High Priority**: Add prop passthrough for commonly used Ant Design Dropdown props:
-   - `getPopupContainer`
-   - `destroyPopupOnHide`
-   - `arrow`
-   - `autoAdjustOverflow`
-   - `onMenuClick`
-
-2. **Medium Priority**: Enhance classNames API support:
-   - Add `classNames.menu` support
-   - Support all v6 classNames parts
-
-3. **Low Priority**: Add convenience features:
-   - Menu loading state
-   - Empty state rendering
-   - Ref forwarding for trigger
-
-4. **Documentation**: Document limitations and workarounds for unsupported use cases