0
# RC-Trigger
1

2
RC-Trigger is a foundational trigger component for React applications that manages popup behavior and positioning. It provides comprehensive trigger functionality including hover, click, focus, and context menu actions with precise popup alignment using dom-align integration, customizable animations and transitions through rc-motion, and built-in accessibility features.
3

4
## Package Information
5

6
- **Package Name**: rc-trigger
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install rc-trigger`
10

11
## Core Imports
12

13
```typescript
14
import Trigger from "rc-trigger";
15
import type { BuildInPlacements } from "rc-trigger";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const Trigger = require("rc-trigger");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import React from "react";
28
import Trigger from "rc-trigger";
29

30
function BasicExample() {
31
  return (
32
    <Trigger
33
      action={['click']}
34
      popup={<div>This is the popup content</div>}
35
      popupAlign={{
36
        points: ['tl', 'bl'],
37
        offset: [0, 4]
38
      }}
39
    >
40
      <button>Click to toggle popup</button>
41
    </Trigger>
42
  );
43
}
44
```
45

46
## Architecture
47

48
RC-Trigger is built around several key components:
49

50
- **Trigger Component**: Main component that wraps children and manages popup lifecycle
51
- **Popup System**: Internal popup rendering with portal-based positioning
52
- **Alignment Engine**: Integration with rc-align for precise popup positioning
53
- **Animation System**: RC-Motion integration for smooth show/hide transitions
54
- **Event Management**: Comprehensive event handling for multiple trigger actions
55
- **Mobile Support**: Special handling for mobile devices with touch interactions
56

57
## Capabilities
58

59
### Core Trigger Component
60

61
The main Trigger component that manages popup behavior, positioning, and lifecycle.
62

63
```typescript { .api }
64
interface TriggerProps {
65
  children: React.ReactElement;
66
  popup: React.ReactNode | (() => React.ReactNode);
67
  action?: ActionType | ActionType[];
68
  showAction?: ActionType[];
69
  hideAction?: ActionType[];
70
  popupVisible?: boolean;
71
  defaultPopupVisible?: boolean;
72
  onPopupVisibleChange?: (visible: boolean) => void;
73
  afterPopupVisibleChange?: (visible: boolean) => void;
74
  onPopupClick?: React.MouseEventHandler<HTMLDivElement>;
75
  className?: string;
76
  popupClassName?: string;
77
  popupStyle?: React.CSSProperties;
78
  prefixCls?: string;
79
  popupAlign?: AlignType;
80
  popupPlacement?: string;
81
  builtinPlacements?: BuildInPlacements;
82
  mouseEnterDelay?: number;
83
  mouseLeaveDelay?: number;
84
  focusDelay?: number;
85
  blurDelay?: number;
86
  zIndex?: number;
87
  forceRender?: boolean;
88
  destroyPopupOnHide?: boolean;
89
  mask?: boolean;
90
  maskClosable?: boolean;
91
  popupMotion?: CSSMotionProps;
92
  maskMotion?: CSSMotionProps;
93
  // ... and additional props for advanced usage
94
}
95

96
export default class Trigger extends React.Component<TriggerProps>;
97

98
/**
99
 * Internal function to generate Trigger class with custom portal component
100
 * @private Internal usage - do not use in production code
101
 */
102
function generateTrigger(PortalComponent: any): React.ComponentClass<TriggerProps>;
103
```
104

105
[Core Trigger API](./trigger-component.md)
106

107
### Positioning and Alignment
108

109
Advanced popup positioning system with precise alignment configuration and overflow handling.
110

111
```typescript { .api }
112
interface AlignType {
113
  points?: AlignPoint[];
114
  offset?: number[];
115
  targetOffset?: number[];
116
  overflow?: {
117
    adjustX?: boolean | number;
118
    adjustY?: boolean | number;
119
  };
120
  useCssRight?: boolean;
121
  useCssBottom?: boolean;
122
  useCssTransform?: boolean;
123
}
124

125
type BuildInPlacements = Record<string, AlignType>;
126
```
127

128
[Positioning System](./positioning.md)
129

130
### Animation and Motion
131

132
Motion configuration using rc-motion for smooth popup transitions and mask animations.
133

134
```typescript { .api }
135
interface TriggerProps {
136
  popupMotion?: CSSMotionProps;
137
  maskMotion?: CSSMotionProps;
138
  popupTransitionName?: TransitionNameType; // @deprecated
139
  popupAnimation?: AnimationType; // @deprecated
140
}
141
```
142

143
[Animation System](./animation.md)
144

145
### Event Handling
146

147
Comprehensive event system supporting multiple trigger actions with customizable delays and behaviors.
148

149
```typescript { .api }
150
type ActionType = 'click' | 'hover' | 'focus' | 'contextMenu';
151

152
interface TriggerProps {
153
  action?: ActionType | ActionType[];
154
  showAction?: ActionType[];
155
  hideAction?: ActionType[];
156
  mouseEnterDelay?: number;
157
  mouseLeaveDelay?: number;
158
  focusDelay?: number;
159
  blurDelay?: number;
160
}
161
```
162

163
[Event Handling](./events.md)
164

165
## Types
166

167
```typescript { .api }
168
type AlignPoint = string; // Two-character alignment points like 'tl', 'tr', 'cc'
169

170
type ActionType = string; // Actions like 'click', 'hover', 'focus', 'contextMenu', etc.
171

172
type TransitionNameType = string;
173

174
type AnimationType = string;
175

176
type StretchType = string; // Popup stretch configuration
177

178
interface Point {
179
  pageX: number;
180
  pageY: number;
181
}
182

183
interface CommonEventHandler {
184
  remove: () => void;
185
}
186

187
interface CSSMotionProps {
188
  /** CSS class name or object for motion styling */
189
  motionName?: string | {
190
    appear?: string;
191
    enter?: string;
192
    leave?: string;
193
    appearActive?: string;
194
    enterActive?: string;
195
    leaveActive?: string;
196
  };
197
  /** Whether to trigger motion on initial mount */
198
  motionAppear?: boolean;
199
  /** Whether to trigger motion on enter */
200
  motionEnter?: boolean;
201
  /** Whether to trigger motion on leave */
202
  motionLeave?: boolean;
203
  /** Remove element from DOM when leave motion completes */
204
  removeOnLeave?: boolean;
205
  /** Force render element even when motion is complete */
206
  forceRender?: boolean;
207
  /** Deadline for motion to complete (ms) */
208
  motionDeadline?: number;
209
  /** Lifecycle callbacks */
210
  onAppearStart?: (element: HTMLElement) => void;
211
  onEnterStart?: (element: HTMLElement) => void;
212
  onLeaveStart?: (element: HTMLElement) => void;
213
  onAppearActive?: (element: HTMLElement) => void;
214
  onEnterActive?: (element: HTMLElement) => void;
215
  onLeaveActive?: (element: HTMLElement) => void;
216
  onAppearEnd?: (element: HTMLElement) => void;
217
  onEnterEnd?: (element: HTMLElement) => void;
218
  onLeaveEnd?: (element: HTMLElement) => void;
219
}
220

221
interface MobileConfig {
222
  popupMotion?: CSSMotionProps;
223
  popupClassName?: string;
224
  popupStyle?: React.CSSProperties;
225
  popupRender?: (originNode: React.ReactNode) => React.ReactNode;
226
}
227
```