@king-design/intact 3.6.2-beta.1 → 3.7.0

package/components/anchor/constants.ts

@@ -0,0 +1,3 @@
+export const ANCHOR = 'Anchor';
+export const ANCHOR_LINK_LEVEL = 'AnchorLinkLevel';
+

package/components/anchor/demos/basic.md

@@ -0,0 +1,34 @@
+---
+title: 基本用法
+order: 0
+---
+
+`Anchor` 的基本用法。使用 `Anchor` 包裹多个 `AnchorLink`，每个 `AnchorLink` 的 `href` 对应页面中元素的 `id`。可以通过`Anchor`的`offset`属性，设置锚点的滚动偏移量。`AnchorLink`的`disabled`属性对应其`Tab`是否禁用。
+
+```vdt
+import {Anchor, AnchorLink} from 'kpc';
+
+<div class="anchor-demo">
+    <Anchor v-model="activeAnchor" offset={76}>
+        <AnchorLink href="components-anchor-demos-basic" title="基础用法" />
+        <AnchorLink href="components-anchor-demos-horizontal" title="水平排列" />
+        <AnchorLink href="components-anchor-demos-container" title="自定义滚动容器" disabled={true} />
+    </Anchor>
+</div>
+```
+
+```ts
+interface Props {
+    activeAnchor?: string
+}
+export default class extends Component<Props> {
+    static template = template;
+
+    static defaults() {
+        return {
+            activeAnchor: '',
+        }
+    }
+}
+```
+

package/components/anchor/demos/container.md

@@ -0,0 +1,76 @@
+---
+title: 自定义滚动容器
+order: 2
+---
+
+使用 `container` 属性可以指定滚动容器，适用于内容在特定容器内滚动的情况。默认滚动容器为`window`。
+
+```vdt
+import {Anchor, AnchorLink} from 'kpc';
+import {createVNode as h} from 'intact';
+
+<div class="anchor-demo">
+    <Anchor value={this.get('activeAnchor')} container="#scroll-container1">
+        <AnchorLink href="basic-info-card" title="基础信息" />
+        <AnchorLink href="config-info-card" title="配置信息" />
+        <AnchorLink href="other-info-card" title="其他信息" />
+    </Anchor>
+    
+    <div id="scroll-container1" class="scroll-container1">
+        <div id="basic-info-card" class="section basic-info">
+            <h2>基础信息</h2>
+            <p>这是基础信息</p>
+        </div>
+        <div id="config-info-card" class="section config-info">
+            <h2>配置信息</h2>
+            <p>这是配置信息</p>
+        </div>
+        <div id="other-info-card" class="section other-info">
+            <h2>其他信息</h2>
+            <p>这是其他信息</p>
+        </div>
+    </div>
+</div>
+```
+
+```styl
+.anchor-demo
+    display flex
+    align-items flex-start
+    gap 20px
+    
+.scroll-container1
+    position relative
+    flex 1
+    height 300px
+    overflow-y auto
+    .section
+        padding 20px
+        height 300px
+        &.basic-info
+            background #dad4f4
+        &.config-info
+            background #ecdbeb
+        &.other-info
+            background #d3fdfa
+        h2
+            margin-top 0
+```
+
+```ts
+import {bind} from 'kpc';
+
+interface Props {
+    activeAnchor?: string
+}
+export default class extends Component<Props> {
+    static template = template;
+
+    static defaults() {
+        return {
+            activeAnchor: 'config-info-card',
+        }
+    }
+}
+```
+

package/components/anchor/demos/events.md

@@ -0,0 +1,100 @@
+---
+title: 自定义事件回调
+order: 3
+---
+
+`Anchor` 组件提供了 `click` 和 `change` 事件。`click` 事件在点击锚点链接时触发，`change` 事件在锚点值改变时触发（点击锚点链接或者滑动容器至目标锚点都会触发`change`事件）。
+
+```vdt
+import {Anchor, AnchorLink, Button} from 'kpc';
+
+<div class="anchor-demo">
+    <Anchor 
+        v-model="activeAnchor" 
+        vertical={false}
+        container="#scroll-container2"
+        ev-click={this.handleAnchorClick}
+        ev-change={this.handleAnchorChange}
+    >
+        <AnchorLink href="section_one" title="section1" />
+        <AnchorLink href="section_two" title="section2" />
+        <AnchorLink href="section_three" title="section3" />
+    </Anchor>
+    <div id="scroll-container2" class="scroll-container2">
+        <div id="section_one" class="section section1">
+            <h2>Section1</h2>
+        </div>
+        <div id="section_two" class="section section2">
+            <h2>Section2</h2>
+        </div>
+        <div id="section_three" class="section section3">
+            <h2>Section3</h2>
+        </div>
+    </div>
+    <div v-if={this.get('logs').length} class="logs-container">
+        {this.get('logs').map((log, index) => <div key={index}>{log}</div>)}
+    </div>
+</div>
+```
+
+```styl
+.anchor-demo
+    display flex
+    flex-direction column
+    gap 20px
+    
+.scroll-container2
+    position relative
+    height 300px
+    overflow-y auto
+    
+.section
+    padding 20px
+    height 300px
+    &.section1
+        background #dad4f4
+    &.section2
+        background #ecdbeb
+    &.section3
+        background #d3fdfa
+    h2
+        margin-top 0
+.logs-container
+    border 1px solid #ddd
+    border-radius 4px
+    max-height 100px
+    overflow-y auto
+    padding 8px
+```
+
+```ts
+import {bind, AnchorLinkProps} from 'kpc';
+
+interface Props {
+    activeAnchor?: string
+    logs: string[]
+}
+
+export default class extends Component<Props> {
+    static template = template;
+
+    static defaults() {
+        return {
+            activeAnchor: 'section_one',
+            logs: [],
+        }
+    }
+
+    @bind
+    handleAnchorClick(e: MouseEvent, link: AnchorLinkProps) {
+        const logs = this.get('logs') || [];
+        this.set('logs', [...logs, `点击了锚点: title: ${link.title} href: ${link.href}`]);
+    }
+
+    @bind
+    handleAnchorChange(href: string) {
+        const logs = this.get('logs') || [];
+        this.set('logs', [...logs, `锚点改变为: ${href}`])
+    }
+}
+```

package/components/anchor/demos/horizontal.md

@@ -0,0 +1,33 @@
+---
+title: 水平排列
+order: 1
+---
+
+`Tabs`默认垂直排列，可以设置`vertical`为`false`，实现`Tabs`水平排列。
+
+```vdt
+import {Anchor, AnchorLink} from 'kpc';
+
+<div class="anchor-demo">
+    <Anchor v-model="activeAnchor" offset={76} vertical={false}>
+        <AnchorLink href="components-anchor-demos-basic" title="基础用法" />
+        <AnchorLink href="components-anchor-demos-horizontal" title="水平排列" />
+        <AnchorLink href="components-anchor-demos-container" title="自定义滚动容器" />
+    </Anchor>
+</div>
+```
+
+```ts
+interface Props {
+    activeAnchor?: string
+}
+export default class extends Component<Props> {
+    static template = template;
+
+    static defaults() {
+        return {
+            activeAnchor: '',
+        }
+    }
+}
+```

package/components/anchor/demos/nested.md

@@ -0,0 +1,132 @@
+---
+title: 嵌套锚点
+order: 4
+---
+
+`AnchorLink` 支持嵌套子 `AnchorLink`，嵌套的锚点会自动缩进，形成清晰的层级关系。(横向 `Anchor`，不支持嵌套)
+
+```vdt
+import {Anchor, AnchorLink} from 'kpc';
+
+<div class="anchor-demo">
+    <div id="scroll-container3" class="scroll-container3">
+        <div id="section1" class="section section1">
+            <h2>Part1</h2>
+            <p>这是Part1的内容</p>
+            <div id="section1-1" class="subsection">
+                <h3>Part1.1</h3>
+                <p>这是Part1.1</p>
+            </div>
+            <div id="section1-2" class="subsection">
+                <h3>Part1.2</h3>
+                <p>这是Part1.2的内容</p>
+                <div id="section1-2-1" class="subsubsection">
+                    <h4>Part1.2.1</h4>
+                    <p>这是Part1.2.1的内容</p>
+                </div>
+                <div id="section1-2-2" class="subsubsection">
+                    <h4>Part1.2.2</h4>
+                    <p>这是Part1.2.2的内容</p>
+                </div>
+            </div>
+            <div id="section1-3" class="subsection">
+                <h3>Part1.3</h3>
+                <p>这是Part1.3的内容</p>
+            </div>
+        </div>
+        <div id="section2" class="section section2">
+            <h2>Part2</h2>
+            <p>这是Part2的内容</p>
+            <div id="section2-1" class="subsection">
+                <h3>Part2.1</h3>
+                <p>这是Part2.1的内容</p>
+            </div>
+            <div id="section2-2" class="subsection">
+                <h3>Part2.2</h3>
+                <p>这是Part2.2的内容</p>
+            </div>
+        </div>
+        <div id="section3" class="section section3">
+            <h2>Part3</h2>
+            <p>这是Part3的内容</p>
+        </div>
+    </div>
+    <Anchor v-model="activeAnchor" container="#scroll-container3">
+        <AnchorLink href="section1" title="Part1">
+            <AnchorLink href="section1-1" title="Part1.1" />
+            <AnchorLink href="section1-2" title="Part1.2">
+                <AnchorLink href="section1-2-1" title="Part1.2.1" />
+                <AnchorLink href="section1-2-2" title="Part1.2.2" />
+            </AnchorLink>
+            <AnchorLink href="section1-3" title="Part1.3" />
+        </AnchorLink>
+        <AnchorLink href="section2" title="Part2">
+            <AnchorLink href="section2-1" title="Part2.1" />
+            <AnchorLink href="section2-2" title="Part2.2" />
+        </AnchorLink>
+        <AnchorLink href="section3" title="Part3" />
+    </Anchor>
+</div>
+```
+
+```styl
+.anchor-demo
+    display flex
+    align-items flex-start
+    gap 20px
+    
+.scroll-container3
+    flex 1
+    height 350px
+    overflow-y auto
+    
+.section
+    margin-bottom 40px
+    padding 20px
+    &.section1
+        background #f0f4ff
+    &.section2
+        background #fff0f4
+    &.section3
+        background #f4fff0
+    
+    h2
+        margin-top 0
+        color #333
+    
+.subsection
+    margin 20px 0
+    padding 15px
+    background rgba(255, 255, 255, 0.6)
+    border-radius 4px
+    
+    h3
+        margin-top 0
+        color #555
+    
+.subsubsection
+    margin 15px 0
+    padding 10px
+    background rgba(255, 255, 255, 0.8)
+    border-radius 4px
+    
+    h4
+        margin-top 0
+        color #666
+```
+
+```ts
+interface Props {
+    activeAnchor?: string
+}
+export default class extends Component<Props> {
+    static template = template;
+
+    static defaults() {
+        return {
+            activeAnchor: 'section1',
+        }
+    }
+}
+```
+

package/components/anchor/index.md

@@ -0,0 +1,38 @@
+---
+title: 锚点
+category: 组件
+order: 91
+sidebar: doc
+---
+
+# 属性
+
+## Anchor
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| value | 当前激活的锚点ID，使用`v-model`进行双向绑定 | `string` | `undefined` |
+| offset | 滚动偏移量，用于调整滚动位置（如 header 高度） | `number` | `0` |
+| container | 滚动容器，可以是CSS选择器字符串或HTMLElement对象 | `string \| HTMLElement` | `window` |
+| threshold | 激活阈值，提前多少像素激活锚点 | `number` | `50` |
+| vertical | 是否垂直排列 | `boolean` | `true` |
+| size | 放置锚点链接的`Tabs`尺寸 | `"large" \| "default" \| "small" \| "mini"` | `"default"` |
+| duration | 点击锚点链接或设置value触发的容器滚动的持续时间，单位为毫秒 | `number` | `700` |
+
+## AnchorLink
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| href | 锚点ID（对应页面元素的id），不需要包含`#` | `string` | `undefined` |
+| title | 显示文本 | `string` | `VNode` | `undefined` |
+| disabled | 是否禁用 | `boolean` | `false` |
+
+# 事件
+
+## Anchor
+
+| 事件名 | 说明 | 参数 |
+| --- | --- | --- |
+| change | 锚点改变时触发 | `(href: string) => void` |
+| click | 点击锚点时触发 | `(e: MouseEvent, props: AnchorLinkProps) => void` |
+

package/components/anchor/index.spec.ts

@@ -0,0 +1,171 @@
+import BasicDemo from '~/components/anchor/demos/basic';
+import NestedDemo from '~/components/anchor/demos/nested';
+import {mount, unmount, wait, dispatchEvent} from '../../test/utils';
+import {Anchor, AnchorLink} from './';
+import {Component} from 'intact';
+
+// 基础 Demo
+class BaseAnchorDemo extends Component {
+    static template = `
+        const {Anchor, AnchorLink} = this;
+        <div style="display: flex; gap: 20px; align-items: flex-start;">
+            <div id="scroll-container-test" style="flex: 1; height: 300px; overflow-y: auto;">
+                <div id="section1" style="height: 300px; padding: 20px;">Section 1</div>
+                <div id="section2" style="height: 300px; padding: 20px;">Section 2</div>
+                <div id="section3" style="height: 300px; padding: 20px;">Section 3</div>
+            </div>
+            <Anchor v-model="value" container="#scroll-container-test" {...this.getAnchorProps()}>
+                <AnchorLink href="section1" title="Section 1" />
+                <AnchorLink href="section2" title="Section 2" />
+                <AnchorLink href="section3" title="Section 3" />
+            </Anchor>
+        </div>
+    `;
+    Anchor = Anchor;
+    AnchorLink = AnchorLink;
+    
+    getAnchorProps() {
+        return {};
+    }
+    
+    static defaults() {
+        return {
+            value: 'section1'
+        };
+    }
+}
+
+describe('Anchor', () => {
+    afterEach(() => {
+        unmount();
+    });
+
+    it('should render basic anchor correctly', async () => {
+        const [instance, element] = mount(BasicDemo);
+        
+        await wait(200);
+        const anchor = element.querySelector('.k-anchor') as HTMLElement;
+        expect(anchor).to.exist;
+        expect(anchor.outerHTML).to.matchSnapshot();
+    });
+
+    it('should scroll to target position when clicking anchor link', async function() {
+        this.timeout(0);
+        
+        class Demo extends BaseAnchorDemo {}
+        
+        const [instance, element] = mount(Demo);
+        await wait(300);
+        
+        const container = document.querySelector('#scroll-container-test') as HTMLElement;
+        const anchor = element.querySelector('.k-anchor') as HTMLElement;
+        const secondLink = anchor.querySelectorAll('.k-tab')[1] as HTMLElement;
+        const section2 = document.getElementById('section2')!;
+        
+        // 先滚动到顶部
+        container.scrollTop = 0;
+        await wait(100);
+        
+        const initialScrollTop = container.scrollTop;
+        
+        // 点击第二个锚点链接
+        secondLink.click();
+        
+        // 等待滚动动画完成
+        await wait(800);
+        
+        // 检查容器是否滚动
+        const finalScrollTop = container.scrollTop;
+        expect(finalScrollTop).to.be.greaterThan(initialScrollTop);
+        
+        // 检查 section2 是否在视口内或接近视口顶部
+        const rect = section2.getBoundingClientRect();
+        const containerRect = container.getBoundingClientRect();
+        expect(rect.top).to.be.lessThan(containerRect.bottom);
+    });
+
+    it('should update value when scrolling', async function() {
+        this.timeout(0);
+        
+        class Demo extends BaseAnchorDemo {}
+        
+        const [instance, element] = mount(Demo);
+        await wait(300);
+        
+        const container = document.querySelector('#scroll-container-test') as HTMLElement;
+        
+        const targetScrollTop = 300;
+        container.scrollTop = targetScrollTop;
+
+        dispatchEvent(container, 'scroll');
+        await new Promise(resolve => requestAnimationFrame(resolve));
+        await wait(100);
+
+        expect(instance.get('value')).to.eql('section2');
+    });
+
+    it('should trigger change event', async function() {
+        this.timeout(0);
+        
+        class Demo extends BaseAnchorDemo {
+            onChange = sinon.spy();
+            
+            getAnchorProps() {
+                return {
+                    'ev-change': this.onChange
+                };
+            }
+        }
+        
+        const [instance, element] = mount(Demo);
+        await wait(300);
+        
+        const anchor = element.querySelector('.k-anchor') as HTMLElement;
+        const secondLink = anchor.querySelectorAll('.k-tab')[1] as HTMLElement;
+        
+        secondLink.click();
+        await wait(300);
+        
+        expect(instance.onChange.calledOnce).to.be.true;
+        expect(instance.onChange.calledWith('section2')).to.be.true;
+    });
+
+    it('should render nested anchor links correctly', async () => {
+        const [instance, element] = mount(NestedDemo);
+        
+        await wait(200);
+        const anchor = element.querySelector('.k-anchor') as HTMLElement;
+        expect(anchor).to.exist;
+        
+        const nestedLinks = anchor.querySelectorAll('.k-anchor-link-nested');
+        expect(nestedLinks.length).to.be.greaterThan(0);
+        expect(anchor.outerHTML).to.matchSnapshot();
+    });
+
+    it('should support disabled anchor link', async () => {
+        class Demo extends BaseAnchorDemo {
+            static template = `
+                const {Anchor, AnchorLink} = this;
+                <div style="display: flex; gap: 20px; align-items: flex-start;">
+                    <div id="scroll-container-test" style="flex: 1; height: 300px; overflow-y: auto;">
+                        <div id="section1" style="height: 300px; padding: 20px;">Section 1</div>
+                        <div id="section2" style="height: 300px; padding: 20px;">Section 2</div>
+                    </div>
+                    <Anchor v-model="value" container="#scroll-container-test">
+                        <AnchorLink href="section1" title="Section 1" />
+                        <AnchorLink href="section2" title="Section 2" disabled={true} />
+                    </Anchor>
+                </div>
+            `;
+        }
+        
+        const [instance, element] = mount(Demo);
+        await wait(200);
+        
+        const anchor = element.querySelector('.k-anchor') as HTMLElement;
+        const disabledLink = anchor.querySelectorAll('.k-tab')[1] as HTMLElement;
+        
+        expect(disabledLink.className).to.include('k-disabled');
+        expect(anchor.outerHTML).to.matchSnapshot();
+    });
+});