@capillarytech/blaze-ui 5.20.0 → 5.22.0

package/CapTab/README.md

@@ -1,406 +0,0 @@
-# CapTab
-
-Enhanced tab component built on Ant Design v6 with backward compatibility for Ant Design v3/v5 APIs.
-
-## Summary of Changes from cap-ui-library
-
-The `CapTab` component has been migrated from `cap-ui-library` to `blaze-ui` with the following updates:
-
-- **TypeScript**: Full TypeScript implementation with proper type definitions
-- **Ant Design v6**: Updated to use Ant Design v6 APIs while maintaining backward compatibility
-- **SCSS Modules**: Uses SCSS modules for styling
-- **Enhanced API**: Added support for Ant Design v6 `items` prop pattern
-- **Backward Compatible**: All deprecated props from Ant Design v3/v5 still work with console warnings
-
-## Props
-
-### Supported Props
-
-The component accepts all Ant Design v6 `Tabs` props, plus the following additions:
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `panes` | `TabPaneData[]` | `[]` | Array of tab pane data objects |
-| `className` | `string` | - | Custom class name for the tabs wrapper |
-| `animated` | `boolean \| { inkBar?: boolean; tabPane?: boolean }` | `true` (except when `type="card"`) | Animation configuration |
-| `type` | `'line' \| 'card' \| 'editable-card'` | `'line'` | Tab type |
-| `size` | `'large' \| 'middle' \| 'small'` | `'middle'` | Tab size |
-| `tabPlacement` | `'top' \| 'end' \| 'bottom' \| 'start'` | - | Tab placement (v6 API) |
-| `activeKey` | `string` | - | Active tab key |
-| `defaultActiveKey` | `string` | - | Default active tab key |
-| `onChange` | `(activeKey: string) => void` | - | Callback when active tab changes |
-| `onEdit` | `(targetKey: string, action: 'add' \| 'remove') => void` | - | Callback for editable tabs |
-
-### Deprecated Props (Still Supported)
-
-The following Ant Design component APIs are deprecated but still supported for backward compatibility:
-
-#### `tabPosition` Prop (Ant Design Tabs Component)
-
-- **Status:** ⚠️ Deprecated
-- **Ant Design Component:** Tabs
-- **Deprecated Prop:** `tabPosition`
-- **Replacement:** Use `tabPlacement` prop instead
-- **Migration:** Replace `tabPosition` with `tabPlacement` and update values (`left` → `start`, `right` → `end`)
-- **Removal:** Will be removed in next major version
-
-**Before (Deprecated):**
-```tsx
-import { CapTab } from '@capillarytech/blaze-ui';
-
-<CapTab 
-  tabPosition="left"
-  panes={[
-    { tab: 'Tab 1', content: 'Content 1' },
-    { tab: 'Tab 2', content: 'Content 2' },
-  ]}
-/>
-```
-
-**After (Recommended):**
-```tsx
-import { CapTab } from '@capillarytech/blaze-ui';
-
-<CapTab 
-  tabPlacement="start"
-  panes={[
-    { tab: 'Tab 1', content: 'Content 1' },
-    { tab: 'Tab 2', content: 'Content 2' },
-  ]}
-/>
-```
-
-**Placement Value Mapping:**
-- `left` → `start` (v6 API)
-- `right` → `end` (v6 API)
-- `top` → `top` (unchanged)
-- `bottom` → `bottom` (unchanged)
-
-**Note:** A deprecation warning will be shown in development mode when using `tabPosition` instead of `tabPlacement`.
-
-#### `TabPane` Children Pattern (Ant Design Tabs Component)
-
-- **Status:** ⚠️ Deprecated
-- **Ant Design Component:** Tabs
-- **Deprecated Pattern:** `TabPane` children pattern (using `<TabPane>` components as children)
-- **Replacement:** Use `items` prop (via `panes` prop in CapTab)
-- **Migration:** Convert `TabPane` children structure to `panes` array format
-- **Removal:** Will be removed in next major version
-
-**Before (Deprecated in Ant Design v6):**
-```tsx
-import { Tabs } from 'antd';
-const { TabPane } = Tabs;
-
-<Tabs>
-  <TabPane tab="Tab 1" key="1">Content 1</TabPane>
-  <TabPane tab="Tab 2" key="2">Content 2</TabPane>
-</Tabs>
-```
-
-**After (Recommended):**
-```tsx
-import { CapTab } from '@capillarytech/blaze-ui';
-
-<CapTab
-  panes={[
-    { tab: 'Tab 1', key: '1', content: 'Content 1' },
-    { tab: 'Tab 2', key: '2', content: 'Content 2' },
-  ]}
-/>
-```
-
-**Note:** CapTab internally converts the `panes` prop to Ant Design v6's `items` format. The original component from `cap-ui-library` used the `TabPane` children pattern, which is deprecated in Ant Design v6. The migrated component handles this conversion automatically.
-
-## Deprecated APIs Summary
-
-| Deprecated API | Ant Design Component | Replacement | Removal Version |
-|----------------|---------------------|-------------|----------------|
-| `tabPosition` prop | Tabs | `tabPlacement` prop | Next major version |
-| `TabPane` children pattern | Tabs | `items` prop (via `panes`) | Next major version |
-
-## API Changes
-
-### Tab Placement (Ant Design Tabs Component)
-
-**Old API (deprecated):**
-```tsx
-<CapTab 
-  tabPosition="left"
-  panes={[
-    { tab: 'Tab 1', content: 'Content 1' },
-    { tab: 'Tab 2', content: 'Content 2' },
-  ]}
-/>
-```
-
-**New API (recommended):**
-```tsx
-<CapTab 
-  tabPlacement="start"
-  panes={[
-    { tab: 'Tab 1', content: 'Content 1' },
-    { tab: 'Tab 2', content: 'Content 2' },
-  ]}
-/>
-```
-
-**Placement Value Mapping:**
-- `left` → `start` (v6 API)
-- `right` → `end` (v6 API)
-- `top` → `top` (unchanged)
-- `bottom` → `bottom` (unchanged)
-
-### TabPane Children Pattern (Ant Design Tabs Component)
-
-The original component used `TabPane` children pattern, which is deprecated in Ant Design v6. The migrated component handles this internally by converting the `panes` prop to the `items` format required by Ant Design v6.
-
-**Original Pattern (deprecated in Ant Design v6):**
-```tsx
-// This pattern is deprecated in Ant Design v6
-<Tabs>
-  <TabPane tab="Tab 1" key="1">Content 1</TabPane>
-  <TabPane tab="Tab 2" key="2">Content 2</TabPane>
-</Tabs>
-```
-
-**Current Pattern (recommended):**
-```tsx
-// CapTab handles this conversion internally
-<CapTab
-  panes={[
-    { tab: 'Tab 1', key: '1', content: 'Content 1' },
-    { tab: 'Tab 2', key: '2', content: 'Content 2' },
-  ]}
-/>
-```
-
-## 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
-
-- **Tab Placement**: Support for Ant Design v6 `tabPlacement` API with automatic mapping of deprecated values
-- **Items Format**: Internal conversion from `panes` to Ant Design v6 `items` format
-- **Animation Configuration**: Enhanced animation API supporting boolean or object configuration
-- **Stable Keys**: Automatic key generation for panes without explicit keys
-
-## Migration Steps for Consumers
-
-### Step 1: Update Imports
-
-**Before:**
-```tsx
-import { CapTab } from '@capillarytech/cap-ui-library';
-```
-
-**After:**
-```tsx
-import { CapTab } from '@capillarytech/blaze-ui';
-```
-
-### Step 2: Update Deprecated Props (Optional)
-
-While deprecated props still work, it's recommended to update them:
-
-**Before:**
-```tsx
-<CapTab 
-  tabPosition="left"
-  panes={[
-    { tab: 'Tab 1', content: 'Content 1' },
-    { tab: 'Tab 2', content: 'Content 2' },
-  ]}
-/>
-```
-
-**After:**
-```tsx
-<CapTab 
-  tabPlacement="start"
-  panes={[
-    { tab: 'Tab 1', content: 'Content 1' },
-    { tab: 'Tab 2', content: 'Content 2' },
-  ]}
-/>
-```
-
-## Code Examples
-
-### Basic Usage
-
-```tsx
-import { CapTab } from '@capillarytech/blaze-ui';
-
-function MyComponent() {
-  return (
-    <CapTab
-      panes={[
-        { tab: 'Tab 1', content: 'Content 1' },
-        { tab: 'Tab 2', content: 'Content 2' },
-        { tab: 'Tab 3', content: 'Content 3' },
-      ]}
-    />
-  );
-}
-```
-
-### With Different Tab Types
-
-```tsx
-// Line tabs (default)
-<CapTab type="line" panes={panes} />
-
-// Card tabs
-<CapTab type="card" panes={panes} />
-
-// Editable card tabs
-<CapTab 
-  type="editable-card" 
-  panes={panes}
-  onEdit={(key, action) => {
-    if (action === 'add') {
-      // Handle add
-    } else {
-      // Handle remove
-    }
-  }}
-/>
-```
-
-### With Different Tab Placements
-
-```tsx
-// Top (default)
-<CapTab tabPlacement="top" panes={panes} />
-
-// Bottom
-<CapTab tabPlacement="bottom" panes={panes} />
-
-// Start (left)
-<CapTab tabPlacement="start" panes={panes} />
-
-// End (right)
-<CapTab tabPlacement="end" panes={panes} />
-```
-
-### With Controlled Active Key
-
-```tsx
-import { useState } from 'react';
-
-function ControlledExample() {
-  const [activeKey, setActiveKey] = useState('1');
-
-  return (
-    <CapTab
-      activeKey={activeKey}
-      onChange={setActiveKey}
-      panes={[
-        { key: '1', tab: 'Tab 1', content: 'Content 1' },
-        { key: '2', tab: 'Tab 2', content: 'Content 2' },
-      ]}
-    />
-  );
-}
-```
-
-### With Disabled Tabs
-
-```tsx
-<CapTab
-  panes={[
-    { tab: 'Tab 1', content: 'Content 1' },
-    { tab: 'Tab 2', content: 'Content 2', disabled: true },
-    { tab: 'Tab 3', content: 'Content 3' },
-  ]}
-/>
-```
-
-### With Custom Tab Content
-
-```tsx
-<CapTab
-  panes={[
-    { 
-      tab: (
-        <span>
-          <Icon type="user" /> User Tab
-        </span>
-      ), 
-      content: 'User content' 
-    },
-    { 
-      tab: (
-        <span>
-          <Icon type="setting" /> Settings Tab
-        </span>
-      ), 
-      content: 'Settings content' 
-    },
-  ]}
-/>
-```
-
-### With Animation Configuration
-
-```tsx
-// Disable all animations
-<CapTab animated={false} panes={panes} />
-
-// Enable only ink bar animation
-<CapTab animated={{ inkBar: true, tabPane: false }} panes={panes} />
-
-// Enable only tab pane animation
-<CapTab animated={{ inkBar: false, tabPane: true }} panes={panes} />
-```
-
-## Import Examples
-
-### Default Import
-
-```tsx
-import CapTab from '@capillarytech/blaze-ui/components/CapTab';
-```
-
-### Named Import
-
-```tsx
-import { CapTab } from '@capillarytech/blaze-ui';
-```
-
-### With TypeScript Types
-
-```tsx
-import { CapTab } from '@capillarytech/blaze-ui';
-import type { CapTabProps, TabPaneData } from '@capillarytech/blaze-ui';
-
-const panes: TabPaneData[] = [
-  { tab: 'Tab 1', content: 'Content 1' },
-  { tab: 'Tab 2', content: 'Content 2' },
-];
-
-const props: CapTabProps = {
-  panes,
-  type: 'line',
-  size: 'middle',
-};
-```
-
-## Notes
-
-- **No Breaking Changes**: The component is fully backward compatible with `cap-ui-library` v8.x
-- **Deprecated Props**: Deprecated props will show console warnings in development mode but continue to work
-- **Tab Placement**: The `tabPosition` prop with values `left`/`right` is automatically mapped to `start`/`end` for Ant Design v6 compatibility
-- **Panes Format**: The component internally converts the `panes` prop to Ant Design v6's `items` format
-- **Animation**: By default, animations are enabled except when `type="card"` (matching original behavior)
-- **Stable Keys**: If panes don't have explicit `key` props, stable keys are generated automatically based on tab content
-
-## Related Components
-
-- `CapButton` - Button component that can be used in tab content
-- `CapIcon` - Icon component that can be used in tab labels
-- `CapCard` - Card component that can be used in tab content

package/CapTab/Status.md

@@ -1,104 +0,0 @@
-# Migration Status: CapTab
-
-**Last Updated**: 2026-02-06 17:31:34
-
-## 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
-- [ ] **Step 9**: CSS Analysis (if mismatches found)
-- [ ] **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
-
-**Status**: ✅ **VERIFIED** - All Ant Design prop changes properly documented
-
-**Verified Date**: 2026-02-06
-
-### Ant Design Components Used
-- **Tabs** (`antd-v5` / Ant Design v6)
-
-### Deprecated Ant Design Props Documented
-
-#### 1. `tabPosition` → `tabPlacement` (Ant Design Tabs Component)
-- **Status**: ✅ Documented
-- **Location**: README.md (lines 38-79), types.ts (line 26)
-- **Implementation**: 
-  - ✅ @deprecated JSDoc comment in types.ts
-  - ✅ Backward compatibility code in index.tsx (mapTabPlacement function)
-  - ✅ Console warning via logDeprecationWarning
-  - ✅ Value mapping: `left` → `start`, `right` → `end`
-- **Documentation**: Complete with Before/After examples and value mapping table
-
-#### 2. `TabPane` Children Pattern → `items` Prop (Ant Design Tabs Component)
-- **Status**: ✅ Documented
-- **Location**: README.md (lines 81-113)
-- **Implementation**:
-  - ✅ Internal conversion from `panes` prop to `items` format
-  - ✅ Handled automatically in component implementation
-- **Documentation**: Complete with Before/After examples explaining the pattern change
-
-### Verification Checklist
-
-- [x] **Ant Design Components Identified**: Tabs component identified
-- [x] **MIGRATION_CHANGELOG_TEMPLATE.md Checked**: Referenced for format guidance
-- [x] **ANTD_V6_MIGRATION.md Checked**: Confirmed Tabs prop changes match documented patterns
-- [x] **README.md Documentation**: Complete "Deprecated Props" section with:
-  - [x] Status indicators (⚠️ Deprecated)
-  - [x] Ant Design component identification
-  - [x] Deprecated prop names
-  - [x] Replacement prop names
-  - [x] Migration examples (Before/After)
-  - [x] Value mapping tables
-  - [x] Removal version information
-- [x] **@deprecated JSDoc Comments**: Present in types.ts for `tabPosition` prop
-- [x] **Backward Compatibility**: Implemented with prop mapping and fallback logic
-- [x] **Console Warnings**: Implemented via logDeprecationWarning utility
-- [x] **Deprecated APIs Summary Table**: Present in README.md (lines 115-120)
-
-### Summary
-
-All Ant Design component prop changes for CapTab have been properly documented and implemented:
-- ✅ Both deprecated Ant Design props (`tabPosition` and `TabPane` pattern) are documented
-- ✅ Documentation follows the format from MIGRATION_CHANGELOG_TEMPLATE.md and ANTD_V6_MIGRATION.md
-- ✅ Backward compatibility is maintained with console warnings
-- ✅ Migration examples are provided for each deprecated prop
-- ✅ All deprecated props clearly indicate which Ant Design component they belong to
-
-**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 17:29:59
-**Maximum Mismatch**: 2.41%
-
-### Mismatched Variants:
-- default:1.99%
-- selected:2.02%
-- disabled-tabs:2.41%
-- tab-switch (with 2 interactions):1.89%
-
-
-## CSS Fixes Applied
-
-_No CSS fixes applied yet._
-
-## Notes
-
-_No notes yet._
-

package/CapTab/tests/USE_CASE_GAPS.md

@@ -1,143 +0,0 @@
-# CapTab Use Case Gaps Analysis
-
-## Phase 0: Google Sheets Access
-
-**Status**: ⚠️ **Unable to access Google Sheets**
-
-- MCP Server `google_sheets` was not available
-- Spreadsheet ID: `1Xt8l8Q6Hw0cUYV65SlGvGcPnOtzprr0fukDR9UWJ3kg`
-- Tab: `CapTab`
-
-**Action Required**: Manual review of Google Sheets to compare use cases against component implementation.
-
-**Note**: Tests were created based on component implementation analysis, existing Storybook stories, and standard tab component requirements.
-
----
-
-## Phase 2: Test Implementation
-
-**Status**: ✅ **Complete & Optimized**
-
-**Test Coverage**: Comprehensive unit tests implemented covering:
-- Default rendering and initialization
-- Prop variations (types, sizes, placements, animations) - consolidated with `it.each`
-- User interactions (click, keyboard navigation, focus) - consolidated with `it.each`
-- Callbacks and event handlers
-- Edge cases (empty states, null/undefined values, ReactNode handling) - consolidated
-- Accessibility (ARIA attributes, keyboard navigation)
-- Backward compatibility (deprecated props)
-- Data flow and state management
-- Conditional rendering logic - consolidated with `it.each`
-- Key generation for panes without explicit keys (including ReactNode edge cases)
-- Wrapper structure and CSS classes
-- Animation config edge cases
-- mapTabPlacement edge cases
-
-**Optimizations Applied**:
-- Removed duplicate tests (consolidated ~159 tests to ~102 tests)
-- Used `it.each` for repetitive test patterns
-- Consolidated similar edge case tests
-- Added missing coverage for key generation edge cases (ReactNode without children, minimal panes)
-- Improved test maintainability and readability
-
----
-
-## Phase 1: Use Cases NOT Fulfilled by CapTab
-
-Based on component analysis, the following use cases are **NOT** currently supported:
-
-### 1. **Loading States**
-- ❌ **Loading indicator**: No loading state for tabs or tab content
-- ❌ **Skeleton loading**: No skeleton/placeholder while content loads
-- ❌ **Async content loading**: No built-in support for lazy loading tab content
-
-### 2. **Error States**
-- ❌ **Error handling**: No error state display for failed tab content
-- ❌ **Error boundaries**: No error boundary integration for tab panes
-- ❌ **Retry mechanisms**: No retry functionality for failed content
-
-### 3. **Empty States**
-- ❌ **Custom empty state**: No custom empty state message when panes array is empty
-- ❌ **Empty tab content**: No empty state for individual tab panes with no content
-- ❌ **Empty state callbacks**: No callback when empty state is displayed
-
-### 4. **Advanced Interactions**
-- ❌ **Drag and drop**: No ability to reorder tabs via drag and drop
-- ❌ **Tab closing**: No built-in close button for tabs (except editable-card type)
-- ❌ **Tab duplication**: No ability to duplicate tabs
-- ❌ **Tab context menu**: No right-click context menu for tabs
-- ❌ **Tab tooltips**: No tooltip support for tab labels
-
-### 5. **Customization**
-- ❌ **Custom tab icons**: No built-in icon prop support (requires ReactNode)
-- ❌ **Tab badges/notifications**: No badge or notification count display
-- ❌ **Custom tab styling per pane**: All tabs use same styling
-- ❌ **Tab width customization**: No per-tab width control
-- ❌ **Tab alignment options**: Limited alignment options beyond centered
-
-### 6. **Data Features**
-- ❌ **Tab persistence**: No localStorage/sessionStorage persistence
-- ❌ **Tab state management**: No built-in state management integration
-- ❌ **Tab analytics**: No analytics/tracking hooks
-- ❌ **Tab validation**: No validation before tab switch
-- ❌ **Tab dependencies**: No way to show/enforce tab dependencies
-
-### 7. **Accessibility Enhancements**
-- ❌ **Custom ARIA labels**: No per-tab ARIA label customization
-- ❌ **Screen reader announcements**: No custom announcements for tab changes
-- ❌ **Focus management**: Limited focus management options
-- ❌ **Skip links**: No skip-to-content links
-
-### 8. **Performance Features**
-- ❌ **Lazy loading**: No lazy loading for tab content
-- ❌ **Virtual scrolling**: No virtual scrolling for many tabs
-- ❌ **Content preloading**: No preloading for adjacent tabs
-- ❌ **Memoization helpers**: No built-in memoization for tab content
-
-### 9. **Integration Features**
-- ❌ **URL synchronization**: No URL hash/query param sync
-- ❌ **Router integration**: No direct router integration
-- ❌ **Form integration**: No form state preservation across tabs
-- ❌ **Multi-tab selection**: No multi-select mode
-
-### 10. **Developer Experience**
-- ❌ **Tab refs**: No ref forwarding for individual tabs
-- ❌ **Tab lifecycle hooks**: No onMount/onUnmount callbacks per tab
-- ❌ **Tab validation callbacks**: No beforeChange validation
-- ❌ **Tab animation callbacks**: No animation start/end callbacks
-
----
-
-## Component Capabilities (Verified)
-
-### ✅ **Supported Features**:
-- ✅ Basic tab rendering with panes prop
-- ✅ Multiple tab types (line, card, editable-card)
-- ✅ Tab sizes (small, middle, large)
-- ✅ Tab placements (top, bottom, start, end)
-- ✅ Controlled and uncontrolled modes
-- ✅ Disabled tabs
-- ✅ Custom className
-- ✅ Animation configuration (boolean or object)
-- ✅ ReactNode support for tab labels and content
-- ✅ Backward compatibility with deprecated props
-- ✅ onChange callback for tab switching
-- ✅ onEdit callback for editable-card type
-- ✅ Stable key generation for panes without keys
-- ✅ All Ant Design Tabs props via rest spread
-
----
-
-## Recommendations
-
-1. **High Priority**: Add loading states and error handling for better UX
-2. **Medium Priority**: Add URL synchronization and router integration
-3. **Low Priority**: Add advanced features like drag-and-drop and tab badges
-
----
-
-## Notes
-
-- Component is a wrapper around Ant Design v6 Tabs
-- Most missing features can be implemented by consumers using Ant Design props
-- Focus should be on features that require component-level logic