Skip to content

Commit 68f6bdd

Browse files
wangdicoderwangdicoder
committed
docs: add Overlay component documentation and examples
Add English and Chinese docs with four demo examples (basic, blurred, mask types, custom content) and register Overlay in the docs router under the Feedback category.
1 parent 4116ab5 commit 68f6bdd

7 files changed

Lines changed: 240 additions & 0 deletions

File tree

‎apps/docs/src/routers.tsx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -129,6 +129,7 @@ const c = {
129129
speedDial: ll(() => import('../../../packages/react/src/speed-dial/index.md'), () => import('../../../packages/react/src/speed-dial/index.zh_CN.md')),
130130
anchor: ll(() => import('../../../packages/react/src/anchor/index.md'), () => import('../../../packages/react/src/anchor/index.zh_CN.md')),
131131
autoComplete: ll(() => import('../../../packages/react/src/auto-complete/index.md'), () => import('../../../packages/react/src/auto-complete/index.zh_CN.md')),
132+
overlay: ll(() => import('../../../packages/react/src/overlay/index.md'), () => import('../../../packages/react/src/overlay/index.zh_CN.md')),
132133
};
133134

134135
export const getGuideMenu = (s: SiteLocale): RouterItem[] => {
@@ -238,6 +239,7 @@ export const getComponentMenu = (s: SiteLocale): RouterItem[] => {
238239
{ title: 'Alert', route: 'alert', component: pick(c.alert, z) },
239240
{ title: 'Drawer', route: 'drawer', component: pick(c.drawer, z) },
240241
{ title: 'Loader', route: 'loader', component: pick(c.loader, z) },
242+
{ title: 'Overlay', route: 'overlay', component: pick(c.overlay, z) },
241243
{ title: 'Loading Bar', route: 'loading-bar', component: pick(c.loadingBar, z) },
242244
{ title: 'Message', route: 'message', component: pick(c.message, z) },
243245
{ title: 'Modal', route: 'modal', component: pick(c.modal, z) },

‎packages/react/src/overlay/demo/basic.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<Demo>
2+
3+
### Basic
4+
5+
Basic overlay with a default mask.
6+
7+
8+
```jsx live
9+
() => {
10+
const Wrapper = () => {
11+
const [isShow, setIsShow] = React.useState(false);
12+
13+
return (
14+
<>
15+
<Button btnType="primary" onClick={() => setIsShow(true)}>Show Overlay</Button>
16+
<Overlay isShow={isShow} clickCallback={() => setIsShow(false)}>
17+
<div style={{ position: 'fixed', top: '50%', left: '50%', transform: 'translate(-50%, -50%)', color: '#fff', fontSize: 20 }}>
18+
Click the overlay to close
19+
</div>
20+
</Overlay>
21+
</>
22+
);
23+
};
24+
25+
return <Wrapper />;
26+
}
27+
```
28+
29+
</Demo>

‎packages/react/src/overlay/demo/blurred.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<Demo>
2+
3+
### Blurred
4+
5+
Overlay with a blurred backdrop effect.
6+
7+
8+
```jsx live
9+
() => {
10+
const Wrapper = () => {
11+
const [isShow, setIsShow] = React.useState(false);
12+
13+
return (
14+
<>
15+
<Button btnType="primary" onClick={() => setIsShow(true)}>Blurred Overlay</Button>
16+
<Overlay isShow={isShow} blurred clickCallback={() => setIsShow(false)}>
17+
<div style={{ position: 'fixed', top: '50%', left: '50%', transform: 'translate(-50%, -50%)', color: '#fff', fontSize: 20 }}>
18+
Blurred backdrop overlay
19+
</div>
20+
</Overlay>
21+
</>
22+
);
23+
};
24+
25+
return <Wrapper />;
26+
}
27+
```
28+
29+
</Demo>

‎packages/react/src/overlay/demo/custom-content.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
<Demo>
2+
3+
### Custom Content
4+
5+
Overlay can wrap any custom content rendered above the mask.
6+
7+
8+
```jsx live
9+
() => {
10+
const Wrapper = () => {
11+
const [isShow, setIsShow] = React.useState(false);
12+
13+
return (
14+
<>
15+
<Button btnType="primary" onClick={() => setIsShow(true)}>Custom Content</Button>
16+
<Overlay isShow={isShow} clickCallback={() => setIsShow(false)}>
17+
<div
18+
style={{
19+
position: 'fixed',
20+
top: '50%',
21+
left: '50%',
22+
transform: 'translate(-50%, -50%)',
23+
background: '#fff',
24+
borderRadius: 8,
25+
padding: '24px 32px',
26+
textAlign: 'center',
27+
}}
28+
onClick={(e) => e.stopPropagation()}
29+
>
30+
<h3 style={{ margin: '0 0 12px' }}>Custom Panel</h3>
31+
<p style={{ margin: '0 0 16px', color: '#666' }}>This content is rendered inside the overlay.</p>
32+
<Button btnType="primary" onClick={() => setIsShow(false)}>Close</Button>
33+
</div>
34+
</Overlay>
35+
</>
36+
);
37+
};
38+
39+
return <Wrapper />;
40+
}
41+
```
42+
43+
</Demo>

‎packages/react/src/overlay/demo/mask-types.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<Demo>
2+
3+
### Mask Types
4+
5+
Overlay supports three mask types: `default`, `inverted`, and `none`.
6+
7+
8+
```jsx live
9+
() => {
10+
const Wrapper = () => {
11+
const [visible, setVisible] = React.useState(false);
12+
const [type, setType] = React.useState('default');
13+
14+
const open = (t) => {
15+
setType(t);
16+
setVisible(true);
17+
};
18+
19+
return (
20+
<>
21+
<Flex gap={12}>
22+
<Button onClick={() => open('default')}>Default</Button>
23+
<Button onClick={() => open('inverted')}>Inverted</Button>
24+
<Button onClick={() => open('none')}>None</Button>
25+
</Flex>
26+
<Overlay isShow={visible} type={type} clickCallback={() => setVisible(false)}>
27+
<div style={{ position: 'fixed', top: '50%', left: '50%', transform: 'translate(-50%, -50%)', color: type === 'none' ? '#333' : '#fff', fontSize: 20 }}>
28+
Mask type: {type} (click to close)
29+
</div>
30+
</Overlay>
31+
</>
32+
);
33+
};
34+
35+
return <Wrapper />;
36+
}
37+
```
38+
39+
</Demo>

‎packages/react/src/overlay/index.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
import Basic from './demo/basic.md'
2+
import Blurred from './demo/blurred.md'
3+
import MaskTypes from './demo/mask-types.md'
4+
import CustomContent from './demo/custom-content.md'
5+
6+
# Overlay
7+
8+
A mask layer that covers the page content.
9+
10+
## Scenario
11+
12+
When you need a mask layer to cover the page content, such as when displaying a modal dialog, drawer, or any floating panel that requires a backdrop. **Overlay** provides a low-level building block with fade animation, scroll locking, and multiple mask types.
13+
14+
## Usage
15+
16+
```jsx
17+
import { Overlay } from 'tiny-ui';
18+
```
19+
20+
## Examples
21+
22+
<Layout>
23+
<Column>
24+
<Basic/>
25+
<MaskTypes/>
26+
</Column>
27+
<Column>
28+
<Blurred/>
29+
<CustomContent/>
30+
</Column>
31+
</Layout>
32+
33+
## API
34+
35+
| Property | Description | Type | Default |
36+
| -------------- | ---------------------------------------------- | ------------------------------------------------------------- | --------- |
37+
| isShow | whether the overlay is visible | boolean | false |
38+
| blurred | whether to apply a blurred backdrop effect | boolean | false |
39+
| unmountOnExit | whether to unmount when hidden | boolean | true |
40+
| zIndex | z-index of the overlay | number | 1000 |
41+
| type | mask type | enum: `default` &#124; `inverted` &#124; `none` | `default` |
42+
| clickCallback | callback when the overlay is clicked | (e: MouseEvent) => void | - |
43+
| onEnter | callback before enter transition starts | () => void | - |
44+
| onEntered | callback after enter transition finishes | () => void | - |
45+
| onExit | callback before exit transition starts | () => void | - |
46+
| onExited | callback after exit transition finishes | () => void | - |
47+
| children | content rendered inside the overlay | ReactNode | - |
48+
| style | style object of container | CSSProperties | - |
49+
| className | className of container | string | - |

‎packages/react/src/overlay/index.zh_CN.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
import Basic from './demo/basic.md'
2+
import Blurred from './demo/blurred.md'
3+
import MaskTypes from './demo/mask-types.md'
4+
import CustomContent from './demo/custom-content.md'
5+
6+
# Overlay
7+
8+
覆盖页面内容的遮罩层。
9+
10+
## 使用场景
11+
12+
当你需要一个遮罩层来覆盖页面内容时，例如显示模态对话框、抽屉或任何需要背景遮罩的浮层。**Overlay** 提供了一个低级构建块，具有淡入淡出动画、滚动锁定和多种遮罩类型。
13+
14+
## 引入方式
15+
16+
```jsx
17+
import { Overlay } from 'tiny-ui';
18+
```
19+
20+
## 代码示例
21+
22+
<Layout>
23+
<Column>
24+
<Basic/>
25+
<MaskTypes/>
26+
</Column>
27+
<Column>
28+
<Blurred/>
29+
<CustomContent/>
30+
</Column>
31+
</Layout>
32+
33+
## API
34+
35+
| 属性 | 说明 | 类型 | 默认值 |
36+
| -------------- | ------------------------------------------ | ------------------------------------------------------------- | --------- |
37+
| isShow | 遮罩层是否可见 | boolean | false |
38+
| blurred | 是否应用模糊背景效果 | boolean | false |
39+
| unmountOnExit | 隐藏时是否卸载 | boolean | true |
40+
| zIndex | 遮罩层的 z-index | number | 1000 |
41+
| type | 遮罩类型 | enum: `default` &#124; `inverted` &#124; `none` | `default` |
42+
| clickCallback | 点击遮罩层时的回调 | (e: MouseEvent) => void | - |
43+
| onEnter | 进入过渡开始前的回调 | () => void | - |
44+
| onEntered | 进入过渡结束后的回调 | () => void | - |
45+
| onExit | 退出过渡开始前的回调 | () => void | - |
46+
| onExited | 退出过渡结束后的回调 | () => void | - |
47+
| children | 遮罩层内渲染的内容 | ReactNode | - |
48+
| style | 容器的样式对象 | CSSProperties | - |
49+
| className | 容器的类名 | string | - |

0 commit comments

Comments
 (0)