@capillarytech/blaze-ui 5.21.0 → 5.22.0

package/CapDrawer/tests/MISSING_USE_CASES.md

@@ -1,170 +0,0 @@
-# CapDrawer - Missing Use Cases Analysis
-
-## Phase 1: Use Cases NOT Fulfilled by Component
-
-**Note**: Unable to access Google Sheets spreadsheet. Analysis based on component code review, Ant Design Drawer API, and common drawer use cases.
-
-### 1. **Footer Support**
-- ❌ **No footer prop** - Ant Design Drawer supports `footer` prop, but CapDrawer doesn't expose it
-- ❌ **No footer slot** - Cannot add footer content (e.g., action buttons) without custom content manipulation
-- **Impact**: Users must manually add footer elements to content prop
-- **Workaround**: Add footer elements to `content` prop
-
-### 2. **Extra Actions/Header Actions**
-- ❌ **No extra prop** - Ant Design Drawer supports `extra` prop for header actions, but CapDrawer doesn't expose it
-- ❌ **No header actions slot** - Cannot add custom header buttons/icons without modifying title
-- **Impact**: Limited header customization options
-- **Workaround**: Include extra actions in `title` prop as React node
-
-### 3. **Force Render**
-- ❌ **No forceRender prop** - Ant Design Drawer supports `forceRender` to render drawer content even when closed
-- **Impact**: Cannot pre-render drawer content for performance optimization
-- **Workaround**: None - would need to add prop passthrough
-
-### 4. **Get Container**
-- ❌ **No getContainer prop** - Ant Design Drawer supports `getContainer` to control portal container
-- **Impact**: Drawer always renders in document.body portal, cannot be scoped to specific container
-- **Workaround**: None - would need to add prop passthrough
-
-### 5. **Keyboard Support**
-- ⚠️ **Limited keyboard handling** - ESC key support exists but not explicitly tested or documented
-- ❌ **No keyboard prop** - Cannot disable keyboard shortcuts
-- ❌ **No custom keyboard handlers** - Cannot override default keyboard behavior
-- **Impact**: Limited control over keyboard interactions
-
-### 6. **Z-Index Control**
-- ❌ **No zIndex prop** - Ant Design Drawer supports `zIndex` prop, but CapDrawer doesn't expose it
-- **Impact**: Cannot control drawer stacking order when multiple drawers are present
-- **Workaround**: Use CSS to override z-index, but not ideal
-
-### 7. **Auto Focus**
-- ❌ **No autoFocus prop** - Ant Design Drawer supports `autoFocus` to control focus behavior
-- **Impact**: Cannot prevent auto-focus on open (may interfere with form inputs)
-- **Workaround**: None - would need to add prop passthrough
-
-### 8. **Root Class Name**
-- ❌ **No rootClassName prop** - Ant Design Drawer v6 supports `rootClassName` for root element styling
-- **Impact**: Limited styling options for drawer wrapper
-- **Workaround**: Use `className` prop, but may not target root element
-
-### 9. **Styles API**
-- ❌ **No styles prop** - Ant Design Drawer v6 supports `styles` prop for body/header/footer styling
-- **Impact**: Cannot customize individual drawer sections without CSS overrides
-- **Workaround**: Use CSS classes, but less flexible than styles API
-
-### 10. **Class Names API**
-- ❌ **No classNames prop** - Ant Design Drawer v6 supports `classNames` prop for body/header/footer classes
-- **Impact**: Limited ability to target specific drawer sections with CSS
-- **Workaround**: Use `className` prop, but may not target specific sections
-
-### 11. **After Open/Close Callbacks**
-- ❌ **No afterOpenChange callback** - Ant Design Drawer supports `afterOpenChange` for post-animation callbacks
-- **Impact**: Cannot execute logic after drawer animation completes
-- **Workaround**: Use `onOpenChange` with timeout, but not ideal
-
-### 12. **Drawer Content Loading States**
-- ❌ **No loading prop** - Cannot show loading state within drawer
-- ❌ **No loading indicator** - No built-in loading spinner support
-- **Impact**: Must manually handle loading states in content
-- **Workaround**: Add loading components to `content` prop
-
-### 13. **Drawer Content Error States**
-- ❌ **No error prop** - Cannot display error messages or error states
-- ❌ **No error styling** - No built-in error state support
-- **Impact**: Must manually handle error states in content
-- **Workaround**: Add error components to `content` prop
-
-### 14. **Drawer Size Presets Limitations**
-- ⚠️ **Limited size options** - Only supports 's', 'r', 'l' presets (25vw, 50vw, 75vw)
-- ❌ **No extra-small or extra-large** - Cannot use 'xs' or 'xl' sizes
-- ❌ **No custom preset sizes** - Cannot define custom size presets
-- **Impact**: Limited size options, must use `width` prop for other sizes
-
-### 15. **Drawer Content Validation**
-- ❌ **No content validation** - Doesn't validate content prop type
-- ❌ **No empty state handling** - No built-in empty state support
-- **Impact**: Must manually handle empty/null content cases
-
-### 16. **Drawer Animation Control**
-- ❌ **No motion customization** - Cannot customize open/close animations
-- ❌ **No animation duration control** - Cannot adjust animation speed
-- **Impact**: Limited animation customization options
-
-### 17. **Drawer Resize Support**
-- ❌ **No resizable prop** - Ant Design Drawer doesn't support resizing, but some use cases may require it
-- **Impact**: Cannot allow users to resize drawer width
-- **Workaround**: Would need custom implementation
-
-### 18. **Multiple Drawers**
-- ⚠️ **No multi-drawer coordination** - No built-in support for managing multiple drawers
-- ❌ **No drawer stack management** - Cannot control which drawer is on top
-- **Impact**: Complex scenarios with multiple drawers require manual management
-
-### 19. **Drawer State Persistence**
-- ❌ **No state persistence** - Cannot persist drawer open state across page reloads
-- ❌ **No localStorage integration** - No built-in state persistence
-- **Impact**: Must manually implement state persistence if needed
-
-### 20. **Drawer Content Scrolling**
-- ⚠️ **Limited scroll control** - Ant Design Drawer handles scrolling, but no custom scroll behavior
-- ❌ **No scroll restoration** - Cannot restore scroll position on reopen
-- **Impact**: Scroll position resets when drawer closes/reopens
-
-### 21. **Drawer Content Lazy Loading**
-- ❌ **No lazy loading** - Content always renders when drawer is open
-- ❌ **No code splitting support** - Cannot lazy load drawer content
-- **Impact**: All drawer content loads immediately, may affect performance
-
-### 22. **Drawer Form Integration**
-- ❌ **No form integration helpers** - No built-in Form.Item wrapper or validation
-- ❌ **No form state management** - Must manually handle form state
-- **Impact**: Forms in drawers require manual setup
-
-### 23. **Drawer Content Preloading**
-- ❌ **No preload prop** - Cannot preload drawer content before opening
-- **Impact**: Content loads only when drawer opens, may cause delay
-
-### 24. **Drawer Accessibility Enhancements**
-- ⚠️ **Basic accessibility** - Relies on Ant Design defaults
-- ❌ **No aria-label prop** - Cannot provide custom aria-label
-- ❌ **No aria-describedby** - Cannot link to descriptive text
-- ❌ **No focus trap customization** - Cannot customize focus trap behavior
-- **Impact**: Limited accessibility customization options
-
-### 25. **Drawer Content Templates**
-- ❌ **No content templates** - No built-in templates for common drawer patterns
-- ❌ **No drawer types** - No preset drawer types (form, list, detail, etc.)
-- **Impact**: Must build drawer content from scratch each time
-
-## Recommendations
-
-### High Priority
-1. Add `footer` prop passthrough for action buttons
-2. Add `extra` prop passthrough for header actions
-3. Add `getContainer` prop passthrough for portal control
-4. Add `zIndex` prop passthrough for stacking control
-5. Add `afterOpenChange` callback for post-animation logic
-
-### Medium Priority
-1. Add `forceRender` prop for performance optimization
-2. Add `autoFocus` prop for focus control
-3. Add `rootClassName`, `styles`, and `classNames` props (Ant Design v6 API)
-4. Add `keyboard` prop for keyboard control
-5. Improve accessibility props (aria-label, aria-describedby)
-
-### Low Priority
-1. Add more size presets (xs, xl)
-2. Add drawer content loading state helpers
-3. Add drawer state persistence helpers
-4. Add drawer content templates
-5. Add resizable drawer support (custom feature)
-
-## Current Component Strengths
-✅ Backward compatibility with `visible` and `onVisibleChange` props  
-✅ Custom `content` prop mapping to children  
-✅ Custom `size` prop for width presets  
-✅ Custom `width` prop for explicit width values  
-✅ Comprehensive Ant Design Drawer prop passthrough (most props)  
-✅ Deprecation warnings for legacy props  
-✅ TypeScript support with proper types  
-✅ Clean API with sensible defaults  

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`