# Cedar Design Web

> Vue 3 component library. Package: @cedar-design/ui. Component prefix: C / c-.

Read the quick start and the relevant component page before generating code. Follow the documented props, events, slots, imports and styles. Do not substitute APIs from another component library.

Documentation language: en-US.

---

Document: llms/en-US/components/affix.md

<!-- Source: src/affix/README.en-US.md; locale: en-US; page: /en/components/affix/ -->

# Affix

The same scenarios, parameters and interactions as Cedar. Only component prefixes differ; themes and site shells remain independent.

## Basic examples

### Basic usage

Example source: src/affix/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const containerRef = ref<HTMLElement>()
</script>

<template>
  <p>Scroll inside the bordered area.</p>
  <div ref="containerRef" class="scroller">
    <div class="scroll-content">
      <c-affix :target="containerRef"><c-button status="primary">Basic usage</c-button></c-affix>
    </div>
  </div>
</template>

<style scoped>
.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}
</style>
```

## Layout and arrangement

### Affix direction, offset and container

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `target` | Scroller or selector; finds nearest scrolling ancestor when omitted, falling back to window | Affix direction, offset and container |
| `offset-top` | Distance from the scroll container top; accepts CSS lengths | Affix direction, offset and container |
| `offset-bottom` | Distance from the bottom; takes precedence over offset-top, including 0 | Affix direction, offset and container |
<!-- demo-config-notes:end -->


Scroll each bordered area separately to compare top/bottom affixing and offsets within an explicit scroll container.

Example source: src/affix/__demos__/offset-container-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const containerRef = ref<HTMLElement>()
return { containerRef }
})())

const scene2 = demoProxyRefs((() => {

const containerRef = ref<HTMLElement>()
return { containerRef }
})())

const scene3 = demoProxyRefs((() => {

const containerRef = ref<HTMLElement>()
return { containerRef }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="top">
    <h4><span lang="zh-CN">顶部偏移</span><span lang="en-US">Top offset</span></h4>
    <p>Scroll inside the bordered area.</p>
      <div :ref="element => (scene1.containerRef = element)" class="scroller">
        <div class="scroll-content">
          <c-affix :target="scene1.containerRef" :offset-top="80"
            ><c-button status="primary">Top offset</c-button></c-affix
          >
        </div>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="bottom">
    <h4><span lang="zh-CN">底部偏移</span><span lang="en-US">Bottom offset</span></h4>
    <p>Scroll inside the bordered area.</p>
      <div :ref="element => (scene2.containerRef = element)" class="scroller">
        <div class="scroll-content">
          <div style="height: 240px"></div>
          <c-affix :target="scene2.containerRef" :offset-bottom="20"
            ><c-button status="primary">Bottom offset</c-button></c-affix
          >
        </div>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="container">
    <h4><span lang="zh-CN">指定滚动容器</span><span lang="en-US">Scroll container</span></h4>
    <p>Scroll inside the bordered area.</p>
      <div :ref="element => (scene3.containerRef = element)" class="scroller">
        <div class="scroll-content">
          <div style="height: 40px"></div>
          <c-affix :target="scene3.containerRef" :offset-top="20"
            ><c-button status="primary">Scroll container</c-button></c-affix
          >
        </div>
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}

}
.demo-comparison-case--2 {

.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}

}
.demo-comparison-case--3 {

.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}

}
</style>
```

## Interaction and control

### Change event

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `target` | Scroller or selector; finds nearest scrolling ancestor when omitted, falling back to window | Change event, Disabled, CSS mode and manual update |
| `offset-top` | Distance from the scroll container top; accepts CSS lengths | Change event, Disabled, CSS mode and manual update |
| `disabled` | Disable affixing | Disabled, CSS mode and manual update |
| `css-mode` | Use native position: sticky, subject to ancestor overflow and container boundaries | Disabled, CSS mode and manual update |
| `z-index` | Stacking level | Disabled, CSS mode and manual update |
<!-- demo-config-notes:end -->


Example source: src/affix/__demos__/fix-change.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const containerRef = ref<HTMLElement>()
const fixed = ref(false)
</script>

<template>
  <p>Scroll inside the bordered area.</p>
  <div ref="containerRef" class="scroller">
    <div class="scroll-content">
      <div style="height: 40px"></div>
      <c-affix :target="containerRef" :offset-top="20" @change="fixed = $event"
        ><c-button status="primary">Change event</c-button></c-affix
      >
    </div>
  </div>
  <p role="status">Fixed: {{ fixed }}</p>
</template>

<style scoped>
.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}
</style>
```

### Disabled, CSS mode and manual update

Example source: src/affix/__demos__/controls.vue

```vue
<script setup lang="ts">
import { nextTick, ref } from "vue";
const containerRef = ref<HTMLElement>();
const affixRef = ref<{ updatePosition: () => Promise<void> }>();
const disabled = ref(false);
const cssMode = ref(false);
const spacerHeight = ref(40);
const updates = ref(0);
async function updateLayout() {
  spacerHeight.value = spacerHeight.value === 40 ? 100 : 40;
  await nextTick();
  await affixRef.value?.updatePosition();
  updates.value++;
}
</script>

<template>
  <c-space wrap size="12px" style="margin-bottom: 12px">
    <c-checkbox v-model="disabled"> Disabled</c-checkbox>
    <c-checkbox v-model="cssMode"> CSS sticky</c-checkbox>
    <c-button @click="updateLayout">Change layout and update position</c-button>
  </c-space>
  <p aria-live="polite">Position updates: {{ updates }}</p>
  <div ref="containerRef" class="scroller">
    <div class="scroll-content">
      <div :style="{ height: `${spacerHeight}px` }"></div>
      <c-affix
        ref="affixRef"
        :target="containerRef"
        :disabled="disabled"
        :css-mode="cssMode"
        :offset-top="12"
        :z-index="2"
      >
        <c-button status="primary">Scroll to pin</c-button>
      </c-affix>
    </div>
  </div>
</template>

<style scoped>
.scroller {
  height: 200px;
  overflow: auto;
  border: 1px solid currentColor;
}
.scroll-content {
  min-height: 600px;
  padding: 16px;
}
</style>
```

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| offset-top | Distance from the scroll container top; accepts CSS lengths | `number / string` | `0` |
| offset-bottom | Distance from the bottom; takes precedence over offset-top, including 0 | `number / string` | `undefined` |
| target | Scroller or selector; finds nearest scrolling ancestor when omitted, falling back to window | `string / HTMLElement / Window` | `undefined` |
| target-container | Extra outer scroller to listen to; omitted means no extra listener, and it is not a clipping boundary | `string / HTMLElement / Window` | `undefined` |
| z-index | Stacking level | `number / string` | `10` |
| disabled | Disable affixing | `boolean` | `false` |
| css-mode | Use native position: sticky, subject to ancestor overflow and container boundaries | `boolean` | `false` |

### Events

| Event | Arguments and timing |
| --- | --- |
| change | `(fixed: boolean, offset: number)`, emitted when the fixed state changes. While fixed, offset is the affix threshold; otherwise it is the distance to the corresponding container edge. Disabling affixing reports 0. |

### Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| default | Content to affix | — |

### Methods

| Method | Description | Arguments | Returns |
| --- | --- | --- | --- |
| updatePosition | Rebind scrollers and recalculate on the next animation frame | — | `Promise<void>` |

### Platform notes

Props, event arguments, slots and public methods match across platforms. CSS mode follows browser sticky rules; examples use independent scroll containers.
<!-- same-source-api:end -->

### Type definitions

The component exports the following types

```ts
import type { AffixInstance } from '@cedar-design/ui'
```

`change` reports state transitions, so remeasuring an already fixed item does not repeat `true`; disabling a fixed item reports `false, 0`. Viewport units are reevaluated during measurement. CSS mode passes valid lengths to native sticky positioning; JS mode resolves numbers, numeric strings, px, rem, vw, vh, vmin and vmax. The target controls observation and JS measurement; native sticky remains constrained by actual CSS ancestors. Pending `updatePosition()` work cannot rebind a deactivated or replaced activation generation.

---

Document: llms/en-US/components/alert.md

<!-- Source: src/alert/README.en-US.md; locale: en-US; page: /en/components/alert/ -->

# Alert

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/alert/__demos__/basic.vue

```vue
<template>
  <c-alert>This is an info alert.</c-alert>
</template>

<script lang="ts" setup>
</script>
```

## Appearance and states

### Appearance configuration comparison

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/alert/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({
  variant: "tonal",
  status: "default",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["tonal","outline","standard"]},{"name":"status","values":["info","success","warning","danger","default"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'tonal', value: 'tonal' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-radio-group
          v-model="__demoAppearance['status']"
          aria-label="status"
          :options="[
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
            { label: 'default', value: 'default' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-alert v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">This is an info alert.</c-alert>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Content and presentation

### Title, alignment and banners

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Alert title | Title, alignment and banners, Action |
| `status` | Alert status | Title, alignment and banners, Show Icon |
| `center` | Whether to center the content | Title, alignment and banners |
| `banner` | Whether to display a top banner without borders or rounded corners | Title, alignment and banners |
| `show-icon` | Whether to show an icon | Show Icon |
| `closable` | Whether to show the close button | Action |
<!-- demo-config-notes:end -->


Compare title hierarchy, centered content and page-wide banners. Actions and dismiss behavior have separate examples.

Example source: src/alert/__demos__/content-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="title">
    <h4><span lang="zh-CN">提示标题</span><span lang="en-US">title</span></h4>
    <c-row :gutter="[40, 20]">
        <c-col :span="12">
          <c-alert title="Info">This is an info alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert title="Success" status="success">This is an success alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="warning">
            <template #title> Warning </template>
            This is an warning alert.
          </c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="danger">
            <template #title> Error </template>
            This is a danger alert.
          </c-alert>
        </c-col>
      </c-row>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="center">
    <h4><span lang="zh-CN">居中</span><span lang="en-US">center</span></h4>
    <c-alert center>This is a centered alert.</c-alert>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="banner">
    <h4><span lang="zh-CN">顶部公告</span><span lang="en-US">banner</span></h4>
    <c-alert banner>This is a banner alert.</c-alert>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Show Icon

- `status`: Selects the semantic state.

Example source: src/alert/__demos__/show-icon.vue

```vue
<template>
  <c-row :gutter="[40, 20]">
    <c-col :span="12">
      <c-alert :show-icon="false">This is an info alert.</c-alert>
    </c-col>
    <c-col :span="12">
      <c-alert status="success" :show-icon="false">This is an success alert.</c-alert>
    </c-col>
    <c-col :span="12">
      <c-alert status="warning" :show-icon="false">
        <template #title> Warning </template>
        This is an warning alert.
      </c-alert>
    </c-col>
    <c-col :span="12">
      <c-alert status="danger" :show-icon="false">
        <template #title> Error </template>
        This is a danger alert.
      </c-alert>
    </c-col>
  </c-row>
</template>

<script lang="ts" setup>
</script>
```

### Action

Example source: src/alert/__demos__/action.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-alert closable>
      This is an info alert.
      <template #action>
        <c-button size="sm" status="primary">Detail</c-button>
      </template>
    </c-alert>
    <c-alert title="Example" closable>
      This is an info alert.
      <template #action>
        <c-button size="sm" status="primary">Detail</c-button>
      </template>
    </c-alert>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## Customization and slots

### Custom Icon

- `status`: Selects the semantic state.

Example source: src/alert/__demos__/custom-icon.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-alert>
      <template #icon>
        <c-icon-face-smile-fill />
      </template>
      This is an alert with a custom icon.
    </c-alert>
    <c-alert status="default">
      <template #icon>
        <c-icon-exclamation-circle-fill />
      </template>
      Default type can still show a custom icon via slot.
    </c-alert>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## Interaction and control

### Dismiss controls and custom icons

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `closable` | Whether to show the close button | Dismiss controls and custom icons |
| `status` | Alert status | Dismiss controls and custom icons |
<!-- demo-config-notes:end -->


Operate the default and custom dismiss controls to compare the same dismissal behavior.

Example source: src/alert/__demos__/dismiss-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="closable">
    <h4><span lang="zh-CN">可关闭</span><span lang="en-US">closable</span></h4>
    <c-row :gutter="[40, 20]">
        <c-col :span="12">
          <c-alert closable>This is an info alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="success" closable>This is an success alert.</c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="warning" closable>
            <template #title> Warning </template>
            This is an warning alert.
          </c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert status="danger" closable>
            <template #title> Error </template>
            This is a danger alert.
          </c-alert>
        </c-col>
      </c-row>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="close-icon">
    <h4><span lang="zh-CN">自定义关闭图标</span><span lang="en-US">close icon</span></h4>
    <c-row :gutter="[40, 20]">
        <c-col :span="12">
          <c-alert closable>
            <template #close-icon>
              <c-icon-close-circle />
            </template>
            This is an info alert.
          </c-alert>
        </c-col>
        <c-col :span="12">
          <c-alert closable>
            <template #close-icon> Close </template>
            This is an info alert.
          </c-alert>
        </c-col>
      </c-row>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## API

### `<Alert>` Props

| Prop | Description | Type | Default |
| --------- | --------------------------------------------------------------------- | --------------------------------------------------- | ------------ |
| status | Alert status | `'info' \| 'success' \| 'warning' \| 'danger' \| 'default'` | `'info'` |
| variant | Visual variant | `'standard' \| 'tonal' \| 'outline'` | `'standard'` |
| color | Custom background color; overrides the background derived from type | `string` | - |
| title | Alert title | `string` | - |
| message | Content text; the default slot can also supply it | `string` | - |
| show-icon | Whether to show an icon | `boolean` | `true` |
| closable | Whether to show the close button | `boolean` | `false` |
| banner | Whether to display a top banner without borders or rounded corners | `boolean` | `false` |
| center | Whether to center the content | `boolean` | `false` |
| elevation | Elevation: `true`, `false`, or a level from `0-24` | `boolean \| number` | `false` |

### `<Alert>` Events

| Event | Description | Arguments |
| ----------- | ------------------ | ----------------------------- |
| close | Triggered when the Close button is clicked and can only be used when the Close button is displayed | `(event: MouseEvent) => void` |
| closed | Emitted after close transition | - |

### `<Alert>` Slots

| Slot | Description | Arguments |
| ---------- | -------- | ---- |
| default | Content | - |
| icon | Icon | - |
| title | Title | - |
| action | Actions | - |
| close-icon | The close icon of alert | - |

### Type definitions

The component exports the following types:

```ts
import type {
  AlertInstance,
  AlertProps,
  AlertStatus,
  AlertVariant,
} from '@cedar-design/ui'
```

### Style variables

See `style/token.less`; all variables use the `--c-alert-` prefix. Example override:

```css
:root {
  --c-alert-padding-vertical: 12px;
  --c-alert-padding-horizontal: 20px;
}
```

## Migration notes (breaking changes)

| Previous API | Current API |
| -- | -- |
| `type="error"` | `type="danger"` |
| `type="normal"` | `type="default"` |
| `closeable` | `closable` |
| `#close-element` slot | `#close-icon` slot |

Added capabilities: `variant` / `color` / `elevation` / `default` status / `closed` event.

`type="default"` renders no built-in icon. Use `#icon` when an icon is needed.

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

The close button supports keyboard activation. close fires once, and closed fires after the leave transition. Maple renamed its internal __close-icon class to __close-btn. Default icons are adapted locally in each library.

### Complete variable defaults

Colored titles, content, icons and outline borders use readable system content colors. standard and tonal share the same level-1 background; standard adds a subtle decorative border. Default titles use content-primary; body text and icons use content-secondary. The content variable also sets the root inherited color, used by close icons and actions without an explicit color. Maple dark mode inherits these colors while retaining its geometry overrides: 16px padding, 22px icons, 12px icon/close gaps and 1.5 body line height. color changes only the background; callers must also verify foreground contrast. The table lists :root defaults, not theme overrides.

| Variable | Default |
| --- | --- |
| `--c-alert-padding-vertical` | `var(--c-sys-space-4)` |
| `--c-alert-padding-horizontal` | `var(--c-sys-space-6)` |
| `--c-alert-padding-vertical-with-title` | `var(--c-sys-space-6)` |
| `--c-alert-padding-horizontal-with-title` | `var(--c-sys-space-6)` |
| `--c-alert-border-radius` | `var(--c-sys-radius-md)` |
| `--c-alert-border-width` | `1px` |
| `--c-alert-font-size-content` | `var(--c-sys-font-size-md)` |
| `--c-alert-font-size-title` | `var(--c-sys-font-size-lg)` |
| `--c-alert-font-weight-title` | `var(--c-sys-font-weight-medium)` |
| `--c-alert-line-height` | `1.5715` |
| `--c-alert-line-height-title` | `1.5` |
| `--c-alert-title-margin-bottom` | `var(--c-sys-space-2)` |
| `--c-alert-icon-size` | `16px` |
| `--c-alert-icon-margin-right` | `var(--c-sys-space-4)` |
| `--c-alert-action-margin-left` | `var(--c-sys-space-5)` |
| `--c-alert-close-margin-left` | `var(--c-sys-space-4)` |
| `--c-alert-standard-info-bg` | `rgb(var(--c-blue-1))` |
| `--c-alert-standard-info-border` | `rgb(var(--c-blue-3))` |
| `--c-alert-standard-info-title` | `var(--c-sys-color-content-info)` |
| `--c-alert-standard-info-content` | `var(--c-sys-color-content-info)` |
| `--c-alert-standard-info-icon` | `var(--c-sys-color-content-info)` |
| `--c-alert-standard-success-bg` | `rgb(var(--c-success-1))` |
| `--c-alert-standard-success-border` | `rgb(var(--c-success-3))` |
| `--c-alert-standard-success-title` | `var(--c-sys-color-content-success)` |
| `--c-alert-standard-success-content` | `var(--c-sys-color-content-success)` |
| `--c-alert-standard-success-icon` | `var(--c-sys-color-content-success)` |
| `--c-alert-standard-warning-bg` | `rgb(var(--c-warning-1))` |
| `--c-alert-standard-warning-border` | `rgb(var(--c-warning-3))` |
| `--c-alert-standard-warning-title` | `var(--c-sys-color-content-warning)` |
| `--c-alert-standard-warning-content` | `var(--c-sys-color-content-warning)` |
| `--c-alert-standard-warning-icon` | `var(--c-sys-color-content-warning)` |
| `--c-alert-standard-danger-bg` | `rgb(var(--c-danger-1))` |
| `--c-alert-standard-danger-border` | `rgb(var(--c-danger-3))` |
| `--c-alert-standard-danger-title` | `var(--c-sys-color-content-danger)` |
| `--c-alert-standard-danger-content` | `var(--c-sys-color-content-danger)` |
| `--c-alert-standard-danger-icon` | `var(--c-sys-color-content-danger)` |
| `--c-alert-standard-default-bg` | `var(--c-color-fill-2)` |
| `--c-alert-standard-default-border` | `var(--c-sys-color-border-default)` |
| `--c-alert-standard-default-title` | `var(--c-sys-color-content-primary)` |
| `--c-alert-standard-default-content` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-standard-default-icon` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-tonal-info-bg` | `rgb(var(--c-blue-1))` |
| `--c-alert-tonal-info-title` | `var(--c-sys-color-content-info)` |
| `--c-alert-tonal-info-content` | `var(--c-sys-color-content-info)` |
| `--c-alert-tonal-info-icon` | `var(--c-sys-color-content-info)` |
| `--c-alert-tonal-success-bg` | `rgb(var(--c-success-1))` |
| `--c-alert-tonal-success-title` | `var(--c-sys-color-content-success)` |
| `--c-alert-tonal-success-content` | `var(--c-sys-color-content-success)` |
| `--c-alert-tonal-success-icon` | `var(--c-sys-color-content-success)` |
| `--c-alert-tonal-warning-bg` | `rgb(var(--c-warning-1))` |
| `--c-alert-tonal-warning-title` | `var(--c-sys-color-content-warning)` |
| `--c-alert-tonal-warning-content` | `var(--c-sys-color-content-warning)` |
| `--c-alert-tonal-warning-icon` | `var(--c-sys-color-content-warning)` |
| `--c-alert-tonal-danger-bg` | `rgb(var(--c-danger-1))` |
| `--c-alert-tonal-danger-title` | `var(--c-sys-color-content-danger)` |
| `--c-alert-tonal-danger-content` | `var(--c-sys-color-content-danger)` |
| `--c-alert-tonal-danger-icon` | `var(--c-sys-color-content-danger)` |
| `--c-alert-tonal-default-bg` | `var(--c-color-fill-2)` |
| `--c-alert-tonal-default-title` | `var(--c-sys-color-content-primary)` |
| `--c-alert-tonal-default-content` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-tonal-default-icon` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-outline-info-border` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-info-title` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-info-content` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-info-icon` | `var(--c-sys-color-content-info)` |
| `--c-alert-outline-success-border` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-success-title` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-success-content` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-success-icon` | `var(--c-sys-color-content-success)` |
| `--c-alert-outline-warning-border` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-warning-title` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-warning-content` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-warning-icon` | `var(--c-sys-color-content-warning)` |
| `--c-alert-outline-danger-border` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-danger-title` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-danger-content` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-danger-icon` | `var(--c-sys-color-content-danger)` |
| `--c-alert-outline-default-border` | `var(--c-sys-color-border-default)` |
| `--c-alert-outline-default-title` | `var(--c-sys-color-content-primary)` |
| `--c-alert-outline-default-content` | `var(--c-sys-color-content-secondary)` |
| `--c-alert-outline-default-icon` | `var(--c-sys-color-content-secondary)` |

### Motion variables

Built-in motion follows `prefers-reduced-motion: reduce`. Reduced motion does not prevent loading-state or close-event updates.

| Token | Default |
| --- | --- |
| `--c-alert-close-duration` | `var(--c-sys-motion-duration-slow)` |

---

Document: llms/en-US/components/anchor.md

<!-- Source: src/anchor/README.en-US.md; locale: en-US; page: /en/components/anchor/ -->

# Anchor

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `show-background`: Whether to show the background

Example source: src/anchor/__demos__/basic.vue

```vue
<template>
  <c-anchor :show-background="false">
    <c-anchor-link href="#基础用法">基础用法</c-anchor-link>
    <c-anchor-link href="#无轴线模式">无轴线模式</c-anchor-link>
    <c-anchor-link href="#固钉位置">固钉位置
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary"
          >Scroll Boundary
          <template #sublist>
            <c-anchor-link href="#boundary1">Scroll Boundary1</c-anchor-link>
            <c-anchor-link href="#hash1">Hash mode1</c-anchor-link>
          </template>
        </c-anchor-link>
        <c-anchor-link href="#是否改变hash">是否改变hash</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup></script>
```

## Layout and arrangement

### Affix

Preview configuration: `:offsetTop="80"`, `href="#basic"`, `href="#show-line"`, `href="#affix"`.

Example source: src/anchor/__demos__/affix.vue

```vue
<template>
  <c-affix :offsetTop="80">
    <c-anchor :style="{ backgroundColor: 'var(--color-bg-1)' }">
      <c-anchor-link href="#basic">Basic</c-anchor-link>
      <c-anchor-link href="#show-line">Show Rail</c-anchor-link>
      <c-anchor-link href="#affix">
        Affix
        <template #sublist>
          <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
          <c-anchor-link href="#hash">Hash mode</c-anchor-link>
        </template>
      </c-anchor-link>
    </c-anchor>
  </c-affix>
</template>
<script lang="ts" setup>
</script>
```

## Content and presentation

### Show Line

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `show-line` | Whether to show the left axis | Show Line |
| `change-hash` | Whether to change the hash. When set to `false`, clicking on the anchor will not change the hash of the page | Hash |
<!-- demo-config-notes:end -->


- `show-line`: Whether to show the left axis

Example source: src/anchor/__demos__/show-line.vue

```vue
<template>
  <c-anchor :show-line="false">
    <c-anchor-link href="#basic">Basic</c-anchor-link>
    <c-anchor-link href="#show-line">Show Rail</c-anchor-link>
    <c-anchor-link href="#affix">
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
        <c-anchor-link href="#hash">Hash mode</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup>
</script>
```

### Hash

- `change-hash`: Whether to change the hash. When set to `false`, clicking on the anchor will not change the hash of the page

Example source: src/anchor/__demos__/hash.vue

```vue
<template>
  <c-anchor :change-hash="false">
    <c-anchor-link href="#basic">Basic</c-anchor-link>
    <c-anchor-link href="#show-line">Show Line</c-anchor-link>
    <c-anchor-link href="#affix">
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
        <c-anchor-link href="#hash">Hash mode</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup>
</script>
```

## Lifecycle and edge cases

### Boundary

- `boundary`: Scrolling boundary value. After setting the value to a number, it will stop scrolling when the distance is `boundary` from the scrolling container.

Example source: src/anchor/__demos__/boundary.vue

```vue
<template>
  <c-anchor boundary="center">
    <c-anchor-link href="#basic">Basic</c-anchor-link>
    <c-anchor-link href="#show-line">Show Rail</c-anchor-link>
    <c-anchor-link href="#affix">
      Affix
      <template #sublist>
        <c-anchor-link href="#boundary">Scroll Boundary</c-anchor-link>
        <c-anchor-link href="#hash">Hash mode</c-anchor-link>
      </template>
    </c-anchor-link>
  </c-anchor>
</template>

<script lang="ts" setup>
</script>
```

### Scroll Lifecycle

Example source: src/anchor/__demos__/scroll-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import Anchor, { AnchorLink } from "../index";

const active = ref(true);
const mounted = ref(true);
const container = ref<HTMLElement>();
const changes = ref(0);
</script>

<template>
  <div>
    <c-button html-type="button" @click="active = !active"
      >切换 KeepAlive</c-button
    >
    <c-button html-type="button" @click="mounted = !mounted"
      >卸载／挂载</c-button
    >
    <p>
      切换链接后立即停用或卸载；激活后再次点击，检查旧滚动不会恢复。change
      通知：{{ changes }}
    </p>
    <KeepAlive v-if="mounted">
      <Anchor
        v-if="active"
        :scroll-container="container"
        :change-hash="false"
        @change="changes++"
      >
        <AnchorLink href="#anchor-lifecycle-first" title="第一段" />
        <AnchorLink href="#anchor-lifecycle-second" title="第二段" />
      </Anchor>
    </KeepAlive>
    <div ref="container" style="height: 180px; overflow: auto">
      <section id="anchor-lifecycle-first" style="min-height: 240px">
        第一段内容
      </section>
      <section id="anchor-lifecycle-second" style="min-height: 240px">
        第二段内容
      </section>
    </div>
  </div>
</template>
```

## Reading direction

The axis, highlight and indentation follow reading start. Vertical scrolling and anchor targets remain unchanged.

## API

### `<anchor>` Props

| Parameter | Description | Type | Default |
| ---------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------- | :-------: |
| boundary | Scrolling `boundary` value. After setting the value to a number, it will stop scrolling when the distance is `boundary` from the scrolling container. | `'start' \| 'end' \| 'center' \| 'nearest' \| number` | `'start'` |
| show-line | Whether to show the left axis | `boolean` | `true` |
| show-background | Whether to show the background | `boolean` | `true` |
| scroll-container | Scroll container | `string \| HTMLElement \| Window` | `-` |
| change-hash | Whether to change the hash. When set to `false`, clicking on the anchor will not change the hash of the page | `boolean` | `true` |

### `<anchor>` Events

| Event | Description | Arguments |
| ------ | ------------------ | ------------------------------------------------ |
| select | Emitted when the user clicks a link | hash: `string \| undefined`<br>preHash: `string` |
| change | Emitted when the active link changes | hash: `string` |

### `<anchor-link>` Props

| Parameter | Description | Type | Default |
| ------ | ------------------ | -------- | :----: |
| title | Anchor link text | `string` | `-` |
| href | Anchor link URL | `string` | `-` |

### Type definitions

The component exports the following types

```ts
import type { AnchorInstance } from '@cedar-design/ui'
```

---

Document: llms/en-US/components/auto-complete.md

<!-- Source: src/auto-complete/README.en-US.md; locale: en-US; page: /en/components/auto-complete/ -->

# AutoComplete

Text input with suggested completions. Suggestions are arrays; application code owns remote loading.

## Reading direction

The editor and suggestion popup inherit source dir, including in custom containers. Horizontal caret keys keep native editing behavior; vertical keys navigate candidates, Enter selects and Escape closes. Candidate updates preserve the native composition buffer until composition ends instead of repainting the previous model value.

## Search and visibility

case-sensitive replaces the removed strict prop. Default matching searches label and ignores case; use search-fields to include value. Custom filter-option callbacks own their case policy; filter-option=false bypasses local filtering for remote results. AutoComplete has no public open/defaultOpen/update:open API: focusing and typing determine suggestion visibility. trigger-props can customize placement but cannot force internal open state. A public v-model:open would require a separate API change.

## Basic examples

### Basic

Example source: src/auto-complete/__demos__/basic.vue

```vue
<template>
  <c-auto-complete
    v-model="value"
    :options="options"
    placeholder="输入或选择城市"
    clearable
    style="width: 100%; max-width: 320px"
  />
  <p>当前值：{{ value || '-' }}</p>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref('')
const options = [
  'Beijing',
  { value: 310000, label: 'Shanghai' },
  { value: 'chengdu', label: 'Chengdu' },
  { value: 'wuhan', label: 'Wuhan', disabled: true },
]
</script>
```

### Interaction state comparison

Toggle disabled, read-only and error states, then interact with the same instance. Recovery controls remain outside the target; error appearance alone does not validate data.

<details>
<summary>Configuration details and limits</summary>

#### State Lab

## Appearance and states

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                  | Related examples                    |
| ------------- | ------------------------------------------------------------------------ | ----------------------------------- |
| `options`     | Suggestions, including groups; unique values become strings on selection | Appearance configuration comparison |
| `clearable`   | Allow clearing a nonempty editable value                                 | Appearance configuration comparison |

<!-- demo-config-notes:end -->

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/auto-complete/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("研发");
const options = [{ value: "研发" }, { value: "研发平台" }, { value: "设计" }];
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-auto-complete
      v-model="value"
      :options="options"
      clearable
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-auto-complete>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Matching and suggestions

### Opening Policy

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                                                                  | Related examples                              |
| ---------------- | ------------------------------------------------------------------------ | --------------------------------------------- |
| `options`        | Suggestions, including groups; unique values become strings on selection | Opening Policy, Case Sensitive, Group Spacing |
| `placeholder`    | Placeholder or floating hint text                                        | Opening Policy, Case Sensitive, Group Spacing |
| `should-open`    | Opening policy; does not filter candidates                               | Opening Policy, Group Spacing, Virtual List   |
| `filter-option`  | Filter by label; false for remote filtering                              | Opening Policy                                |
| `case-sensitive` | Case-sensitive built-in matching                                         | Case Sensitive                                |
| `trigger-props`  | Trigger configuration; cannot override owned opening and disabled state  | Group Spacing                                 |

<!-- demo-config-notes:end -->

Example source: src/auto-complete/__demos__/opening-policy.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref("");
const allowEmpty = ref(false);
const filter = ref(true);
const shouldOpen = (text: string) => allowEmpty.value || text.length >= 2;
const options = ["Cedar", "Maple", "Vue"];
</script>
<template>
  <c-space direction="column" size="md">
    <c-checkbox v-model="allowEmpty"> 允许空输入展开</c-checkbox>
    <c-checkbox v-model="filter"> 按输入过滤候选</c-checkbox>
    <c-auto-complete
      v-model="value"
      :options="options"
      :filter-option="filter"
      :should-open="shouldOpen"
      placeholder="默认输入两个字符后展开"
    />
    <p>展开条件不负责过滤；即使允许展开，没有匹配候选也不显示菜单。</p>
  </c-space>
</template>
```

### Case Sensitive

Example source: src/auto-complete/__demos__/case-sensitive.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-auto-complete v-model="looseValue" :options="options" placeholder="默认：输入 ar" style="width: 100%; max-width: 320px" />
    <c-auto-complete v-model="caseSensitiveValue" :options="options" case-sensitive placeholder="区分大小写：输入 Ar" style="width: 100%; max-width: 320px" />
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const options = ['Arco', 'Maple', 'Cedar']
const looseValue = ref('')
const caseSensitiveValue = ref('')
</script>
```

### Group Spacing

Example source: src/auto-complete/__demos__/group-spacing.vue

```vue
<script setup lang="ts">
const options = [
  {
    isGroup: true,
    label: "华北",
    options: [
      { value: "beijing", label: "北京" },
      { value: "tianjin", label: "天津" },
    ],
  },
  {
    isGroup: true,
    label: "华东",
    options: [
      { value: "shanghai", label: "上海" },
      { value: "hangzhou", label: "杭州" },
    ],
  },
];
</script>

<template>
  <c-space direction="column" size="md">
    <c-auto-complete
      :options="options"
      :should-open="() => true"
      placeholder="分组候选"
      :style="{ width: '280px' }"
    />
    <c-auto-complete
      :options="options"
      :should-open="() => true"
      placeholder="自定义缩进的分组候选"
      :style="{ width: '280px' }"
      :trigger-props="{ popupStyle: { '--c-auto-complete-option-padding-horizontal': '20px' } }"
    />
  </c-space>
</template>
```

### Virtual List

Example source: src/auto-complete/__demos__/virtual-list.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
const options = Array.from({ length: 500 }, (_, index) => ({ value: `device-${index + 1}`, label: `Device ${index + 1}` }))
</script>
<template>
  <c-auto-complete v-model="value" :options="options" :should-open="() => true"
    :virtual-list-props="{ height: 180 }" placeholder="搜索 500 个设备" />
</template>
```

## Content and field customization

### Footer

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                  | Related examples  |
| ------------- | ------------------------------------------------------------------------ | ----------------- |
| `options`     | Suggestions, including groups; unique values become strings on selection | Footer, Decorator |
| `placeholder` | Placeholder or floating hint text                                        | Footer, Decorator |
| `field-names` | Map value, label, disabled and other fields                              | Footer            |
| `variant`     | Input variant; inherits Group when unset                                 | Decorator         |
| `hint`        | Enable Input floating hint                                               | Decorator         |
| `clearable`   | Allow clearing a nonempty editable value                                 | Decorator         |

<!-- demo-config-notes:end -->

Example source: src/auto-complete/__demos__/footer.vue

```vue
<template>
  <c-auto-complete
    v-model="value"
    :options="options"
    :field-names="{ value: 'code', label: 'name', disabled: 'unavailable' }"
    placeholder="输入城市"
    style="width: 100%; max-width: 320px"
  >
    <template #option="{ data }">{{ data.label }} · {{ data.raw.country }}</template>
    <template #footer>
      <div style="padding: 6px 12px; color: var(--c-sys-color-content-tertiary)">选择候选或继续自由输入</div>
    </template>
  </c-auto-complete>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value = ref('')
const options = [
  { code: 'PEK', name: 'Beijing', country: 'CN' },
  { code: 'SHA', name: 'Shanghai', country: 'CN' },
  { code: 'NRT', name: 'Tokyo', country: 'JP', unavailable: true },
]
</script>
```

### Decorator

Example source: src/auto-complete/__demos__/decorator.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
const options = ['Cedar', 'Maple']
</script>
<template>
  <c-space direction="column" size="md">
    <c-auto-complete v-for="variant in (['filled', 'outline', 'standard'] as const)" :key="variant"
      v-model="value" :options="options" :variant="variant" :placeholder="variant" hint clearable />
    <c-auto-complete v-model="value" :options="options" hint placeholder="自定义颜色"
      focus-color="#6750a4" text-color="#386a20" enterkeyhint="search">
      <template #prefix>@</template><template #suffix>.com</template>
    </c-auto-complete>
  </c-space>
</template>
```

## Interaction and keyboard

### Api Review

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                  | Related examples          |
| ------------- | ------------------------------------------------------------------------ | ------------------------- |
| `options`     | Suggestions, including groups; unique values become strings on selection | Api Review, Accessibility |
| `clearable`   | Allow clearing a nonempty editable value                                 | Api Review                |
| `disabled`    | Disabled; inherited when unset, explicit false overrides                 | Api Review                |
| `readonly`    | Readonly; focus/copy allowed, suggestions stay closed                    | Api Review                |
| `error`       | Error state; inherits FormItem when unset                                | Api Review                |
| `input-attrs` | Native input attributes; combobox state is owned by the component        | Accessibility             |

<!-- demo-config-notes:end -->

</details>

Example source: src/auto-complete/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("研发");
const options = [{ value: "研发" }, { value: "研发平台" }, { value: "设计" }];
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-auto-complete
      v-model="value"
      :options="options"
      clearable
      v-bind="__demoState"
    ></c-auto-complete>
  </c-space>
</template>
```

### Accessibility

Example source: src/auto-complete/__demos__/accessibility.vue

```vue
<template>
  <label :for="inputId">前端框架</label>
  <c-auto-complete
    v-model="value"
    :options="options"
    :input-attrs="{ id: inputId, 'aria-describedby': helpId }"
    style="width: 100%; max-width: 320px"
  />
  <p :id="helpId">使用方向键浏览建议，Enter 选择，Escape 关闭。</p>
</template>

<script setup lang="ts">
import { ref, useId } from 'vue'

const inputId = useId()
const helpId = useId()
const value = ref('')
const options = ['Vue', 'React', 'Angular']
</script>
```

## Async data and configuration

### Remote

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                  | Related examples            |
| --------------- | ------------------------------------------------------------------------ | --------------------------- |
| `options`       | Suggestions, including groups; unique values become strings on selection | Remote, Passthrough Options |
| `filter-option` | Filter by label; false for remote filtering                              | Remote                      |
| `placeholder`   | Placeholder or floating hint text                                        | Remote                      |
| `disabled`      | Disabled; inherited when unset, explicit false overrides                 | Passthrough Options         |
| `should-open`   | Opening policy; does not filter candidates                               | Passthrough Options         |
| `trigger-props` | Trigger configuration; cannot override owned opening and disabled state  | Passthrough Options         |

<!-- demo-config-notes:end -->

Example source: src/auto-complete/__demos__/remote.vue

```vue
<template>
  <c-auto-complete
    v-model="value"
    :options="options"
    :filter-option="false"
    placeholder="输入关键字获取远程建议"
    style="width: 100%; max-width: 320px"
    @search="handleSearch"
  />
</template>

<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue'

const value = ref('')
const options = ref<string[]>([])

let requestId = 0
onBeforeUnmount(() => requestId++)
const handleSearch = async (keyword: string) => {
  const current = ++requestId
  const result = await Promise.resolve(keyword ? Array.from({ length: 4 }, (_, index) => `${keyword}-${index + 1}`) : [])
  if (current === requestId) options.value = result
}
</script>
```

### Passthrough Options

Example source: src/auto-complete/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { AutoCompleteTriggerOptions } from "@cedar-design/ui";
const disabled = ref(false);
const triggerOptions: AutoCompleteTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
  popupContainer: false,
};
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="disabled = !disabled">{{
      disabled ? "启用输入" : "禁用输入"
    }}</c-button>
    <c-auto-complete
      edit-mode="direct"
      :disabled="disabled"
      :should-open="() => true"
      :options="options"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">
      顶层 disabled：{{ disabled }}；聚焦输入框查看向上展开的候选。
    </p>
  </c-space>
</template>
```

### Props

| Prop                 | Description                                                              | Type                                                                                     | Default                          |
| -------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | -------------------------------- |
| `model-value`        | Controlled text                                                          | `string`                                                                                 | `—`                              |
| `default-value`      | Initial uncontrolled text                                                | `string`                                                                                 | `''`                             |
| `options`            | Suggestions, including groups; unique values become strings on selection | `(AutoCompleteOption \| SelectOptionGroup)[]` / `(query, { signal }) => Array / Promise` | `undefined`                      |
| `field-names`        | Map value, label, disabled and other fields                              | `AutoCompleteFieldNames`                                                                 | `—`                              |
| `should-open`        | Opening policy; does not filter candidates                               | `(value: string) => boolean`                                                             | `value.length > 0`               |
| `filter-option`      | Filter by label; false for remote filtering                              | `AutoCompleteFilterOption`                                                               | automatic: arrays on; loader off |
| `case-sensitive`     | Case-sensitive built-in matching                                         | `boolean`                                                                                | `false`                          |
| `popup-container`    | Popup container; same contract as Trigger                                | `PopupContainer`                                                                         | `—`                              |
| `trigger-props`      | Trigger configuration; cannot override owned opening and disabled state  | `TriggerProps`                                                                           | `—`                              |
| `virtual-list-props` | Enable and configure virtual scrolling                                   | `VirtualListProps`                                                                       | `—`                              |
| `size`               | Five sizes; inherit Group / Form / global configuration when unset       | `xs \| sm \| md \| lg \| xl`                                                             | `md`                             |
| `variant`            | Input variant; inherits Group when unset                                 | `filled \| outline \| standard`                                                          | `outline`                        |
| `disabled`           | Disabled; inherited when unset, explicit false overrides                 | `boolean`                                                                                | `undefined`                      |
| `readonly`           | Readonly; focus/copy allowed, suggestions stay closed                    | `boolean`                                                                                | `undefined`                      |
| `error`              | Error state; inherits FormItem when unset                                | `boolean`                                                                                | `undefined`                      |
| `clearable`          | Allow clearing a nonempty editable value                                 | `boolean`                                                                                | `false`                          |
| `placeholder`        | Placeholder or floating hint text                                        | `string`                                                                                 | `—`                              |
| `hint`               | Enable Input floating hint                                               | `boolean`                                                                                | `undefined`                      |
| `line`               | Show border or underline                                                 | `boolean`                                                                                | `true`                           |
| `text-color`         | Instance text color                                                      | `string`                                                                                 | `—`                              |
| `focus-color`        | Instance focus color                                                     | `string`                                                                                 | `—`                              |
| `blur-color`         | Instance unfocused hint color                                            | `string`                                                                                 | `—`                              |
| `enterkeyhint`       | Virtual keyboard action hint                                             | `InputHTMLAttributes['enterKeyHint']`                                                    | `—`                              |
| `aria-label`         | Accessible input name                                                    | `string`                                                                                 | `—`                              |
| `max-length`         | Same length normalization for typing and selecting                       | `number \| { length: number; errorOnly?: boolean }`                                      | `0`                              |
| `show-word-limit`    | Display word count                                                       | `boolean`                                                                                | `false`                          |
| `word-length`        | Custom length calculation                                                | `(value: string) => number`                                                              | `—`                              |
| `word-slice`         | Custom slicing                                                           | `(value: string, maxLength: number) => string`                                           | `—`                              |
| `input-attrs`        | Native input attributes; combobox state is owned by the component        | `Record<string, unknown>`                                                                | `—`                              |

### Events

| Event                                     | Arguments                                                     |
| ----------------------------------------- | ------------------------------------------------------------- |
| `update:model-value`                      | `value: string`                                               |
| `input / search / change`                 | `value: string, event: Event`                                 |
| `select`                                  | `value: string, option: AutoCompleteOptionInfo, event: Event` |
| `clear`                                   | `event: Event`                                                |
| `focus / blur`                            | `event: FocusEvent`                                           |
| `dropdown-scroll / dropdown-reach-bottom` | `event: Event`                                                |

### Slots

| Slot              | Description                        |
| ----------------- | ---------------------------------- |
| `option`          | `{ data: AutoCompleteOptionInfo }` |
| `footer`          | Menu footer                        |
| `prefix / suffix` | Input prefix / suffix              |
| `clear-icon`      | `{ clear }`                        |

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API details

| Token                                           | Default                                             |
| ----------------------------------------------- | --------------------------------------------------- |
| `--c-auto-complete-popup-max-height`            | `var(--c-select-popup-max-height)`                  |
| `--c-auto-complete-popup-bg`                    | `var(--c-select-popup-bg)`                          |
| `--c-auto-complete-popup-border-radius`         | `var(--c-select-popup-border-radius)`               |
| `--c-auto-complete-popup-padding-vertical`      | `var(--c-select-popup-padding-vertical)`            |
| `--c-auto-complete-popup-font-size`             | `var(--c-select-popup-font-size)`                   |
| `--c-auto-complete-popup-border-color`          | `var(--c-select-popup-border-color)`                |
| `--c-auto-complete-popup-box-shadow`            | `var(--c-select-popup-box-shadow)`                  |
| `--c-auto-complete-option-height`               | `var(--c-select-popup-option-height)`               |
| `--c-auto-complete-option-font-weight-selected` | `var(--c-select-popup-option-font-weight-selected)` |
| `--c-auto-complete-option-padding-horizontal`   | `var(--c-select-popup-option-padding-horizontal)`   |
| `--c-auto-complete-option-bg-default`           | `var(--c-select-popup-option-bg)`                   |
| `--c-auto-complete-option-bg-hover`             | `var(--c-select-popup-option-bg-hover)`             |
| `--c-auto-complete-option-bg-selected`          | `var(--c-select-popup-option-bg-selected)`          |
| `--c-auto-complete-option-bg-disabled`          | `var(--c-select-popup-option-bg-disabled)`          |
| `--c-auto-complete-option-text-color-default`   | `var(--c-select-popup-option-text-color)`           |
| `--c-auto-complete-option-text-color-hover`     | `var(--c-select-popup-option-text-color-hover)`     |
| `--c-auto-complete-option-text-color-selected`  | `var(--c-select-popup-option-text-color-selected)`  |
| `--c-auto-complete-option-text-color-disabled`  | `var(--c-select-popup-option-text-color-disabled)`  |

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Prop                 | Description                                                              | Type                                                                                     | Default                                                      |
| -------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `model-value`        | Controlled text                                                          | `string`                                                                                 | `—`                                                          |
| `default-value`      | Initial uncontrolled text                                                | `string`                                                                                 | `''`                                                         |
| `options`            | Suggestions, including groups; unique values become strings on selection | `(AutoCompleteOption \| SelectOptionGroup)[]` / `(query, { signal }) => Array / Promise` | `undefined`                                                  |
| `field-names`        | Map value, label, disabled and other fields                              | `AutoCompleteFieldNames`                                                                 | `—`                                                          |
| `should-open`        | Opening policy; does not filter candidates                               | `(value: string) => boolean`                                                             | `value.length > 0`                                           |
| `filter-option`      | Filter by label; false for remote filtering                              | `AutoCompleteFilterOption`                                                               | Automatic: enabled for arrays, disabled for loader functions |
| `case-sensitive`     | Case-sensitive built-in matching                                         | `boolean`                                                                                | `false`                                                      |
| `popup-container`    | Popup container; same contract as Trigger                                | `PopupContainer`                                                                         | `—`                                                          |
| `trigger-props`      | Trigger configuration; cannot override owned opening and disabled state  | `TriggerProps`                                                                           | `—`                                                          |
| `virtual-list-props` | Enable and configure virtual scrolling                                   | `VirtualListProps`                                                                       | `—`                                                          |
| `size`               | Five sizes; inherit Group / Form / global configuration when unset       | `xs \| sm \| md \| lg \| xl`                                                             | `md`                                                         |
| `variant`            | Input variant; inherits Group when unset                                 | `filled \| outline \| standard`                                                          | `outline`                                                    |
| `disabled`           | Disabled; inherited when unset, explicit false overrides                 | `boolean`                                                                                | `undefined`                                                  |
| `readonly`           | Readonly; focus/copy allowed, suggestions stay closed                    | `boolean`                                                                                | `undefined`                                                  |
| `error`              | Error state; inherits FormItem when unset                                | `boolean`                                                                                | `undefined`                                                  |
| `clearable`          | Allow clearing a nonempty editable value                                 | `boolean`                                                                                | `false`                                                      |
| `placeholder`        | Placeholder or floating hint text                                        | `string`                                                                                 | `—`                                                          |
| `hint`               | Enable Input floating hint                                               | `boolean`                                                                                | `undefined`                                                  |
| `line`               | Show border or underline                                                 | `boolean`                                                                                | `true`                                                       |
| `text-color`         | Instance text color                                                      | `string`                                                                                 | `—`                                                          |
| `focus-color`        | Instance focus color                                                     | `string`                                                                                 | `—`                                                          |
| `blur-color`         | Instance unfocused hint color                                            | `string`                                                                                 | `—`                                                          |
| `enterkeyhint`       | Virtual keyboard action hint                                             | `InputHTMLAttributes['enterKeyHint']`                                                    | `—`                                                          |
| `aria-label`         | Accessible input name                                                    | `string`                                                                                 | `—`                                                          |
| `max-length`         | Same length normalization for typing and selecting                       | `number \| { length: number; errorOnly?: boolean }`                                      | `0`                                                          |
| `show-word-limit`    | Display word count                                                       | `boolean`                                                                                | `false`                                                      |
| `word-length`        | Custom length calculation                                                | `(value: string) => number`                                                              | `—`                                                          |
| `word-slice`         | Custom slicing                                                           | `(value: string, maxLength: number) => string`                                           | `—`                                                          |
| `input-attrs`        | Native input attributes; combobox state is owned by the component        | `Record<string, unknown>`                                                                | `—`                                                          |

### Events

| Event                                     | Arguments                                                     |
| ----------------------------------------- | ------------------------------------------------------------- |
| `update:model-value`                      | `value: string`                                               |
| `input / search / change`                 | `value: string, event: Event`                                 |
| `select`                                  | `value: string, option: AutoCompleteOptionInfo, event: Event` |
| `clear`                                   | `event: Event`                                                |
| `focus / blur`                            | `event: FocusEvent`                                           |
| `dropdown-scroll / dropdown-reach-bottom` | `event: Event`                                                |

Typing: `input → update:modelValue → search`; selection: `update:modelValue → select → change`; clear: `clear → input → update:modelValue → change`. Selecting the same value emits only select. change is a commit on blur, Enter or selection. Input owns typing/focus/clear Form notifications; AutoComplete notifies Form once for suggestion commits. Selection applies maxLength; select.value is the committed string, while option.value retains the original suggestion. clear receives an event, not a string.

### Slots

| Slot              | Description                        |
| ----------------- | ---------------------------------- |
| `option`          | `{ data: AutoCompleteOptionInfo }` |
| `footer`          | Menu footer                        |
| `prefix / suffix` | Input prefix / suffix              |
| `clear-icon`      | `{ clear }`                        |

### Methods

`focus()` / `blur()`

label is text. Use the option slot or an option render function for complex candidates; function/VNode labels are not supported. Arrow keys browse, Enter selects, Escape closes, and Tab retains native focus navigation. Vue useId keeps SSR identifiers stable.

## Type definitions

```ts
import type {
  AutoCompleteProps,
  AutoCompleteInstance,
  AutoCompleteOption,
  AutoCompleteOptionData,
  AutoCompleteOptionInfo,
  AutoCompleteFieldNames,
  AutoCompleteFilterOption,
} from "@cedar-design/ui";
```

## Style variables

| Token                                           | Default                                             |
| ----------------------------------------------- | --------------------------------------------------- |
| `--c-auto-complete-popup-max-height`            | `var(--c-select-popup-max-height)`                  |
| `--c-auto-complete-popup-bg`                    | `var(--c-select-popup-bg)`                          |
| `--c-auto-complete-popup-border-radius`         | `var(--c-select-popup-border-radius)`               |
| `--c-auto-complete-popup-padding-vertical`      | `var(--c-select-popup-padding-vertical)`            |
| `--c-auto-complete-popup-font-size`             | `var(--c-select-popup-font-size)`                   |
| `--c-auto-complete-popup-border-color`          | `var(--c-select-popup-border-color)`                |
| `--c-auto-complete-popup-box-shadow`            | `var(--c-select-popup-box-shadow)`                  |
| `--c-auto-complete-option-height`               | `var(--c-select-popup-option-height)`               |
| `--c-auto-complete-option-font-weight-selected` | `var(--c-select-popup-option-font-weight-selected)` |
| `--c-auto-complete-option-padding-horizontal`   | `var(--c-select-popup-option-padding-horizontal)`   |
| `--c-auto-complete-option-bg-default`           | `var(--c-select-popup-option-bg)`                   |
| `--c-auto-complete-option-bg-hover`             | `var(--c-select-popup-option-bg-hover)`             |
| `--c-auto-complete-option-bg-selected`          | `var(--c-select-popup-option-bg-selected)`          |
| `--c-auto-complete-option-bg-disabled`          | `var(--c-select-popup-option-bg-disabled)`          |
| `--c-auto-complete-option-text-color-default`   | `var(--c-select-popup-option-text-color)`           |
| `--c-auto-complete-option-text-color-hover`     | `var(--c-select-popup-option-text-color-hover)`     |
| `--c-auto-complete-option-text-color-selected`  | `var(--c-select-popup-option-text-color-selected)`  |
| `--c-auto-complete-option-text-color-disabled`  | `var(--c-select-popup-option-text-color-disabled)`  |

Clearing does not emit search or reopen candidates, including when focus returns from a keyboard-focused clear button to the input. The parent controls the value: each rejected clear or selection still emits a change proposal; an accepted candidate selection notifies Form once.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

Suggestions share Select’s list, group, selected and disabled styles. AutoComplete style variables follow the corresponding Select variables by default. In `inline` mode, the list opens below the input and follows scrolling; use `trigger-props` to explicitly change placement or enable automatic flipping. In `popup` mode, candidates use the same full editor surface as Select.

### Public type exports

Root and component entries export `AutoCompleteEmits`、`AutoCompleteSlots`、`AutoCompleteExpose` alongside Props and Instance. Emits are event argument tuples derived from the runtime validators; Expose contains focus/blur.

`case-sensitive` only makes built-in local filtering `case-sensitive`: `ap` matches `Apple` when false, but not when true. It does not require choosing an option or validate the value. A custom `filterOption` takes priority; `filterOption=false` disables local filtering and makes `case-sensitive` irrelevant.

### Migrating strict / Migration

The old `strict` prop is removed. Use `case-sensitive` (`caseSensitive` in TypeScript) instead; boolean meanings and the default false remain unchanged. This removal is marked for the next major release, without a compatibility alias.

### Built-in search fields

`searchFields` / `search-fields` is a readonly `('label' | 'value')[]`, defaulting to `['label']`. Multiple fields use OR matching, case-insensitive by default. `['value', 'label']` searches codes and names; fieldNames maps semantic fields to business fields. An empty array matches no items for a nonempty query. Values are compared as strings; object traversal, object values and pinyin matching require a custom callback. A custom callback takes precedence and decides case handling itself. Remote results use the existing protocol for disabling local filtering. Cascader retains path semantics and checks the configured fields on each path node.

## Configuring the cleared value

`empty-value` / `emptyValue` configures the model value produced by clearing. It accepts a value in the component model type, null, or a zero-argument factory. Omitting it preserves the existing default. Use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on each clear; selected items that cannot be cleared remain. It does not redefine empty values, change Form reset defaults, or treat 0/false as universally empty.
Text and person-ID models remain strings; use an empty string or a business-defined string sentinel.

## Loading options through a function prop

Pass options(query, { signal }) directly; useAsyncData is unnecessary. options still accepts arrays, and an explicit array, including [], takes precedence. The component manages loading, stale-result isolation and cancellation. load-error reports failures, and the instance refresh() method retries. A business loader may accept only query and ignore the second argument.

filterable enables entering a search query. filterOption controls only local matching and never sends requests. With an options loader, remote results are not filtered again by default; with only an array, local matching is enabled by default. Most callers do not need filter-option.

```vue
<c-auto-complete v-model="text" :options="loadSuggestions" />
```

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/avatar.md

<!-- Source: src/avatar/README.en-US.md; locale: en-US; page: /en/components/avatar/ -->

# Avatar

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `color`: Overrides the color.

Example source: src/avatar/__demos__/basic.vue

```vue
<template>
  <c-space align="center" :size="16" wrap>
    <c-avatar>C</c-avatar>
    <c-avatar>CD</c-avatar>
    <c-avatar shape="square">Cedar</c-avatar>
    <c-avatar color="#00bebe">U</c-avatar>
    <c-avatar image-url="/cat.jpg" alt="一只猫" />
  </c-space>
</template>
```

## Appearance and states

### Size and shape comparison

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `shape` | Avatar shape | Size and shape comparison, Style, Hoverable |
| `image-url` | Image URL | Size and shape comparison, Hoverable |
| `alt` | Image alternative text | Size and shape comparison, Hoverable |
| `bordered` | Whether to show a border | Style, Hoverable |
| `size` | Avatar width and height; numbers are px, strings are CSS lengths | Size and shape comparison |
| `color` | Background color | Style |
<!-- demo-config-notes:end -->


Compare space used at each size, then round and square boundaries. Image fitting and fallback remain separate.

Example source: src/avatar/__demos__/shape-size-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const numericSizes = [24, 32, 40, 48, 64] as const

const labels = { 24: 'A', 32: 'B', 40: 'C', 48: 'D', 64: 'E' } as const

const imageSizes = [28, 36, 48, 64, 78] as const

const cssSizes = ['3rem', '2.5em', '48px'] as const
return { numericSizes, labels, imageSizes, cssSizes }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" :size="20">
        <c-space align="flex-end" :size="16" wrap>
          <c-space v-for="size in scene1.numericSizes" :key="size" direction="column" align="center" :size="8">
            <c-avatar :size="size">{{ scene1.labels[size] }}</c-avatar>
            <span class="label">{{ size }}px</span>
          </c-space>
        </c-space>
    
        <c-space align="flex-end" :size="16" wrap>
          <c-space v-for="size in scene1.imageSizes" :key="size" direction="column" align="center" :size="8">
            <c-avatar image-url="/cat.jpg" :alt="`${size}px`" :size="size" />
            <span class="label">{{ size }}px</span>
          </c-space>
        </c-space>
    
        <c-space align="flex-end" :size="16" wrap>
          <c-space v-for="size in scene1.cssSizes" :key="size" direction="column" align="center" :size="8">
            <c-avatar :size="size">Aa</c-avatar>
            <span class="label">{{ size }}</span>
          </c-space>
        </c-space>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="shape">
    <h4><span lang="zh-CN">形状</span><span lang="en-US">shape</span></h4>
    <c-space align="flex-end" :size="16" wrap>
        <c-space direction="column" align="center" :size="8">
          <c-avatar>圆</c-avatar>
          <span class="label">circle</span>
        </c-space>
        <c-space direction="column" align="center" :size="8">
          <c-avatar shape="square">方</c-avatar>
          <span class="label">square</span>
        </c-space>
        <c-space direction="column" align="center" :size="8">
          <c-avatar image-url="/cat.jpg" alt="圆形图片" />
          <span class="label">circle · 图片</span>
        </c-space>
        <c-space direction="column" align="center" :size="8">
          <c-avatar image-url="/cat.jpg" alt="方形图片" shape="square" />
          <span class="label">square · 图片</span>
        </c-space>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
.demo-comparison-case--2 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
</style>
```

### Style

- `color`: Overrides the color.

Example source: src/avatar/__demos__/style.vue

```vue
<template>
  <c-space align="center" :size="16" wrap>
    <c-avatar color="var(--c-color-warning)">火</c-avatar>
    <c-avatar color="var(--c-color-danger)">Cedar</c-avatar>
    <c-avatar color="#00bebe">CD</c-avatar>
    <c-avatar color="#7b61ff" shape="square">A</c-avatar>
    <c-avatar bordered>B</c-avatar>
    <c-avatar bordered border-color="#00bebe" color="#e6fffb">C</c-avatar>
  </c-space>
</template>
```

### Hoverable

Preview configuration: `hoverable`, `image-url="/cat.jpg"`, `alt="悬停放大"`, `shape="square"`.

Example source: src/avatar/__demos__/hoverable.vue

```vue
<template>
  <c-space direction="column" :size="24">
    <c-space align="center" :size="16" wrap>
      <c-avatar hoverable>H</c-avatar>
      <c-avatar hoverable image-url="/cat.jpg" alt="悬停放大" />
      <c-avatar hoverable shape="square">方</c-avatar>
    </c-space>
    <c-avatar-group>
      <c-avatar hoverable image-url="/cat.jpg" alt="用户一" bordered />
      <c-avatar hoverable image-url="/cat2.jpg" alt="用户二" bordered />
      <c-avatar hoverable image-url="/cat.jpg" alt="用户三" bordered />
      <c-avatar hoverable bordered>+2</c-avatar>
    </c-avatar-group>
  </c-space>
</template>
```

## Layout and arrangement

### Group direction and overflow

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `image-url` | Image URL | Group direction and overflow |
| `alt` | Image alternative text | Group direction and overflow |
| `bordered` | Whether to show a border | Group direction and overflow |
| `color` | Background color | Group direction and overflow |
<!-- demo-config-notes:end -->


Compare horizontal and vertical groups, maximum counts, stacking and overflow indicators.

Example source: src/avatar/__demos__/group-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="group">
    <h4><span lang="zh-CN">头像组</span><span lang="en-US">group</span></h4>
    <c-space direction="column" :size="24">
        <c-space direction="column" :size="8">
          <span class="label">默认叠层</span>
          <c-avatar-group>
            <c-avatar image-url="/cat.jpg" alt="用户一" bordered />
            <c-avatar image-url="/cat2.jpg" alt="用户二" bordered />
            <c-avatar image-url="/cat.jpg" alt="用户三" bordered />
            <c-avatar bordered>+2</c-avatar>
          </c-avatar-group>
        </c-space>
    
        <c-space direction="column" :size="8">
          <span class="label">max-count + max-style</span>
          <c-avatar-group
            :max-count="3"
            :size="48"
            :max-style="{
      backgroundColor: '#1d2129',
      color: '#fff'
    }"
          >
            <c-avatar image-url="/cat.jpg" alt="用户一" />
            <c-avatar image-url="/cat2.jpg" alt="用户二" />
            <c-avatar color="#00bebe">A</c-avatar>
            <c-avatar color="#f59e0b">B</c-avatar>
            <c-avatar color="#ef4444">C</c-avatar>
          </c-avatar-group>
        </c-space>
    
        <c-space direction="column" :size="8">
          <span class="label">z-index-ascend</span>
          <c-avatar-group z-index-ascend>
            <c-avatar image-url="/cat.jpg" alt="用户一" />
            <c-avatar image-url="/cat2.jpg" alt="用户二" />
            <c-avatar color="#7b61ff">CD</c-avatar>
          </c-avatar-group>
        </c-space>
    
        <c-space direction="column" :size="8">
          <span class="label">shape="square" · offset="-16"</span>
          <c-avatar-group shape="square" :offset="-16" :size="40">
            <c-avatar image-url="/cat.jpg" alt="用户一" />
            <c-avatar image-url="/cat2.jpg" alt="用户二" />
            <c-avatar color="#00bebe">A</c-avatar>
            <c-avatar color="#7b61ff">B</c-avatar>
          </c-avatar-group>
        </c-space>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="group-vertical">
    <h4><span lang="zh-CN">纵向头像组</span><span lang="en-US">group vertical</span></h4>
    <c-space align="flex-end" :size="32" wrap>
        <c-space direction="column" :size="8">
          <span class="label">offset = -12</span>
          <c-avatar-group vertical :offset="-12">
            <c-avatar image-url="/cat.jpg" alt="用户一" bordered />
            <c-avatar image-url="/cat2.jpg" alt="用户二" bordered />
            <c-avatar image-url="/cat.jpg" alt="用户三" bordered />
            <c-avatar bordered>+2</c-avatar>
          </c-avatar-group>
        </c-space>
        <c-space direction="column" :size="8">
          <span class="label">offset = -20</span>
          <c-avatar-group vertical :offset="-20" :size="48">
            <c-avatar image-url="/cat.jpg" alt="用户一" bordered />
            <c-avatar image-url="/cat2.jpg" alt="用户二" bordered />
            <c-avatar color="#00bebe">A</c-avatar>
          </c-avatar-group>
        </c-space>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
.demo-comparison-case--2 {

.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}

}
</style>
```

## Content and presentation

### Auto Fix

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `image-url` | Image URL | Image, Fit, Fallback |
| `alt` | Image alternative text | Image, Fit, Fallback |
| `size` | Avatar width and height; numbers are px, strings are CSS lengths | Image, Fit, Fallback |
| `shape` | Avatar shape | Auto Fix, Image |
| `auto-fix-font-size` | Whether to shrink long text automatically | Auto Fix |
| `object-fit` | Image fitting mode | Fit |
<!-- demo-config-notes:end -->


Preview configuration: `shape="square"`, `:auto-fix-font-size="false"`, `placeholder="输入更长的文字看缩放"`, `clearable`.

Example source: src/avatar/__demos__/auto-fix.vue

```vue
<template>
  <c-space direction="column" :size="16">
    <c-space align="center" :size="16" wrap>
      <c-space direction="column" align="center" :size="8">
        <c-avatar>{{ text }}</c-avatar>
        <span class="label">圆形 · 自适应</span>
      </c-space>
      <c-space direction="column" align="center" :size="8">
        <c-avatar shape="square">{{ text }}</c-avatar>
        <span class="label">方形 · 自适应</span>
      </c-space>
      <c-space direction="column" align="center" :size="8">
        <c-avatar :auto-fix-font-size="false">{{ text }}</c-avatar>
        <span class="label">关闭自适应</span>
      </c-space>
    </c-space>
    <c-input v-model="text" :style="{ width: '240px' }" placeholder="输入更长的文字看缩放" clearable />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const text = ref('Cedar')
</script>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

### Image

- `size`: Controls the component size.

Example source: src/avatar/__demos__/image.vue

```vue
<template>
  <c-space align="center" :size="16" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="/cat.jpg" alt="一只猫" />
      <span class="label">image-url</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="/cat2.jpg" alt="一只猫" :size="48" shape="square" />
      <span class="label">方形图片</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar :size="48">
        <img src="/cat.jpg" alt="默认插槽中的图片" />
      </c-avatar>
      <span class="label">默认插槽 img</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

### Fit

- `size`: Controls the component size.

Example source: src/avatar/__demos__/fit.vue

```vue
<template>
  <c-space align="flex-end" :size="24" wrap>
    <c-space v-for="fit in fits" :key="fit" direction="column" align="center" :size="8">
      <c-avatar image-url="/cat.jpg" :alt="fit" :object-fit="fit" :size="56" />
      <span class="label">{{ fit }}</span>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
const fits = ['fill', 'contain', 'cover', 'none', 'scale-down'] as const
</script>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

### Fallback

- `size`: Controls the component size.

Example source: src/avatar/__demos__/fallback.vue

```vue
<template>
  <c-space align="flex-end" :size="24" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-avatar lazy image-url="/cat.jpg" loading="/cat2.jpg" alt="懒加载与占位图" :size="48" />
      <span class="label">lazy + loading</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="data:image/png;base64,AA==" error="/cat.jpg" alt="失败时回退到占位图" :size="48" />
      <span class="label">error 图片</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="data:image/png;base64,AA==" alt="失败插槽" :size="48">
        <template #error>NA</template>
      </c-avatar>
      <span class="label">error 插槽</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

## Interaction and control

### Trigger

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `image-url` | Image URL | Trigger |
| `alt` | Image alternative text | Trigger |
| `size` | Avatar width and height; numbers are px, strings are CSS lengths | Trigger |
| `trigger-type` | How the action icon is shown | Trigger |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.

Example source: src/avatar/__demos__/trigger.vue

```vue
<template>
  <c-space align="flex-end" :size="32" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-avatar image-url="/cat.jpg" alt="编辑头像" :size="56" @click="onClick('button')">
        <template #trigger-icon>+</template>
      </c-avatar>
      <span class="label">{{ last === 'button' ? 'click · button' : 'trigger-type="button"' }}</span>
    </c-space>

    <c-space direction="column" align="center" :size="8">
      <c-avatar
        image-url="/cat2.jpg"
        alt="更换头像"
        :size="56"
        trigger-type="overlay"
        @click="onClick('overlay')"
      >
        <template #trigger-icon>+</template>
      </c-avatar>
      <span class="label">{{ last === 'overlay' ? 'click · overlay' : 'trigger-type="overlay"' }}</span>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const last = ref('')

function onClick(type: string) {
  last.value = type
}
</script>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: var(--c-font-size-sm);
}
</style>
```

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| shape | Avatar shape | `circle / square` | `circle` |
| image-url | Image URL | `string` | `-` |
| alt | Image alternative text | `string` | `''` |
| size | Avatar width and height; numbers are px, strings are CSS lengths | `number / string` | `-` |
| auto-fix-font-size | Whether to shrink long text automatically | `boolean` | `true` |
| trigger-type | How the action icon is shown | `button / overlay` | `button` |
| trigger-icon-style | Custom style for the action icon | `CSSProperties` | `-` |
| object-fit | Image fitting mode | `fill / contain / cover / none / scale-down` | `cover` |
| color | Background color | `string` | `-` |
| bordered | Whether to show a border | `boolean` | `false` |
| border-color | Border color | `string` | `-` |
| loading | Placeholder image while loading | `string` | `-` |
| error | Fallback image URL when image loading fails | `string` | `-` |
| lazy | Whether to lazy-load the image | `boolean` | `false` |
| hoverable | Whether to scale on hover | `boolean` | `false` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| click | Emitted when the avatar is clicked | `(event: MouseEvent) => void` |
| load | Emitted when the image loads | `() => void` |
| error | Emitted when image loading fails | `() => void` |

### Slots

| Slot | Description |
| --- | --- |
| default | Text, icon, or loading content for an image |
| error | Fallback content when image loading fails |
| trigger-icon | Action icon on the avatar |

### Methods

No custom public methods.
<!-- same-source-api:end -->

### AvatarGroup Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| shape | Child avatar shape | `circle / square` | `circle` |
| size | Child avatar width and height; numbers are px, strings are CSS lengths | `number / string` | `-` |
| auto-fix-font-size | Whether to shrink child avatar text automatically | `boolean` | `true` |
| max-count | Maximum visible avatars; `0` means unlimited | `number` | `0` |
| z-index-ascend | Use ascending stacking order | `boolean` | `false` |
| max-style | Custom summary avatar style | `CSSProperties` | `-` |
| max-popover-props | Summary Popover props | `PopoverProps` | `-` |
| offset | Overlap offset | `number / string` | `-` |
| vertical | Stack avatars vertically | `boolean` | `false` |

### AvatarGroup Slots

| Slot | Description |
| --- | --- |
| default | Avatar list |

### Type definitions

```ts
import type {
  AvatarGroupInstance,
  AvatarGroupProps,
  AvatarInstance,
  AvatarProps,
  AvatarObjectFit,
  AvatarShape,
  AvatarTriggerType,
} from "@cedar-design/ui";
```

### Style variables

| Variable | Default |
| --- | --- |
| `--c-avatar-size-default` | `40px` |
| `--c-avatar-font-size-text` | `20px` |
| `--c-avatar-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-avatar-text-padding-inline` | `4px` |
| `--c-avatar-bg` | `var(--c-color-fill-4)` |
| `--c-avatar-border-width` | `2px` |
| `--c-avatar-border-color` | `var(--c-sys-color-surface-default)` |
| `--c-avatar-group-item-border` | `var(--c-sys-color-surface-default)` |
| `--c-avatar-group-item-border-width` | `2px` |
| `--c-avatar-group-offset` | `-10px` |
| `--c-avatar-group-popover-item-spacing` | `8px` |
| `--c-avatar-font-weight-text` | `500` |
| `--c-avatar-circle-border-radius` | `50%` |
| `--c-avatar-square-border-radius` | `4px` |
| `--c-avatar-size-trigger-button` | `20px` |
| `--c-avatar-trigger-button-bg` | `var(--c-color-fill-2)` |
| `--c-avatar-trigger-button-bg-hover` | `var(--c-color-fill-3)` |
| `--c-avatar-trigger-overlay-icon` | `var(--c-sys-color-content-on-dark)` |
| `--c-avatar-trigger-overlay-bg` | `color-mix(in srgb, var(--c-color-black) 60%, transparent)` |
| `--c-avatar-trigger-icon-button` | `var(--c-sys-color-content-primary)` |
| `--c-avatar-spacing-trigger-button-right` | `4px` |
| `--c-avatar-spacing-trigger-button-bottom` | `4px` |
| `--c-avatar-size-trigger-icon` | `12px` |
| `--c-avatar-trigger-button-border-radius` | `50%` |
| `--c-avatar-font-size-max-count` | `20px` |
| `--c-avatar-max-count-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-avatar-trigger-overlay-font-size` | `16px` |
| `--c-avatar-hover-transform` | `scale(1.1)` |
| `--c-avatar-motion-duration` | `0.2s` |
| `--c-avatar-z-index-trigger` | `1` |
| `--c-avatar-z-index-overlay` | `0` |
| `--c-avatar-z-index-overlay-hover` | `2` |

Text, summary counts and button trigger icons use the primary content `color` by default. Borders follow the container surface; only icons on dark interaction overlays use `content-on-dark`. The avatar `fill-4` background, button background/hover levels and translucent black overlay remain component visual values. When overriding the avatar background with `color`, also check text contrast and override `text-color` if needed.

### Reduced motion

Built-in CSS transitions follow `prefers-reduced-motion: reduce`. Removing transitions does not change final visibility, selected/expanded state or event semantics. Applications control custom animations inside slots.

---

Document: llms/en-US/components/back-top.md

<!-- Source: src/back-top/README.en-US.md; locale: en-US; page: /en/components/back-top/ -->

# BackTop

Visibility RAF and JS duration/easing interpolation have separate ownership. Old listeners/canceled or consumed frames cannot replay after target replacement/deactivation/disposal. Recheck after custom easing before writing; RAF/cancel/time origin use the target owner window. Retained inactive/disposed commands are inert, activation does not resume old animation. Scoped14/full30 per copy pass using controlled queues/iframe, not native browser/OS proof. Default200ms/API remain; no CSS token added.

A native button that scrolls the page or an explicit container to the top.

## Basic examples

### Basic usage

Example source: src/back-top/__demos__/basic.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。</p>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => scroller"
        :popup-container="false"
        :visible-height="120"
        :right="16"
        :bottom="16"
        aria-label="回到顶部"
      />
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

## Customization and slots

### Custom position

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `target-container` | Scroll target; omitted means page | Custom position |
| `popup-container` | Render target; false renders locally | Custom position |
| `visible-height` | Inclusive scroll threshold in px, numeric strings accepted | Custom position |
| `right` | Right offset; number in px, string accepts CSS units | Custom position |
| `bottom` | Bottom offset; number in px, string accepts CSS units | Custom position |
| `aria-label` | Accessible name | Custom position |
<!-- demo-config-notes:end -->


Example source: src/back-top/__demos__/custom-position.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。</p>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => scroller"
        :popup-container="false"
        :visible-height="120"
        :right="64"
        :bottom="32"
        aria-label="回到顶部"
      />
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

## Interaction and control

### Switch scroll container

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `target-container` | Scroll target; omitted means page | Switch scroll container, Content and events |
| `popup-container` | Render target; false renders locally | Switch scroll container, Content and events |
| `visible-height` | Inclusive scroll threshold in px, numeric strings accepted | Switch scroll container, Content and events |
| `right` | Right offset; number in px, string accepts CSS units | Switch scroll container, Content and events |
| `bottom` | Bottom offset; number in px, string accepts CSS units | Switch scroll container, Content and events |
| `aria-label` | Accessible name | Switch scroll container, Content and events |
<!-- demo-config-notes:end -->


Example source: src/back-top/__demos__/container.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
const second = ref<HTMLElement>()
const useSecond = ref(false)
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。</p>
    <c-button @click="useSecond = !useSecond">切换滚动目标 {{ useSecond ? 'B' : 'A' }}</c-button>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <div ref="second" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">B · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => useSecond ? second : scroller"
        :popup-container="false"
        :visible-height="120"
        :right="16"
        :bottom="16"
        aria-label="回到顶部"
      />
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

### Content and events

Example source: src/back-top/__demos__/custom.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'

const scroller = ref<HTMLElement>()
const clicks = ref(0)
onMounted(() => {
  if (scroller.value) {
    scroller.value.scrollTop = 240
    scroller.value.dispatchEvent(new Event('scroll'))
  }
})
</script>

<template>
  <div class="back-top-demo">
    <p>在面板内滚动，超过 120px 时显示按钮。 {{ '点击次数：' }}{{ clicks }}</p>
    <div class="back-top-demo__frame">
      <div ref="scroller" class="back-top-demo__scroll">
        <p v-for="row in 30" :key="row">A · 滚动内容 {{ row }}</p>
      </div>
      <c-back-top
        :target-container="() => scroller"
        :popup-container="false"
        :visible-height="120"
        :right="16"
        :bottom="16"
        @click="clicks++"
        aria-label="回到顶部"
      >TOP</c-back-top>
    </div>
  </div>
</template>

<style scoped>
.back-top-demo { display: flex; flex-direction: column; gap: 12px; }
.back-top-demo > p { margin: 0; }
.back-top-demo__frame { position: relative; display: flex; gap: 12px; }
.back-top-demo__scroll { flex: 1; min-width: 0; height: 240px; overflow: auto; border: 1px solid #ddd; border-radius: 8px; }
.back-top-demo__scroll p { padding: 8px 12px; margin: 0; }
</style>
```

The examples use isolated local containers. Omit `target-container` to listen to the page, not the nearest scrollable ancestor. A selector that is invalid or missing hides the button; use a reactive getter for a container mounted asynchronously. `popup-container` controls where the button renders, not what scrolls.

## Lifecycle and edge cases

### Scheduling Lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `target-container` | Scroll target; omitted means page | Scheduling Lifecycle |
| `popup-container` | Render target; false renders locally | Scheduling Lifecycle |
| `duration` | Animation duration in ms; 0 is immediate | Scheduling Lifecycle |
| `easing` | Built-in curve or normalized progress function | Scheduling Lifecycle |
<!-- demo-config-notes:end -->


Example source: src/back-top/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { BackTopInstance } from "@cedar-design/ui";
const first = ref<HTMLElement>();
const second = ref<HTMLElement>();
const active = ref(true);
const alternate = ref(false);
let retained: BackTopInstance | undefined;
const capture = (instance: BackTopInstance | null) => {
  if (instance) retained = instance;
};
const lower = () => {
  if (first.value) first.value.scrollTop = 300;
  if (second.value) second.value.scrollTop = 300;
};
</script>
<template>
  <div style="position: relative">
    <c-button @click="lower">Scroll down / 滚动到底部</c-button>
    <c-button @click="alternate = !alternate"
      >Switch target / 切换目标</c-button
    >
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="retained?.scrollToTop()"
      >Retained command / 保留命令</c-button
    >
    <p>
      Start an animation, switch or deactivate before completion. Old work must
      not resume.
    </p>
    <div ref="first" style="height: 100px; overflow: auto">
      <div style="height: 500px">Target A</div>
    </div>
    <div ref="second" style="height: 100px; overflow: auto">
      <div style="height: 500px">Target B</div>
    </div>
    <KeepAlive>
      <c-back-top
        v-if="active"
        :ref="capture"
        :target-container="() => (alternate ? second : first)"
        :popup-container="false"
        :duration="1000"
        easing="linear"
      />
    </KeepAlive>
  </div>
</template>
```

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `target-container` | Scroll target; omitted means page | `string \| HTMLElement \| (() => HTMLElement \| null \| undefined)` | `—` |
| `popup-container` | Render target; false renders locally | `string \| HTMLElement \| false` | `body` |
| `visible-height` | Inclusive scroll threshold in px, numeric strings accepted | `number \| string` | `200` |
| `duration` | Animation duration in ms; 0 is immediate | `number` | `200` |
| `easing` | Built-in curve or normalized progress function | `'linear' \| 'quartOut' \| 'easeInOutCubic' \| ((progress: number) => number)` | `'quartOut'` |
| `right` | Right offset; number in px, string accepts CSS units | `number \| string` | `—` |
| `bottom` | Bottom offset; number in px, string accepts CSS units | `number \| string` | `—` |
| `elevation` | Shadow level; true uses level 2 | `boolean \| number` | `true` |
| `aria-label` | Accessible name | `string` | `'Back to top'` |

When `popup-container=false`, the button is positioned absolutely; give its containing block `position: relative`. Repeated clicks replace the previous animation; changing target, deactivation and unmount cancel queued work. Reduced-motion preference skips animation. Horizontal scroll position is preserved.

### Events / slots / methods

- `click(event: MouseEvent)`: emitted once per activation.
- Default slot: noninteractive text or icons. The root is already a native button; do not nest another Button or link.
- `scrollToTop()`: scrolls the current target without emitting an additional click.
- Keyboard: Tab focuses the visible button; Enter / Space activates it. Hidden buttons are not focusable.

### Types

```ts
import type { BackTopProps, BackTopInstance, BackTopTarget, BackTopEasing } from '@cedar-design/ui'
```

### Style variables

| Token | Default |
| --- | --- |
| `--c-back-top-right` | `40px` |
| `--c-back-top-bottom` | `40px` |
| `--c-back-top-button-size` | `var(--c-sys-control-touch-target)` |
| `--c-back-top-button-border-radius` | `50%` |
| `--c-back-top-font-size` | `var(--c-sys-font-size-md)` |
| `--c-back-top-icon-size` | `20px` |
| `--c-back-top-background` | `var(--c-sys-color-surface-raised)` |
| `--c-back-top-text-color` | `var(--c-sys-color-content-brand)` |
| `--c-back-top-hover-background` | `var(--c-sys-color-state-hover)` |
| `--c-back-top-focus-color` | `var(--c-sys-color-content-brand)` |
| `--c-back-top-focus-width` | `2px` |
| `--c-back-top-focus-offset` | `2px` |
| `--c-back-top-z-index` | `var(--c-z-index-local-sticky)` |

Pre-release migration: Cedar `margin-right/bottom` → `right/bottom`, `button-size-width` → `button-size`, `button-size-font/icon` → `font-size/icon-size`, `button-bg/bg-hover/text-color` → `background/hover-background/text-color` (all with the component prefix). Maple duration is now 200ms; default target is the page. Legacy arbitrary BTween curve names are replaced with the documented presets or a function. No aliases remain.

---

Document: llms/en-US/components/badge.md

<!-- Source: src/badge/README.en-US.md; locale: en-US; page: /en/components/badge/ -->

# Badge

The same scenarios, parameters and interactions as Cedar. Only component prefixes differ; themes and site shells remain independent.

## Basic examples

### Basic usage

Badges use a red background and white text by default.

Example source: src/badge/__demos__/basic.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge :content="9"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="9" dot
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge
      ><template #content><span aria-label="New activity">!</span></template
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ></c-space
  >
</template>
```

## Appearance and states

### Statuses and colors

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Badge content | Statuses and colors, Appearance configuration comparison |
| `status` | Semantic status | Statuses and colors |
| `mode` | Layout mode | Statuses and colors |
| `description` | Fallback description text | Statuses and colors |
| `color` | Custom color; outline uses it for border and text | Statuses and colors |
| `text-color` | Content text color | Statuses and colors |
<!-- demo-config-notes:end -->


Example source: src/badge/__demos__/color.vue

```vue
<script setup lang="ts">
const statuses = [
  'default',
  'primary',
  'secondary',
  'tertiary',
  'info',
  'success',
  'warning',
  'danger',
] as const
</script>

<template>
  <c-space direction="column">
    <c-space wrap
      ><c-badge
        v-for="status in statuses"
        :key="status"
        :status="status"
        mode="inline"
        :description="status"
        :content="1"
    /></c-space>
    <c-space wrap
      ><c-badge v-for="status in statuses" :key="status" :status="status" :content="status"
    /></c-space>
    <c-space wrap
      ><c-badge color="#7816ff" text-color="#ffffff" content="Purple" /><c-badge
        color="#005f73"
        text-color="#ffffff"
        content="Teal"
    /></c-space>
  </c-space>
</template>
```

### Appearance configuration comparison

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/badge/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({
  variant: "default",
  status: "default",
  size: "md",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["default","outline"]},{"name":"status","values":["default","primary","secondary","tertiary","info","success","warning","danger"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'outline', value: 'outline' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'secondary', value: 'secondary' },
            { label: 'tertiary', value: 'tertiary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-badge :content="1000" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }" />
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Layout and arrangement

### Positions and offsets

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `position` | Physical corner or left/right midpoint inside the host box, default top-right. Only used in floating mode; RTL does not mirror it | Positions and offsets |
| `content` | Badge content | Positions and offsets |
| `dot` | Display a dot | Positions and offsets |
| `offset-x` | Horizontal offset; ignored in inline mode | Positions and offsets |
| `offset-y` | Vertical offset | Positions and offsets |
| `mode` | Layout mode | Positions and offsets |
<!-- demo-config-notes:end -->


Example source: src/badge/__demos__/position.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const offset = ref(0)
const dot = ref(false)
const positions = ['top-right', 'top-left', 'bottom-right', 'bottom-left', 'left', 'right'] as const
const inlinePositions = ['start', 'end'] as const
</script>

<template>
  <c-space direction="column" :size="24">
    <c-space wrap
      ><c-button @click="offset++">Offset +1</c-button><c-button @click="offset--">Offset -1</c-button
      ><c-button @click="offset = 0">Reset</c-button><c-switch v-model="dot" aria-label="Toggle dot"
    /></c-space>
    <output aria-live="polite">Offset: {{ offset }}px</output>
    <c-space wrap :size="32"
      ><c-badge
        v-for="position in positions"
        :key="position"
        :position="position"
        :content="100"
        :dot="dot"
        :offset-x="offset"
        :offset-y="offset"
        ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor">{{
          position
        }}</span></c-badge
      ></c-space
    >
    <c-space wrap :size="24"
      ><c-badge
        v-for="position in inlinePositions"
        :key="position"
        mode="inline"
        :inline-position="position"
        :content="9"
        :dot="dot"
        :offset-y="offset"
        :description="position"
    /></c-space>
  </c-space>
</template>
```

## Content and presentation

### Inline and standalone

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Badge content | Inline and standalone, Dot badges, Maximum and zero |
| `dot` | Display a dot | Inline and standalone, Dot badges, Show and hide |
| `description` | Fallback description text | Inline and standalone, Show and hide |
| `show-zero` | Show numeric zero | Maximum and zero, Show and hide |
| `mode` | Layout mode | Inline and standalone |
| `inline-position` | Inline badge at the logical start or end of the host content, default end. Only used in inline mode | Inline and standalone |
<!-- demo-config-notes:end -->


Example source: src/badge/__demos__/inline.vue

```vue
<script setup lang="ts">
const positions = ['start', 'end'] as const
</script>

<template>
  <c-space direction="column" :size="16">
    <c-space wrap><c-badge :content="1000" /><c-badge :content="1000" dot /></c-space>
    <c-space v-for="position in positions" :key="position" wrap>
      <c-badge mode="inline" :inline-position="position" :content="9" description="Messages" />
      <c-badge mode="inline" :inline-position="position" dot :content="9" description="Messages" />
    </c-space>
  </c-space>
</template>
```

### Dot badges

Example source: src/badge/__demos__/dot.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge dot :content="1"
      ><span
        style="
          display: inline-block;
          padding: 12px;
          border: 1px solid currentColor;
          border-radius: 4px;
        "
        >Inbox</span
      ></c-badge
    ><c-badge dot :content="1" :offset-x="6" :offset-y="-2"
      ><c-link href="#" @click.prevent>Messages</c-link></c-badge
    ></c-space
  >
</template>
```

### Maximum and zero

Example source: src/badge/__demos__/max.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge :content="0"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="0" show-zero
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="100" :max="10"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="100"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge :content="1000" :max="999"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ></c-space
  >
</template>
```

### Show and hide

Example source: src/badge/__demos__/show.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const show = ref(true)
const content = ref(1)
</script>

<template>
  <c-space direction="column">
    <c-space wrap
      ><c-switch v-model="show" aria-label="Show badge" /><c-button @click="content++">Add</c-button
      ><c-button @click="content = Math.max(0, content - 1)">Subtract</c-button></c-space
    >
    <c-badge :content="0" :show="show" show-zero description="show-zero true" />
    <c-badge :content="0" :show="show" :show-zero="false" description="show-zero false" />
    <c-badge :content="content" :show="show" description="Messages" />
    <c-badge :content="content" :show="show" dot description="Activity" />
  </c-space>
</template>
```

## Customization and slots

### Custom content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Badge content | Custom content |
| `mode` | Layout mode | Custom content |
| `inline-position` | Inline badge at the logical start or end of the host content, default end. Only used in inline mode | Custom content |
<!-- demo-config-notes:end -->


Example source: src/badge/__demos__/content.vue

```vue
<template>
  <c-space wrap :size="24"
    ><c-badge content="NEW"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge content="HOT" mode="inline" inline-position="start"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ><c-badge content="HOT" mode="inline" inline-position="end"
      ><span style="display: inline-block; padding: 12px; border: 1px solid currentColor; border-radius: 4px"
        >Inbox</span
      ></c-badge
    ></c-space
  >
</template>
```

## API

<!-- same-source-api:start -->
### Props

| Parameter | Description | Type | Default |
| --------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------- | :---------: |
| description | Fallback description text | `string` | `-` |
| content | Badge content | `number \| string` | `-` |
| max | Maximum displayed numeric badge value. Numeric content above this value is shown as `${max}+`. | `number` | `99` |
| dot | Display a dot | `boolean` | `false` |
| offset-x | Horizontal offset; ignored in inline mode | `number` | `0` |
| offset-y | Vertical offset | `number` | `0` |
| color | Custom color; outline uses it for border and text | `string` | `-` |
| text-color | Content text color | `string` | `-` |
| mode | Layout mode | `'floating' \| 'inline'` | `floating` |
| position | Physical corner or left/right midpoint inside the host box, default top-right. Only used in floating mode; RTL does not mirror it | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left' \| 'left' \| 'right'` | `top-right` |
| inline-position | Inline badge at the logical start or end of the host content, default end. Only used in inline mode | `'start' \| 'end'` | `end` |
| size | Size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `md` |
| status | Semantic status | `SemanticStatus` | `danger` |
| show | Show the badge | `boolean` | `true` |
| show-zero | Show numeric zero | `boolean` | `false` |
| variant | Appearance | `'outline' \| 'default'` | `default` |

### Events

No component-specific events.

### Slots

| Slot | Description | Arguments |
| ------- | ---------------- | ---- |
| default | Fallback description text | - |
| content | Content displayed inside the badge | - |

### Methods

No public methods.

### Platform notes

Props and slots match across platforms. Without a default slot and with an empty description, the badge renders independently inline. Omitting content displays a dot. Each library reads text direction from its own configuration and supplies its own theme colors and CSS prefix.
<!-- same-source-api:end -->

### Style variables

The following CSS variables support customization with [StyleProvider](#/en-US/style-provider).

| Variable | Default |
| --- | --- |
| `--c-badge-font-weight` | `var(--c-sys-font-weight-medium)` |
| `--c-badge-description-size-xs-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-description-size-sm-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-description-size-md-font-size` | `var(--c-sys-font-size-md)` |
| `--c-badge-description-size-lg-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-badge-description-size-xl-font-size` | `var(--c-sys-font-size-xl)` |
| `--c-badge-description-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-badge-size-xs-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-size-sm-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-size-md-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-badge-size-lg-font-size` | `var(--c-sys-font-size-md)` |
| `--c-badge-size-xl-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-badge-size-xs-scale` | `0.6667` |
| `--c-badge-size-sm-scale` | `0.8333` |
| `--c-badge-size-md-scale` | `1` |
| `--c-badge-size-lg-scale` | `1` |
| `--c-badge-size-xl-scale` | `1` |
| `--c-badge-size-xs-dot-width` | `4px` |
| `--c-badge-size-sm-dot-width` | `5px` |
| `--c-badge-size-md-dot-width` | `6px` |
| `--c-badge-size-lg-dot-width` | `7px` |
| `--c-badge-size-xl-dot-width` | `8px` |
| `--c-badge-size-xs-dot-height` | `4px` |
| `--c-badge-size-sm-dot-height` | `5px` |
| `--c-badge-size-md-dot-height` | `6px` |
| `--c-badge-size-lg-dot-height` | `7px` |
| `--c-badge-size-xl-dot-height` | `8px` |
| `--c-badge-size-xs-space` | `0px` |
| `--c-badge-size-sm-space` | `var(--c-sys-space-1)` |
| `--c-badge-size-md-space` | `var(--c-sys-space-3)` |
| `--c-badge-size-lg-space` | `var(--c-sys-space-3)` |
| `--c-badge-size-xl-space` | `var(--c-sys-space-4)` |
| `--c-badge-size-xs-padding` | `0 var(--c-sys-space-3)` |
| `--c-badge-size-sm-padding` | `0 var(--c-sys-space-3)` |
| `--c-badge-size-md-padding` | `0 var(--c-sys-space-4)` |
| `--c-badge-size-lg-padding` | `0 var(--c-sys-space-4)` |
| `--c-badge-size-xl-padding` | `0 10px` |
| `--c-badge-size-xs-height` | `20px` |
| `--c-badge-size-sm-height` | `20px` |
| `--c-badge-size-md-height` | `24px` |
| `--c-badge-size-lg-height` | `28px` |
| `--c-badge-size-xl-height` | `32px` |
| `--c-badge-size-xs-border-radius` | `20px` |
| `--c-badge-size-sm-border-radius` | `20px` |
| `--c-badge-size-md-border-radius` | `24px` |
| `--c-badge-size-lg-border-radius` | `28px` |
| `--c-badge-size-xl-border-radius` | `32px` |
| `--c-badge-bg-color` | `rgb(var(--c-danger-7))` |
| `--c-badge-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-default-bg-color` | `#e0e0e0` |
| `--c-badge-status-default-text-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-badge-status-info-bg-color` | `var(--c-sys-color-status-info)` |
| `--c-badge-status-info-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-success-bg-color` | `var(--c-sys-color-status-success)` |
| `--c-badge-status-success-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-warning-bg-color` | `var(--c-sys-color-status-warning)` |
| `--c-badge-status-warning-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-danger-bg-color` | `rgb(var(--c-danger-7))` |
| `--c-badge-status-danger-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-primary-bg-color` | `var(--c-sys-color-action-primary)` |
| `--c-badge-status-primary-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-secondary-bg-color` | `rgb(var(--c-gray-6))` |
| `--c-badge-status-secondary-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-status-tertiary-bg-color` | `rgb(var(--c-gray-7))` |
| `--c-badge-status-tertiary-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-badge-variant-outline-bg-color` | `transparent` |
| `--c-badge-variant-outline-text-color` | `var(--c-sys-color-content-danger)` |
| `--c-badge-variant-outline-status-info-text-color` | `var(--c-sys-color-content-info)` |
| `--c-badge-variant-outline-status-success-text-color` | `var(--c-sys-color-content-success)` |
| `--c-badge-variant-outline-status-warning-text-color` | `var(--c-sys-color-content-warning)` |
| `--c-badge-variant-outline-status-danger-text-color` | `var(--c-sys-color-content-danger)` |
| `--c-badge-variant-outline-status-primary-text-color` | `var(--c-sys-color-content-brand)` |
| `--c-badge-variant-outline-status-default-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-badge-variant-outline-status-secondary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-badge-variant-outline-status-tertiary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-badge-border-color` | `var(--c-sys-color-surface-default)` |
| `--c-badge-offset` | `2px` |
| `--c-badge-ring-width` | `2px` |

Filled badge text follows Button: primary, info, success, warning, danger and secondary use `content-on-dark`; tertiary uses `content-on-dark` in light mode and `content-on-bright` in dark mode. Default notification badges use red backgrounds and white text; the neutral background remains `#e0e0e0`.

Colored outline text and borders follow Button, using the matching `content-brand`, `content-info`, `content-success`, `content-warning` and `content-danger` semantic roles; secondary and tertiary outlines use `content-secondary` for readability. `variant-outline-bg-color` works for every status and defaults to transparent. The `color` prop overrides outline text and border; `text-color` overrides text further. Both preserve control through the background variable. Recheck contrast after customizing foreground or background.

### Type definitions

The component exports the following types

```ts
import type { BadgeInstance } from '@cedar-design/ui'
```

### Color override boundaries

The bg-color fallback and danger fill use red backgrounds with white text: danger level 7 in light mode and level 4 in dark mode. Fixed neutral light gray and secondary/tertiary gray levels are intentional component colors. Override the border-color isolation ring to match the host surface. Callers must ensure contrast for custom color/text-color values.

---

Document: llms/en-US/components/breadcrumb.md

<!-- Source: src/breadcrumb/README.en-US.md; locale: en-US; page: /en/components/breadcrumb/ -->

# Breadcrumb

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/breadcrumb/__demos__/basic.vue

```vue
<template>
  <c-breadcrumb>
    <c-breadcrumb-item>Home</c-breadcrumb-item>
    <c-breadcrumb-item>Channel</c-breadcrumb-item>
    <c-breadcrumb-item>News</c-breadcrumb-item>
  </c-breadcrumb>
</template>

<script lang="ts">
</script>
```

## Content and presentation

### Routes

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `routes` | Route list | Routes, Droplist, Max Count |
| `max-count` | Maximum ordinary breadcrumb items, excluding the overflow item; 0 means unlimited | Max Count |
<!-- demo-config-notes:end -->


Preview configuration: `:routes="routes"`, `:href="paths.join('/')"`.

Example source: src/breadcrumb/__demos__/routes.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb :routes="routes" @click.prevent />
    <c-breadcrumb :routes="routes">
      <template #item-render="{ route, routes, paths }">
        <span v-if="route === routes[routes.length - 1]">{{ route.label }}</span>
        <c-link v-else :href="paths.join('/')" @click.prevent>
          {{ route.label }}
        </c-link>
      </template>
    </c-breadcrumb>
    <c-breadcrumb :routes="routes">
      <template #item-render="{ route, routes }">
        <span v-if="route === routes[routes.length - 1]">{{ route.label }}</span>
        <RouterLink v-else :to="route.to">
          {{ route.label }}
        </RouterLink>
      </template>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
import { RouterLink } from 'vue-router'

export default {
  components: { RouterLink },
  setup() {
    const routes = [
      {
        path: '/',
        to: { query: { breadcrumb: 'home' } },
        label: 'Home',
      },
      {
        path: '/channel',
        to: { query: { breadcrumb: 'channel' } },
        label: 'Channel',
      },
      {
        path: '/news',
        to: { query: { breadcrumb: 'news' } },
        label: 'News',
      },
    ]
    return { routes }
  },
}
</script>
```

### Droplist

Preview configuration: `:routes="routes"`, `:droplist="droplist"`.

Example source: src/breadcrumb/__demos__/droplist.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb :routes="routes" @click.prevent />
    <c-breadcrumb>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item :droplist="droplist"> Channel </c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>
        <template #droplist>
          <c-menu-option>Option 1</c-menu-option>
          <c-menu-option>Option 2</c-menu-option>
          <c-menu-option>Option 3</c-menu-option>
        </template>
        Channel
      </c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
export default {
  setup() {
    const routes = [
      {
        path: '/',
        label: 'Home',
      },
      {
        path: '/channel',
        label: 'Channel',
        children: [
          { path: '/goods', label: 'Goods' },
          { path: '/wallet', label: 'Wallet' },
        ],
      },
      {
        path: '/news',
        label: 'News',
      },
    ]
    const droplist = [
      {
        path: '/goods',
        label: 'Goods',
      },
      {
        path: '/wallet',
        label: 'Wallet',
      },
    ]
    return { routes, droplist }
  },
}
</script>
```

### Max Count

Preview configuration: `:max-count="3"`, `:routes="maxRoutes"`, `:trigger="['hover', 'focus', 'click']"`, `:content="omittedItems.map((item) => item.label).join(' / ')"`.

Example source: src/breadcrumb/__demos__/max-count.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb :max-count="3">
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Sub Home</c-breadcrumb-item>
      <c-breadcrumb-item>All Channel</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
      <c-breadcrumb-item>Post</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb :routes="maxRoutes" :max-count="3" @click.prevent>
      <template #more-icon="{ omittedItems }">
        <c-tooltip :trigger="['hover', 'focus', 'click']" :content="omittedItems.map((item) => item.label).join(' / ')">
          <c-icon-more />
        </c-tooltip>
      </template>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
export default {
  setup() {
    const maxRoutes = [
      { path: '/', label: 'Home' },
      { path: '/sub-home', label: 'Sub Home' },
      { path: '/all-channel', label: 'All Channel' },
      { path: '/channel', label: 'Channel' },
      { path: '/news', label: 'News' },
      { path: '/post', label: 'Post' },
    ]
    return { maxRoutes }
  },
}
</script>
```

### Link

Preview configuration: `href="#/home"`, `href="#/channel"`.

Example source: src/breadcrumb/__demos__/link.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const lastAction = ref('尚未操作')
const record = (label: string) => { lastAction.value = `已选择 ${label}` }
</script>

<template>
  <c-space direction="column">
    <div>纯文本：仅展示路径</div>
    <c-breadcrumb>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <div>链接：悬停或聚焦查看反馈</div>
    <c-breadcrumb>
      <c-breadcrumb-item href="#/home" @click.prevent="record('Home')">Home</c-breadcrumb-item>
      <c-breadcrumb-item href="#/channel" @click.prevent="record('Channel')">Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <div>点击操作：支持 Enter / 空格</div>
    <c-breadcrumb>
      <c-breadcrumb-item @click="record('Home')">Home</c-breadcrumb-item>
      <c-breadcrumb-item @click="record('Channel')">Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <span role="status">{{ lastAction }}</span>
  </c-space>
</template>
```

## Customization and slots

### Custom Split

Preview configuration: `separator="~"`, `separator="->"`.

Example source: src/breadcrumb/__demos__/custom-split.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb>
      <template #separator>
        <c-icon-oblique-line />
      </template>
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb separator="~">
      <c-breadcrumb-item>Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb>
      <template #separator>
        <c-icon-oblique-line />
      </template>
      <c-breadcrumb-item separator="->">Home</c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
</script>
```

### Custom Icon

Example source: src/breadcrumb/__demos__/custom-icon.vue

```vue
<template>
  <c-space direction="column">
    <c-breadcrumb>
      <c-breadcrumb-item>
        <c-icon-home />
      </c-breadcrumb-item>
      <c-breadcrumb-item>Channel</c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
    <c-breadcrumb>
      <c-breadcrumb-item>
        <c-icon-home />
      </c-breadcrumb-item>
      <c-breadcrumb-item>
        <c-icon-link />
        Channel
      </c-breadcrumb-item>
      <c-breadcrumb-item>News</c-breadcrumb-item>
    </c-breadcrumb>
  </c-space>
</template>

<script lang="ts">
</script>
```

## API

### Breadcrumb Props

| Prop | Description | Type | Default |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------ |
| max-count | Maximum ordinary breadcrumb items, excluding the overflow item; 0 means unlimited | `number` | `0` |
| routes | Route list | `BreadcrumbRoute[]` | `-` |
| separator | Separator text | `string \| number` | `/` |

### Breadcrumb Slots

| Slot | Description | Arguments |
| ----------- | ---------------------------------- | --------------------------------------------------------------------------- |
| more-icon | Custom overflow icon | `omittedItems` `count` `start` `end` |
| item-render | Custom breadcrumb rendering when routes is provided | `route:BreadcrumbRoute`<br/>`routes:BreadcrumbRoute[]`<br/>`paths:string[]` |
| separator | Custom separator | `-` |

### BreadcrumbItem Props

| Prop | Description | Type | Default |
| -------------- | ------------ | ----------------------------- | ------ |
| separator | Separator text | `string \| number` | `-` |
| href | Link URL | `string` | `-` |
| droplist | Dropdown menu content | `BreadcrumbRoute['children']` | `-` |
| dropdown-props | Props passed to Menu | `MenuProps` | `-` |

### BreadcrumbItem Events

| Event | Description | Arguments |
| ------ | -------- | -------------- |
| click | Click event; omitted items do not emit it | `event: MouseEvent` |
| select | Fired when a built-in dropdown item is selected | `route: BreadcrumbRoute, event?: Event` |

### BreadcrumbItem Slots

| Slot | Description | Arguments |
| --------- | -------------- | ---- |
| droplist | Custom dropdown menu | `-` |
| separator | Custom separator | `-` |

### BreadcrumbRoute

| Parameter | Description | Type | Default |
| -------- | ------------------------- | ------------------------------ | ------ |
| label | Breadcrumb label | `string` | `-` |
| path | Navigation path (`href` on the `a` element) | `string` |
| children | Dropdown menu items | `{label:string,path:string}[]` | `-` |

## Type definitions

The component exports the following types

```ts
import type { BreadcrumbProps, BreadcrumbItemProps, BreadcrumbRoute } from '@cedar-design/ui'
```

## Shared implementation and platform boundaries

Breadcrumb and BreadcrumbItem are maintained as local copies in Cedar / Maple. Component bodies, props, context, types, key styles and paired tests are checked by `design-ui/bin/copied-components-check.mjs`. Each library supplies its own icons, installation entry, menu implementation and theme tokens.

- A nonempty `routes` array takes precedence over the default slot; an empty array falls back to the slot. Default route rendering links all items except the last, which has `aria-current="page"`. `item-render` controls links itself.
- Separator precedence: child slot → child prop → parent slot → parent prop. `0` and an empty string are supported.
- `max-count` preserves the existing boundary: collapsing occurs only when the total exceeds `max-count + 1`. It keeps the first and trailing items. The overflow position does not trigger omitted items’ clicks, links or dropdowns.
- Built-in dropdown selection emits `select(route, event)`. Indices and separators update with dynamic insertion, removal, reordering and SSR.
- Cedar adds a `__content` wrapper for item content; attributes fall through to it. Maple retains its existing theme variables through token mappings.

---

Document: llms/en-US/components/button.md

<!-- Source: src/button/README.en-US.md; locale: en-US; page: /en/components/button/ -->

# Button

Both libraries use the same implementation and examples; package prefixes, themes and registration stay local.

## Basic examples

### Eight statuses

Example source: src/button/__demos__/basic.vue

```vue
<script setup lang="ts">
const statuses = [
  "default",
  "primary",
  "secondary",
  "tertiary",
  "info",
  "success",
  "warning",
  "danger",
] as const;
</script>
<template>
  <c-space wrap size="12px">
    <c-button v-for="status in statuses" :key="status" :status="status">{{
      status
    }}</c-button>
  </c-space>
</template>
```

## Appearance and states

### Four variants

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `variant` | Appearance; inherits group, otherwise default | Four variants, Colors, ripple and elevation |
| `size` | Size; inherits group, otherwise md | Four variants, Five sizes |
| `status` | Semantic color; inherits group, otherwise default | Four variants |
| `disabled` | Disabled; inherits group, explicit false overrides | Disabled buttons and links |
| `component` | Root tag; link attributes fall through | Disabled buttons and links |
| `loading` | Loading; blocks activation and navigation | Disabled buttons and links |
<!-- demo-config-notes:end -->


The `default` variant uses white text for primary, info, success, warning, danger and secondary solid fills.

Example source: src/button/__demos__/variants.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";

const variant = ref("default");
const size = ref("md");
const background = ref("navy");
const variants = ["default", "text", "outline", "tonal"];
const sizes = ["xs", "sm", "md", "lg", "xl"];
const statuses = [
  "default",
  "primary",
  "secondary",
  "tertiary",
  "info",
  "success",
  "warning",
  "danger",
];
const backgrounds = [
  { label: "Navy / 深蓝", value: "navy", color: "#17224B" },
  { label: "White / 白色", value: "light", color: "#FFFFFF" },
  { label: "Light gray / 浅灰", value: "muted", color: "#F5F5F5" },
  { label: "Dark gray / 深灰", value: "dark", color: "#252525" },
];
const cardBackground = computed(
  () => backgrounds.find((item) => item.value === background.value)?.color,
);
</script>
<template>
  <c-space direction="column" block align="stretch" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Variant" field="variant">
        <c-radio-group
          v-model="variant"
          :options="variants"
          aria-label="Button variant"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          :options="sizes"
          aria-label="Button size"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Background" field="background">
        <c-radio-group
          v-model="background"
          :options="backgrounds"
          aria-label="Button background"
          variant="button"
        />
      </c-form-item>
    </c-form>
    <c-card
      class="button-variant-card"
      :data-background="background"
      :elevation="false"
      :style="{ '--c-card-background': cardBackground }"
    >
      <c-space wrap>
        <c-button
          v-for="status in statuses"
          :key="status"
          :status="status"
          :variant="variant"
          :size="size"
          >{{ status }}</c-button
        >
      </c-space>
    </c-card>
  </c-space>
</template>
```

### Five sizes

Horizontal buttons and inputs of the same size share the default height and font size within each platform. Cedar heights are 24/28/32/36/44px; Maple heights are 32/40/48/56/64px. Horizontal button padding is 8/12/16/20/24px per side, with a 6px icon-label gap. Stacked buttons keep their separate content-based height. Component-level overrides remain independent.

Example source: src/button/__demos__/size.vue

```vue
<script setup lang="ts">
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space v-for="size in sizes" :key="size" align="center" wrap :size="12">
      <span>{{ size }}</span>
      <c-input
        :size="size"
        :aria-label="`Input ${size}`"
        placeholder="Input"
        style="width: 140px"
      />
      <c-button :size="size">Button</c-button>
      <c-button :size="size"
        ><template #icon><c-icon-search /></template>Search</c-button
      >
    </c-space>
  </c-space>
</template>
```

### Disabled buttons and links

Example source: src/button/__demos__/disabled.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const clicks = ref(0);
</script>
<template>
  <c-space wrap size="12px">
    <c-button disabled @click="clicks++">Disabled button</c-button>
    <c-button
      component="a"
      href="#blocked-button-link"
      disabled
      @click="clicks++"
      >Disabled link</c-button
    >
    <c-button
      component="a"
      href="#blocked-button-link"
      loading
      @click="clicks++"
      >Loading link</c-button
    >
  </c-space>
  <p aria-live="polite">Blocked clicks: {{ clicks }}</p>
</template>
```

### Colors, ripple and elevation

Example source: src/button/__demos__/custom-color.vue

```vue
<template>
  <c-space wrap size="12px">
    <c-button color="#6750a4" text-color="white">Custom filled</c-button>
    <c-button
      color="linear-gradient(to bottom right, #6750a4, #d0bcff)"
      text-color="white"
      >Gradient</c-button
    >
    <c-button color="#6750a4" variant="text">Custom text</c-button>
    <c-button color="#6750a4" variant="outline">Custom outline</c-button>
    <c-button color="#6750a4" variant="tonal">Custom tonal</c-button>
  </c-space>
</template>
```

## Icons and layout

### Icons and label layouts

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Semantic color; inherits group, otherwise default | Icons and label layouts |
| `variant` | Appearance; inherits group, otherwise default | Icons and label layouts |
| `size` | Size; inherits group, otherwise md | Icons and label layouts |
| `stacked` | Stack icon and text; inherits group when omitted | Icons and label layouts |
| `round` | Round button | Icons and label layouts |
| `block` | Full available width | Block buttons |
<!-- demo-config-notes:end -->


Use built-in icons to compare icon-only, inline and stacked labels across four variants and five sizes. Stacked buttons grow with content and keep at least 8px of top and bottom padding. Omit the default slot for icon-only buttons; round controls shape and stacked controls label layout.

Example source: src/button/__demos__/icons.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["default", "text", "outline", "tonal"] as const;
const layouts = ["icon", "inline", "stacked"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("tonal");
const items = [
  { status: "default", icon: "plus", label: "Add" },
  { status: "primary", icon: "reply", label: "Reply" },
  { status: "info", icon: "info-circle", label: "Info" },
  { status: "success", icon: "check", label: "Confirm" },
  { status: "warning", icon: "delete", label: "Delete" },
  { status: "danger", icon: "close", label: "Close" },
] as const;
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Variant" field="variant">
        <c-radio-group
          v-model="variant"
          :options="variants"
          aria-label="Icon button variant"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          :options="sizes"
          aria-label="Icon button size"
          variant="button"
        />
      </c-form-item>
    </c-form>
    <c-space
      v-for="layout in layouts"
      :key="layout"
      direction="column"
      :size="8"
    >
      <span>{{
        layout === "icon"
          ? "Icon only / 纯图标"
          : layout === "inline"
            ? "Icon and text / 横排图文"
            : "Stacked / 上下堆叠"
      }}</span>
      <c-space wrap>
        <c-button
          v-for="item in items"
          :key="item.label"
          :status="item.status"
          :variant="variant"
          :size="size"
          :stacked="layout === 'stacked'"
          :round="layout === 'icon'"
          :aria-label="item.label"
        >
          <template #icon>
            <c-icon-plus v-if="item.icon === 'plus'" />
            <c-icon-reply v-else-if="item.icon === 'reply'" />
            <c-icon-info-circle v-else-if="item.icon === 'info-circle'" />
            <c-icon-check v-else-if="item.icon === 'check'" />
            <c-icon-delete v-else-if="item.icon === 'delete'" />
            <c-icon-close v-else-if="item.icon === 'close'" />
          </template>
          <template v-if="layout !== 'icon'" #default>{{
            item.label
          }}</template>
        </c-button>
      </c-space>
    </c-space>
  </c-space>
</template>
```

### Block buttons

Example source: src/button/__demos__/block.vue

```vue
<template>
  <c-button block>Full width</c-button>
</template>
```

## Button groups

### Group inheritance and overrides

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Semantic color; inherits group, otherwise default | Group inheritance and overrides |
| `disabled` | Disabled; inherits group, explicit false overrides | Group inheritance and overrides |
| `loading` | Loading; blocks activation and navigation | Button Group Content |
<!-- demo-config-notes:end -->


Example source: src/button/__demos__/button-group.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const size = ref("md");
const disabled = ref(false);
</script>
<template>
  <c-space direction="column" :size="16" class="button-group-demo">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          aria-label="Button group size"
          :options="['xs', 'sm', 'md', 'lg', 'xl']"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="State" field="disabled"
        ><c-checkbox v-model="disabled">Disable group</c-checkbox></c-form-item
      >
    </c-form>
    <div class="button-group-demo__scroll">
      <c-button-group aria-label="Document actions" status="primary" :size="size" :disabled="disabled">
        <c-button>Inherited</c-button>
        <c-button status="success">Status override</c-button>
        <c-button :disabled="false">Enabled override</c-button>
      </c-button-group>
    </div>
  </c-space>
</template>
<style scoped>
.button-group-demo {
  width: 100%;
}
.button-group-demo__scroll {
  max-width: 100%;
  overflow-x: auto;
}
</style>
```

### Button Group Layout

Example source: src/button/__demos__/button-group-layout.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const mixed = ref(false)
const variant = ref("default");
const size = ref("md");
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Variant" field="variant">
        <c-radio-group
          v-model="variant"
          aria-label="Button group variant"
          :options="['default', 'text', 'outline', 'tonal']"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          aria-label="Button group size"
          :options="['xs', 'sm', 'md', 'lg', 'xl']"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Mixed variants"><c-checkbox v-model="mixed">Text override in middle</c-checkbox></c-form-item>
    </c-form>
    <c-space wrap align="flex-start" :size="24">
      <c-button-group
        v-for="vertical in [false, true]"
        :key="String(vertical)"
        :aria-label="vertical ? 'Vertical page actions' : 'Horizontal page actions'"
        :vertical="vertical"
        :variant="variant"
        :size="size"
        status="primary"
      >
        <c-button>Prev</c-button><c-button :variant="mixed ? 'text' : undefined">Info</c-button><c-button>Next</c-button>
      </c-button-group>
    </c-space>
  </c-space>
</template>
```

### Button Group Content

Example source: src/button/__demos__/button-group-content.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const stacked = ref(false);
const vertical = ref(false);
const loading = ref(false);
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="stacked">Stacked labels</c-checkbox>
      <c-checkbox v-model="vertical">Vertical group</c-checkbox>
      <c-checkbox v-model="loading">Load first action</c-checkbox>
    </c-space>
    <c-button-group aria-label="Save or cancel" status="primary" :stacked="stacked" :vertical="vertical">
      <c-button :loading="loading"
        ><template #icon><c-icon-check /></template>Save</c-button
      >
      <c-button
        ><template #icon><c-icon-close /></template>Cancel</c-button
      >
    </c-button-group>
  </c-space>
</template>
```

## Forms and events

### Control Sizes

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | Size; inherits group, otherwise md | Control Sizes |
| `variant` | Appearance; inherits group, otherwise default | Control Sizes |
| `html-type` | Native button type | Native form, focus and touch events |
| `focusable` | Allow sequential Tab focus; does not prevent programmatic focus | Native form, focus and touch events |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.
- `variant`: Selects the visual variant.

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### Native form, focus and touch events


Example source: src/button/__demos__/native-events.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('Editable')
const submissions = ref(0)
const event = ref('Use Tab, Enter or touch')
</script>
<template>
  <c-form @submit="submissions++" @reset="value = 'Editable'" style="display: flex; flex-wrap: wrap; gap: 12px">
    <c-input v-model="value" aria-label="Example field" placeholder="Example field" style="width: 100%; max-width: 280px" />
    <c-button html-type="submit">Submit</c-button>
    <c-button html-type="reset">Reset</c-button>
    <c-button :focusable="false">Skip Tab</c-button>
    <c-button @touchstart="event = 'touchstart'" @focus="event = 'focus'" @blur="event = 'blur'" @click="event = 'click'">Event target</c-button>
  </c-form>
  <p aria-live="polite">Submissions: {{ submissions }}; {{ event }}</p>
</template>
```

## Loading and action feedback

### Loading layouts and animations

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `loading` | Loading; blocks activation and navigation | Loading layouts and animations, Loading Appearance |
| `loading-size` | Indicator size; xs/sm/md/lg/xl map to 12/14/16/18/20px; numbers are px; follows button size when omitted; not used in line mode | Loading layouts and animations, Loading Appearance |
| `loading-type` | Spinner animation; same as Loading.type; not used in line mode | Loading layouts and animations |
| `loading-mode` | Inline, covering, or bottom progress line; line only uses loading-color | Loading layouts and animations |
| `loading-color` | Loading indicator color | Loading Appearance |
| `ripple` | Click ripple | Feedback |
<!-- demo-config-notes:end -->


Example source: src/button/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const stacked = ref(false)
const mode = ref("default");
const size = ref("md");
const modes = ["default", "fill", "line"];
const sizes = ["xs", "sm", "md", "lg", "xl"];
const types = ["circle", "wave", "cube", "rect", "disappear"];
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical" size="sm">
      <c-form-item label="Layout" field="mode">
        <c-radio-group
          v-model="mode"
          :options="modes"
          aria-label="Loading mode"
          variant="button"
        />
      </c-form-item>
      <c-form-item label="Size" field="size">
        <c-radio-group
          v-model="size"
          :disabled="mode === 'line'"
          :options="sizes"
          aria-label="Loading size"
          variant="button"
        />
      </c-form-item>
    </c-form>
    <label><input v-model="stacked" type="checkbox" />图文堆叠（stacked）</label>
    <p v-if="mode === 'line'">
      line 使用底部进度线，loading-type 和 loading-size 不适用；可通过
      loading-color 调整颜色。
    </p>
    <c-space wrap
      ><c-button
        v-for="type in mode === 'line' ? ['line'] : types"
        :key="type"
        loading
        :stacked="stacked"
        :loading-type="mode === 'line' ? 'circle' : type"
        :loading-mode="mode"
        :loading-size="size"
        ><template #icon><svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><path d="M8 1v14M1 8h14" stroke="currentColor" /></svg></template>{{ type }}</c-button
      ></c-space
    >
  </c-space>
</template>
```

### Loading Appearance

Example source: src/button/__demos__/loading-appearance.vue

```vue
<template>
  <c-space wrap
    ><c-button loading loading-color="#e05279">Custom color</c-button
    ><c-button loading :loading-size="16">Custom size</c-button></c-space
  >
</template>
```

### Feedback

- `elevation`: Controls the shadow intensity.

Example source: src/button/__demos__/feedback.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const ripple = ref(true);
const elevation = ref(2);
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="ripple">Ripple</c-checkbox>
      <label
        >Elevation<c-input-number
          v-model="elevation"
          :min="0"
          :max="24"
          aria-label="Button elevation"
      /></label>
    </c-space>
    <c-button :ripple="ripple" :elevation="elevation"
      >Click to compare feedback</c-button
    >
  </c-space>
</template>
```

### Sync, async and rejection recovery

Example source: src/button/__demos__/controlled-loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const saving = ref(false)
const failing = ref(false)
const message = ref('点击保存，观察业务控制的 loading / Click Save to start')
const delay = () => new Promise(resolve => setTimeout(resolve, 800))
async function save() {
  if (saving.value) return
  saving.value = true
  try { await delay(); message.value = '保存完成 / Saved' }
  finally { saving.value = false }
}
async function recover() {
  if (failing.value) return
  failing.value = true
  try { await delay(); throw new Error('模拟请求失败 / Simulated failure') }
  catch (error) { message.value = (error as Error).message }
  finally { failing.value = false }
}
</script>
<template>
  <c-space direction="column" :size="12">
    <p>click 支持 async 回调；业务通过 loading 展示等待，在 finally 中恢复。Async click handlers own their loading state.</p>
    <c-space wrap :size="12">
      <c-button :loading="saving" @click="save">保存 / Save</c-button>
      <c-button :loading="failing" @click="recover">失败与恢复 / Failure recovery</c-button>
    </c-space>
    <p aria-live="polite">{{ message }}</p>
  </c-space>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"`, including runtime changes and local overrides. Icons and content follow reading order; stacked content stays top to bottom and slot graphics are not mirrored. ButtonGroup owns horizontal joining edges and outer corners even when a child has a different text direction. A single child keeps all corners; vertical groups preserve top-to-bottom order. Native Tab, Enter and Space remain available; ordinary groups do not intercept horizontal arrows. Disabled and loading behavior stays unchanged.

## API

<!-- same-source-api:start -->

### Props

| Prop | Description | Type | Default |
| ------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------- | -------------- |
| status | Semantic color; inherits group, otherwise default | `SemanticStatus` | `undefined` |
| variant | Appearance; inherits group, otherwise default | `default / text / outline / tonal` | `undefined` |
| size | Size; inherits group, otherwise md | `xs / sm / md / lg / xl` | `undefined` |
| html-type | Native button type | `button / submit / reset` | `button` |
| component | Root tag; link attributes fall through | `button / a` | `button` |
| round | Round button | `boolean` | `false` |
| block | Full available width | `boolean` | `false` |
| loading | Loading; blocks activation and navigation | `boolean` | `false` |
| loading-type | Spinner animation; same as Loading.type; not used in line mode | `circle / wave / cube / rect / disappear` | `circle` |
| loading-mode | Inline, covering, or bottom progress line; line only uses loading-color | `default / fill / line` | `default` |
| loading-size | Indicator size; xs/sm/md/lg/xl map to 12/14/16/18/20px; numbers are px; follows button size when omitted; not used in line mode | `ComponentSize / number` | `undefined` |
| loading-color | Loading indicator color | `string` | `currentColor` |
| disabled | Disabled; inherits group, explicit false overrides | `boolean` | `undefined` |
| ripple | Click ripple | `boolean` | `true` |
| focusable | Allow sequential Tab focus; does not prevent programmatic focus | `boolean` | `true` |
| autofocus | Native autofocus | `boolean` | `false` |
| text-color | Custom text color | `string` | `undefined` |
| color | Custom background or variant base color | `string` | `undefined` |
| elevation | Default variant shadow; true=2, false=off, rounded/clamped 0–24; group owns grouped elevation | `boolean / number` | `true` |
| stacked | Stack icon and text; inherits group when omitted | `boolean` | `undefined` |

### Events

| Event | Arguments and behavior |
| ---------- | ------------------------------------------- |
| click | `(event: MouseEvent) => void` |
| touchstart | `(event: TouchEvent) => void` |

click is a normal emitted event and supports async handlers. Business state controls loading; restore it in finally. Listener Promises do not automatically drive loading. Disabled/loading links have no effective href.

### Slots

| Slot | Description | Arguments |
| ------- | -------------------------------- | ---- |
| default | Button label; retained while loading | — |
| icon | Leading icon; above label when stacked | — |

### Methods

No custom public methods.
<!-- same-source-api:end -->

## ButtonGroup

### ButtonGroup Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| status | Default semantic status; a child may override it | SemanticStatus | default |
| size | Default button size; a child may override it | xs / sm / md / lg / xl | md |
| variant | Default appearance; adjacent effective variants determine joining, including mixed variants | default / text / outline / tonal | default |
| color | Default custom color; a child may override it | string | undefined |
| text-color | Default text color; a child may override it | string | undefined |
| disabled | Default disabled state; an explicit child false overrides group true | boolean | false |
| stacked | Default vertical icon/text layout; a child may explicitly override with false | boolean | false |
| vertical | Vertical group layout, independent of button content stacking | boolean | false |
| elevation | Group shadow; true means 2, numbers normalize to 0–24; applies only to an enabled default-variant group | boolean / number | true |

The root defaults to `role="group"`. Supply `aria-label` or `aria-labelledby` when the action group needs a name. Native attributes can override role. Ordinary groups retain native Tab / Enter / Space handling without arrow-key focus management.

**Inheritance:** explicit child values win for status, size, variant, color, text-color, disabled and stacked. Elevation belongs to the group; a child's own elevation does not apply. Nested groups use their nearest group's settings and defaults rather than combining outer disabled states.

### ButtonGroup Events

No custom events. `@click` falls through to the root DOM element and can receive descendant bubbling; listen to each Button for its action. The group does not collect listener Promises or own a task or selection model.

### ButtonGroup Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| default | Joined styling supports directly adjacent Button DOM nodes under the group root | — |

**Composition:** extra DOM wrappers, prefix/suffix text and arbitrary controls are outside the joined-styling contract. Wrapped buttons may still inherit configuration without sharing the same joined edges. The group owns outer corners and does not preserve an individual round button's circular shape. Use Space for separated or arbitrary content. For narrow containers, the application chooses scrolling, shorter labels or vertical layout; groups do not wrap automatically.

### ButtonGroup Expose

| Name | Description |
| --- | --- |
| buttonGroupProvider | Reactive group configuration with readonly ComputedRef fields; elevation is boolean / number and other fields match the Props |

There are no additional group action methods.

## Types

ButtonProps、ButtonVariant、ButtonLoadingMode、ButtonInstance、ButtonGroupProps、ButtonGroupInstance。

## CSS variable responsibilities and complete defaults

Button exposes 58 appearance tokens. `{status}-color` controls the solid background, `{status}-foreground-color` controls text/outline/tonal foreground, and `{status}-tonal-color` controls soft backgrounds. `solid-text-color` and `solid-state-layer-color` are shared by semantic statuses; default/tertiary foregrounds and primary/tertiary state layers retain theme-specific roles.

Sizes use xs/sm/md/lg/xl. Font sizes, transition duration, focus width/offset and stacked-height increments reuse system variables. Button groups and stacked buttons share border-radius. Four state opacity variables preserve hover/active differences. loading-duration controls only the bottom progress line; Loading controls other loading animations. Internal variables and fixed animation geometry are not public customization points.

| Variable | Default |
| --------------------------------------- | ----------------------------------------- |
| `--c-button-border-radius` | `var(--c-sys-radius-md)` |
| `--c-button-content-gap` | `var(--c-sys-space-3)` |
| `--c-button-danger-color` | `var(--c-sys-color-status-danger)` |
| `--c-button-danger-disabled-color` | `rgb(var(--c-danger-3))` |
| `--c-button-danger-foreground-color` | `var(--c-sys-color-content-danger)` |
| `--c-button-danger-tonal-color` | `rgb(var(--c-danger-1))` |
| `--c-button-default-color` | `var(--c-sys-color-surface-default)` |
| `--c-button-default-foreground-color` | `var(--c-sys-color-content-primary)` |
| `--c-button-default-tonal-color` | `var(--c-sys-color-surface-muted)` |
| `--c-button-disabled-color` | `var(--c-color-fill-2)` |
| `--c-button-disabled-solid-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-button-disabled-text-color` | `var(--c-sys-color-content-disabled)` |
| `--c-button-focus-color` | `var(--c-sys-color-content-brand)` |
| `--c-button-info-color` | `var(--c-sys-color-status-info)` |
| `--c-button-info-disabled-color` | `rgb(var(--c-blue-3))` |
| `--c-button-info-foreground-color` | `var(--c-sys-color-content-info)` |
| `--c-button-info-tonal-color` | `rgb(var(--c-blue-1))` |
| `--c-button-lg-height` | `36px` |
| `--c-button-lg-padding` | `0 var(--c-sys-space-7)` |
| `--c-button-loading-duration` | `1s` |
| `--c-button-loading-line-height` | `3px` |
| `--c-button-md-height` | `32px` |
| `--c-button-md-padding` | `0 var(--c-sys-space-6)` |
| `--c-button-plain-state-opacity-active` | `1` |
| `--c-button-plain-state-opacity-hover` | `0.5` |
| `--c-button-primary-color` | `var(--c-sys-color-action-primary)` |
| `--c-button-primary-disabled-color` | `rgb(var(--c-primary-3))` |
| `--c-button-primary-foreground-color` | `var(--c-sys-color-content-brand)` |
| `--c-button-primary-state-layer-color` | `var(--c-button-solid-state-layer-color)` |
| `--c-button-primary-tonal-color` | `rgb(var(--c-primary-1))` |
| `--c-button-secondary-color` | `rgb(var(--c-gray-6))` |
| `--c-button-secondary-foreground-color` | `var(--c-sys-color-content-secondary)` |
| `--c-button-secondary-tonal-color` | `rgb(var(--c-gray-2))` |
| `--c-button-sm-height` | `28px` |
| `--c-button-sm-padding` | `0 var(--c-sys-space-5)` |
| `--c-button-solid-state-layer-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-button-solid-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-button-stacked-gap` | `var(--c-sys-space-2)` |
| `--c-button-state-layer-color` | `var(--c-sys-color-surface-page)` |
| `--c-button-state-opacity-active` | `0.12` |
| `--c-button-state-opacity-hover` | `0.08` |
| `--c-button-success-color` | `var(--c-sys-color-status-success)` |
| `--c-button-success-disabled-color` | `rgb(var(--c-success-3))` |
| `--c-button-success-foreground-color` | `var(--c-sys-color-content-success)` |
| `--c-button-success-tonal-color` | `rgb(var(--c-success-1))` |
| `--c-button-tertiary-color` | `rgb(var(--c-gray-7))` |
| `--c-button-tertiary-foreground-color` | `var(--c-sys-color-content-secondary)` |
| `--c-button-tertiary-state-layer-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-button-tertiary-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-button-tertiary-tonal-color` | `rgb(var(--c-gray-1))` |
| `--c-button-warning-color` | `var(--c-sys-color-status-warning)` |
| `--c-button-warning-disabled-color` | `rgb(var(--c-warning-3))` |
| `--c-button-warning-foreground-color` | `var(--c-sys-color-content-warning)` |
| `--c-button-warning-tonal-color` | `rgb(var(--c-warning-1))` |
| `--c-button-xl-height` | `44px` |
| `--c-button-xl-padding` | `0 var(--c-sys-space-8)` |
| `--c-button-xs-height` | `24px` |
| `--c-button-xs-padding` | `0 var(--c-sys-space-4)` |

---

Document: llms/en-US/components/calendar.md

<!-- Source: src/calendar/README.en-US.md; locale: en-US; page: /en/components/calendar/ -->

# Calendar

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/calendar/__demos__/basic.vue

```vue
<template>
  <c-calendar v-model="value" />
  <p class="demo-result">当前选择：{{ format(value) }}</p>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const format = (value: Date) =>
  value.toLocaleDateString("zh-CN", {
    year: "numeric",
    month: "long",
    day: "numeric",
    weekday: "long",
  });
</script>

<style scoped>
.demo-result {
  margin: 12px 0 0;
  color: var(--c-color-text-2);
}
</style>
```

## Views and date presentation

### Modes

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `mode` | Mode | Modes |
| `modes` | Displayed mode | Modes |
| `day-start-of-week` | First day of the week | Week Options |
| `is-week` | Whether to show week numbers | Week Options |
<!-- demo-config-notes:end -->


- `mode`: Mode
- `modes`: Displayed mode

Example source: src/calendar/__demos__/modes.vue

```vue
<template>
  <c-space wrap>
    <c-button
      :status="mode === 'month' ? 'primary' : 'default'"
      @click="mode = 'month'"
      >月视图</c-button
    >
    <c-button
      :status="mode === 'year' ? 'primary' : 'default'"
      @click="mode = 'year'"
      >年视图</c-button
    >
  </c-space>
  <c-calendar
    v-model="value"
    class="calendar-demo"
    :mode="mode"
    :modes="['month', 'year']"
  />
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const mode = ref<"month" | "year">("month");
</script>

<style scoped>
.calendar-demo {
  margin-top: 12px;
}
</style>
```

### Week Options

Preview configuration: `:day-start-of-week="mondayFirst ? 1 : 0"`, `:is-week="showWeek"`.

Example source: src/calendar/__demos__/week-options.vue

```vue
<template>
  <c-space wrap>
    <c-checkbox v-model="mondayFirst">周一作为一周开始</c-checkbox>
    <c-checkbox v-model="showWeek">显示周序号</c-checkbox>
  </c-space>
  <c-calendar
    v-model="value"
    class="calendar-demo"
    :day-start-of-week="mondayFirst ? 1 : 0"
    :is-week="showWeek"
  />
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const mondayFirst = ref(true);
const showWeek = ref(false);
</script>

<style scoped>
.calendar-demo {
  margin-top: 12px;
}
</style>
```

## Interaction and customization

### Controlled

Example source: src/calendar/__demos__/controlled.vue

```vue
<template>
  <c-space wrap>
    <c-button @click="selectToday">选择今天</c-button>
    <c-button @click="selectTomorrow">选择明天</c-button>
  </c-space>
  <c-calendar
    v-model="value"
    class="calendar-demo"
    @change="lastAction = `选择了 ${format($event)}`"
    @panel-change="lastAction = `面板切换到 ${formatMonth($event)}`"
  />
  <c-alert status="info">{{ lastAction }}</c-alert>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const lastAction = ref("可点击日期或切换月份");
const format = (date: Date) => date.toLocaleDateString("zh-CN");
const formatMonth = (date: Date) =>
  date.toLocaleDateString("zh-CN", { year: "numeric", month: "long" });
function selectToday() {
  value.value = new Date();
  lastAction.value = `外部设置为 ${format(value.value)}`;
}
function selectTomorrow() {
  const tomorrow = new Date();
  tomorrow.setDate(tomorrow.getDate() + 1);
  value.value = tomorrow;
  lastAction.value = `外部设置为 ${format(value.value)}`;
}
</script>

<style scoped>
.calendar-demo {
  margin: 12px 0;
}
</style>
```

### Custom Cell

Example source: src/calendar/__demos__/custom-cell.vue

```vue
<template>
  <c-calendar v-model="value">
    <template #default="{ year, month, date }">
      <div v-if="items[key(year, month, date)]" class="cell-items">
        <span
          v-for="item in items[key(year, month, date)]"
          :key="item.label"
          class="cell-item"
          :style="{ '--item-color': item.color }"
          >{{ item.label }}</span
        >
      </div>
    </template>
  </c-calendar>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
const today = new Date();
const key = (year: number, month: number, date: number) =>
  `${year}-${month}-${date}`;
const relativeKey = (offset: number) => {
  const date = new Date(today);
  date.setDate(date.getDate() + offset);
  return key(date.getFullYear(), date.getMonth() + 1, date.getDate());
};
const items: Record<string, Array<{ label: string; color: string }>> = {
  [relativeKey(0)]: [
    { label: "产品评审", color: "rgb(var(--c-primary-6))" },
    { label: "版本发布", color: "rgb(var(--c-success-6))" },
  ],
  [relativeKey(2)]: [{ label: "客户回访", color: "rgb(var(--c-warning-6))" }],
  [relativeKey(5)]: [{ label: "团队周会", color: "rgb(var(--c-purple-6))" }],
};
</script>

<style scoped>
.cell-items {
  display: flex;
  flex-direction: column;
  gap: 4px;
  margin-top: 6px;
}
.cell-item {
  overflow: hidden;
  color: var(--c-color-text-2);
  font-size: 12px;
  line-height: 20px;
  text-overflow: ellipsis;
  white-space: nowrap;
}
.cell-item::before {
  display: inline-block;
  width: 6px;
  height: 6px;
  margin-right: 6px;
  background: var(--item-color);
  border-radius: 50%;
  content: "";
}
</style>
```

### Custom Header

Example source: src/calendar/__demos__/custom-header.vue

```vue
<template>
  <c-calendar v-model="value">
    <template #header="{ year, month }">
      <span class="custom-title">{{ year }} 年 {{ month }} 月工作日历</span>
    </template>
  </c-calendar>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref(new Date());
</script>

<style scoped>
.custom-title {
  margin: 0 8px;
  color: var(--c-color-text-1);
  font-weight: 600;
}
</style>
```

## API

### `<calendar>` Props

| Parameter | Description | Type | Default |
| ------------------------- | -------------------- | ----------------------- | :-----------------: |
| model-value **(v-model)** | Bound value | `date` | `-` |
| default-value | Default value (uncontrolled state) | `date` | `-` |
| mode | Mode | `'month' \| 'year'` | `-` |
| default-mode | Default Mode | `'month' \| 'year'` | `'month'` |
| modes | Displayed mode | `('month' \| 'year')[]` | `['month', 'year']` |
| day-start-of-week | First day of the week | `0 \| 1` | `0` |
| is-week | Whether to show week numbers | `boolean` | `false` |

### `<calendar>` Events

| Event | Description | Arguments |
| ------------ | -------------------- | ------------ |
| change | Emitted when the selected date changes | date: `Date` |
| panel-change | Emitted when the displayed date panel changes | date: `Date` |

### `<calendar>` Slots

| Slot | Description | Arguments | Version |
| ------- | :--------------: | --------------------------------------------------- | :----- |
| header | Custom header content | year: `number`<br>month: `number` | 2.53.0 |
| default | Custom cell content | year: `number`<br>month: `number`<br>date: `number` | 2.53.0 |

### Type definitions

The component exports the following types

```ts
import type { CalendarInstance } from "@cedar-design/ui";
```

---

Document: llms/en-US/components/card.md

<!-- Source: src/card/README.en-US.md; locale: en-US; page: /en/components/card/ -->

# Card

Source changes synchronously invalidate render generations. Close, row direction, newer work, deactivation or disposal prevent old nextTick/timer/double-frame continuations from changing newer phases. Render/timer deliveries consume once. Recheck lifecycle/request/node after geometry hooks to reject reentrant disposal. Suspension cancels both timers and retained close/click input is inert; activation starts a fresh phase from current props without replay, and initial KeepAlive activation does not duplicate the wait.

## Basic examples

### Basic usage and subtitle

Example source: src/card/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-card title="Project overview" description="Keep the team informed." />
    <c-card
      title="Project overview"
      subtitle="Updated today"
      description="Keep the team informed."
      top-divider
      bottom-divider
    >
      Release checklist and project updates.
      <template #title-action><c-button size="sm">More</c-button></template>
      <template #footer><c-button status="primary">View details</c-button></template>
    </c-card>
  </c-space>
</template>
```

## Appearance and states

### Appearance configuration comparison

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title | Appearance configuration comparison, Hover style |
| `description` | Description | Appearance configuration comparison |
| `hoverable` | Hover style | Hover style |
<!-- demo-config-notes:end -->


Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/card/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({ variant: "default", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["default","outline","tonal"]},{"name":"size","values":["sm","md"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])

__demoAppearance['elevation'] = 2
demoCompareFields.push({ name: 'elevation', values: [0, 2, 6] })
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'outline', value: 'outline' },
            { label: 'tonal', value: 'tonal' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    <c-form-item label="elevation"><c-radio-group v-model="__demoAppearance['elevation']" aria-label="elevation" :options="[{ label: '0', value: 0 }, { label: '2', value: 2 }, { label: '6', value: 6 }]" /></c-form-item>
</c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-card
      title="Project overview"
      description="Keep the team informed."
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    />
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Hover style

Example source: src/card/__demos__/hoverable.vue

```vue
<template>
  <c-card hoverable title="Hover over this card" style="width: 100%; max-width: 360px"
    >Hover feedback on pointer devices.</c-card
  >
</template>
```

## Layout and arrangement

### Images and directions

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `direction` | Order of cover and body, default column; supports row, column and row-reverse. Does not position the card itself | Images and directions |
| `title` | Title | Images and directions |
| `src` | Cover image URL; cover slot takes precedence | Images and directions |
| `alt` | Image alternative text | Images and directions |
| `image-height` | Image height; numbers use px | Images and directions |
| `image-width` | Image width; numbers use px | Images and directions |
<!-- demo-config-notes:end -->


Example source: src/card/__demos__/image.vue

```vue
<script setup lang="ts">
const imageSrc = `${import.meta.env.BASE_URL}cat.jpg`
const directions = ['column', 'row', 'row-reverse'] as const
</script>

<template>
  <c-space direction="column" style="width: 100%">
    <c-card
      v-for="direction in directions"
      :key="direction"
      :direction="direction"
      :title="direction"
      :src="imageSrc"
      alt="Cat"
      :image-height="120"
      :image-width="direction === 'column' ? '100%' : 100"
      fit="cover"
      >Card content</c-card
    >
    <c-card title="Custom cover"
      ><template #cover
        ><img :src="imageSrc" alt="Cat" style="width: 100%; height: 120px; object-fit: cover" /></template
      >Cover slot overrides the image.</c-card
    >
  </c-space>
</template>
```

## Content and presentation

### Long title and tooltip

Example source: src/card/__demos__/tooltip.vue

```vue
<script setup lang="ts">
const title = 'Project overview with a long title that does not fit on one line'
</script>

<template>
  <c-card style="width: 100%; max-width: 280px">
    <template #title
      ><span class="long-title" :title="title">{{ title }}</span></template
    >
    <template #description
      ><span class="long-title" :title="title">{{ title }}</span></template
    >
    Native title tooltip on pointer devices; the full text remains in the DOM.
  </c-card>
</template>

<style scoped>
.long-title {
  display: block;
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
}
</style>
```

## Customization and slots

### Custom header

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title | Custom header |
| `top-divider` | Top divider | Content slots |
| `bottom-divider` | Bottom divider | Content slots |
<!-- demo-config-notes:end -->


Example source: src/card/__demos__/no-padding.vue

```vue
<template>
  <c-card title="Fallback title">
    <template #header
      ><header style="padding: 16px">
        <strong>Custom header</strong>
        <p>Replaces the title and subtitle region.</p>
      </header></template
    >
    Card content
  </c-card>
</template>
```

### Content slots

Example source: src/card/__demos__/slots.vue

```vue
<template>
  <c-card top-divider bottom-divider>
    <template #cover><div style="padding: 16px">Custom cover</div></template>
    <template #title="{ slotClass }"><strong :class="slotClass">Custom title</strong></template>
    <template #title-action><c-button size="sm">More</c-button></template>
    <template #subtitle="{ slotClass }"><span :class="slotClass">Custom subtitle</span></template>
    <template #description="{ slotClass }"><p :class="slotClass">Custom description</p></template>
    Default content
    <template #footer><c-button status="primary">Confirm</c-button></template>
  </c-card>
</template>
```

## Interaction and control

### Ripple and click

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title | Ripple and click, Floating and close |
| `ripple` | Click ripple | Ripple and click |
| `floating` | Fullscreen state; supports v-model:floating | Floating and close |
| `floating-duration` | Fullscreen transition duration in ms | Floating and close |
<!-- demo-config-notes:end -->


Example source: src/card/__demos__/ripple.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const clicks = ref(0)
</script>

<template>
  <c-card ripple title="Click this card" @click="clicks++"
    >Clicks: <output aria-live="polite">{{ clicks }}</output></c-card
  >
</template>
```

### Floating and close

Example source: src/card/__demos__/floating.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const floating = ref(false)
</script>

<template>
  <c-card v-model:floating="floating" title="Project overview" :floating-duration="250">
    Summary content
    <template #footer><c-button status="primary" @click="floating = true">Expand</c-button></template>
    <template #floating-content><p style="padding: 16px">Expanded project details.</p></template>
    <template #close-button
      ><c-button aria-label="Close expanded card" @click.stop="floating = false">Close</c-button></template
    >
  </c-card>
</template>
```

## Lifecycle and edge cases

### Floating scheduler lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `floating` | Fullscreen state; supports v-model:floating | Floating scheduler lifecycle |
| `ripple` | Click ripple | Floating scheduler lifecycle |
| `floating-duration` | Fullscreen transition duration in ms | Floating scheduler lifecycle |
| `title` | Title | Floating scheduler lifecycle |
<!-- demo-config-notes:end -->


500ms ripple wait is interaction policy; floating-duration defaults to250ms for collapse and transition. DoubleRaf settles layout; cancellation rejects stale continuation writes, not underlying frames. Public API and CSS variables are unchanged. Full Card Cedar21/Maple44 and scoped15 each are controlled tests, not native browser/OS certification.

Example source: src/card/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref(true)
const mounted = ref(true)
const floating = ref(false)
const ripple = ref(true)
const duration = ref(250)
</script>
<template>
  <div>
    <c-button @click="floating = !floating">Float / 浮起与回落</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <c-button @click="ripple = !ripple">Ripple wait / 涟漪等待</c-button>
    <c-button @click="duration = duration ? 0 : 250">Duration / 零与默认时长</c-button>
    <p>Toggle floating rapidly, suspend during500ms ripple wait or layout settlement, then activate. Old tasks must not reset a newer phase. Underlying doubleRaf frames are not physically canceled.</p>
    <KeepAlive v-if="mounted">
      <c-card v-if="active" v-model:floating="floating" :ripple="ripple" :floating-duration="duration" title="Floating lifecycle / 浮起生命周期">
        Card content / 卡片内容
        <template #floating-content>
          <c-button @click.stop="floating = false">Collapse / 回落</c-button>
          <c-button @click.stop="active = false">Deactivate / 停用</c-button>
          <c-button @click.stop="mounted = false">Unmount / 卸载</c-button>
        </template>
      </c-card>
    </KeepAlive>
  </div>
</template>
```

The same scenarios, parameters and interactions as Cedar. Only component prefixes differ; themes and site shells remain independent.

## Reading direction

Headings, content and actions follow reading order. Default floating actions sit at reading end without mirroring images or custom slots.

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| variant | Appearance | `default / outline / tonal` | `default` |
| size | Density; omitted value follows platform rules below | `sm / md` | `undefined` |
| direction | Order of cover and body, default column; supports row, column and row-reverse. Does not position the card itself | `row / column / row-reverse` | `column` |
| hoverable | Hover styling | `boolean` | `false` |
| title-style | Title row styles | `CSSProperties` | `undefined` |
| title | Title | `string` | `undefined` |
| subtitle | Subtitle | `string` | `undefined` |
| description | Description | `string` | `undefined` |
| top-divider | Top divider | `boolean` | `false` |
| bottom-divider | Bottom divider | `boolean` | `false` |
| src | Cover image URL; cover slot takes precedence | `string` | `undefined` |
| fit | Cover image fit | `fill / contain / cover / none / scale-down` | `cover` |
| image-height | Image height; numbers use px | `string / number` | `undefined` |
| image-width | Image width; numbers use px | `string / number` | `undefined` |
| alt | Image alternative text | `string` | `undefined` |
| elevation | Shadow for default variant; true means level 1, false disables it, numeric levels 0–24 | `boolean / number` | `true` |
| ripple | Click ripple | `boolean` | `false` |
| floating | Fullscreen state; supports v-model:floating | `boolean` | `false` |
| floating-duration | Fullscreen transition duration in ms | `number` | `250` |

### Events

| Event | Arguments and timing |
| --- | --- |
| click | `(event: Event)`, emitted when the card is clicked |
| update:floating | `(value: boolean)`, emits false when the built-in close button requests closing; expansion is controlled by the parent |

### Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| default | Body | — |
| cover | Cover; overrides src | — |
| header | Entire header; overrides title, title-action and subtitle | — |
| title | Title | `{ slotClass: string }` |
| title-action | Title action | — |
| subtitle | Subtitle | `{ slotClass: string }` |
| description | Description | `{ slotClass: string }` |
| footer | Footer actions | — |
| floating-content | Expanded content; column layout only | — |
| close-button | Custom close button; update floating yourself | — |

### Methods

No public methods.

### Platform notes

Props, event arguments and slots match. Cedar inherits the global size when size is omitted: xs/sm map to sm, all others to md. Maple falls back to md. Pass size explicitly for identical density. Themes and CSS prefixes remain platform-specific.
Card no longer has a loading prop. Compose a loading overlay with the Loading directive.
<!-- same-source-api:end -->

### `<Card>` CSS variables

| Variable | Default |
| --- | --- |
| `--c-card-hover-shadow` | `0 4px 12px rgb(0 0 0 / 12%)` |
| `--c-card-size-sm-title-font-size` | `16px` |
| `--c-card-size-sm-section-margin` | `8px 0 0` |
| `--c-card-size-sm-section-padding` | `0 12px` |
| `--c-card-padding` | `0 0 15px 0` |
| `--c-card-background` | `var(--c-sys-color-surface-default)` |
| `--c-card-filled-background` | `var(--c-sys-color-surface-muted)` |
| `--c-card-outline-color` | `var(--c-sys-color-border-default)` |
| `--c-card-border-radius` | `4px` |
| `--c-card-image-width` | `100%` |
| `--c-card-row-image-width` | `140px` |
| `--c-card-image-height` | `200px` |
| `--c-card-row-height` | `140px` |
| `--c-card-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-card-title-font-size` | `20px` |
| `--c-card-title-padding` | `0 12px` |
| `--c-card-title-margin` | `15px 0 0 0` |
| `--c-card-title-row-margin` | `12px 0` |
| `--c-card-content-padding` | `0 16px` |
| `--c-card-content-margin` | `16px 0 0 0` |
| `--c-card-content-color` | `var(--c-sys-color-content-tertiary)` |
| `--c-card-content-font-size` | `14px` |
| `--c-card-content-row-margin` | `16px 0 0 0` |
| `--c-card-subtitle-color` | `var(--c-sys-color-content-secondary)` |
| `--c-card-subtitle-font-size` | `14px` |
| `--c-card-subtitle-padding` | `0 12px` |
| `--c-card-subtitle-margin` | `10px 0 0 0` |
| `--c-card-subtitle-row-margin` | `-8px 0 0 0` |
| `--c-card-description-color` | `var(--c-sys-color-content-secondary)` |
| `--c-card-description-font-size` | `14px` |
| `--c-card-description-margin` | `20px 0 0 0` |
| `--c-card-description-padding` | `0 13px` |
| `--c-card-footer-padding` | `0 12px` |
| `--c-card-footer-right` | `13px` |
| `--c-card-footer-bottom` | `9px` |
| `--c-card-footer-margin` | `30px 0 0 0` |
| `--c-card-line-height` | `22px` |
| `--c-card-row-line-height` | `1.5` |
| `--c-card-floating-buttons-bottom` | `16px` |
| `--c-card-floating-buttons-right` | `16px` |
| `--c-card-floating-buttons-color` | `var(--c-sys-color-content-primary)` |
| `--c-card-close-button-icon-size` | `24px` |
| `--c-card-close-button-size` | `56px` |
| `--c-card-close-button-background` | `#212121` |
| `--c-card-close-button-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-card-close-button-border-radius` | `50%` |

Card colors follow system semantics: regular/filled backgrounds and borders use `surface-default`, `surface-muted` and `border-default`. Titles, body text and secondary text use `content-primary`, `content-tertiary` and `content-secondary`. Expanded floating-button containers sit on the card surface and use `content-primary`; text/icons on dark close buttons use `content-on-dark`. The `#212121` close-button background is Card-specific, not the global primary-action color. See the Design Token specification for old variable mappings.

### Type definitions

The component exports the following types

```ts
import type { CardProps } from '@cedar-design/ui'
```

See `API-MIGRATION.md` at the repository root for size and cross-platform migration rules. Only the documented sizes are supported, not every ComponentSize.

### Variable consumption rules

Row content consumes `--c-card-content-row-margin`, independently from the title margin. Card intentionally exposes only sm/md density, not all five control sizes. Motion uses `--c-card-animation-duration` (`var(--c-sys-motion-duration-slow)`) and `--c-card-animation-easing` (`var(--c-sys-motion-easing-standard)`). Reduced motion disables transitions on every animated Card section.

---

Document: llms/en-US/components/carousel.md

<!-- Source: src/carousel/README.en-US.md; locale: en-US; page: /en/components/carousel/ -->

# Carousel

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/carousel/__demos__/basic.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" >
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

## Direction and layout

### Vertical

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `slides-per-view` | Visible count; auto uses item size | Multi Slides, Centered Slides, Auto Sized |
| `space-between` | Item gap; numbers/numeric strings are px | Multi Slides, Centered Slides, Auto Sized |
| `draggable` | Mouse dragging, independent of touch | Multi Slides, Auto Sized |
| `centered-slides` | Center active slide | centered-slides、auto-sized |
| `orientation` | Horizontal/vertical axis of carousel sliding, default horizontal; does not determine indicator position | Vertical |
| `model-value` | Controlled one-based slide number | Multi Slides |
<!-- demo-config-notes:end -->


- `orientation`: Controls the content direction.

Example source: src/carousel/__demos__/vertical.vue

```vue
<template>
  <c-carousel orientation="vertical" :style="{ width: '600px', height: '300px' }">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Multi Slides

Preview configuration: `:slides-per-view="2.5"`, `:space-between="10"`, `:model-value="current"`, `:loop="loop"`.

Example source: src/carousel/__demos__/multi-slides.vue

```vue
<script setup>
import { ref } from "vue";
const current = ref(1);
const proposal = ref(1);
const changes = ref(0);
const accept = ref(true);
const loop = ref(true);
function update(value) {
  proposal.value = value;
  if (accept.value) current.value = value;
}
</script>

<template>
  <section class="multi-slides-demo">
    <c-checkbox v-model="accept"> Accept changes / 接受切换</c-checkbox>
    <c-checkbox v-model="loop"> Loop / 循环</c-checkbox>
    <p role="status">
      Current: {{ current }} · Proposal: {{ proposal }} · Changes: {{ changes }}
    </p>
    <c-carousel
      :slides-per-view="2.5"
      :space-between="10"
      :style="{ width: '600px', height: '200px' }"
      :model-value="current"
      :loop="loop"
      draggable
      keyboard
      @update:modelValue="update"
      @change="changes++"
    >
      <c-carousel-item v-for="i in 6" :key="i">
        <div
          style="
            width: 100%;
            height: 100%;
            display: flex;
            align-items: center;
            justify-content: center;
            background: #4a90d9;
            color: #fff;
            font-size: 24px;
            font-weight: bold;
          "
        >
          {{ i }}
        </div>
      </c-carousel-item>
    </c-carousel>
  </section>
</template>
```

### Centered Slides

Preview configuration: `:slides-per-view="1.5"`, `:space-between="10"`, `centered-slides`.

Example source: src/carousel/__demos__/centered-slides.vue

```vue
<script setup></script>

<template>
  <c-carousel class="carousel" :slides-per-view="1.5" :space-between="10" centered-slides>
    <c-carousel-item v-for="i in 5" :key="i">
      <div class="carousel-custom-slide">{{ i }}</div>
    </c-carousel-item>
  </c-carousel>
</template>

<style lang="less" scoped>
.carousel {
  height: 160px;
}

.carousel-example {
  height: 160px;
}

.carousel-item {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}

.carousel-custom-slide {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #4a90d9;
  color: #fff;
  font-size: 24px;
  font-weight: bold;
}

.carousel-custom-indicators {
  position: absolute;
  bottom: 10px;
  left: 50%;
  transform: translateX(-50%);
  display: flex;
  gap: 4px;
}

.carousel-custom-indicator {
  width: 20px;
  height: 20px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: rgba(0, 0, 0, 0.3);
  color: #fff;
  font-size: 12px;
  border-radius: 50%;
}

.carousel-custom--active {
  background: #4a90d9;
}

.space {
  height: 20px;
}
</style>
```

### Auto Sized

- `height`: Constrains the component height.

Example source: src/carousel/__demos__/auto-sized.vue

```vue
<script setup>
import { computed, ref } from "vue";
const current = ref(1);
const changes = ref(0);
const wider = ref(false);
const compact = ref(false);
const extra = ref(false);
const empty = ref(false);
const reversed = ref(false);
const widths = computed(() => {
  const items = empty.value
    ? []
    : [140, 220, 180, 260, ...(extra.value ? [200] : [])];
  return (reversed.value ? items.reverse() : items).map(
    (width) => width + (wider.value ? 80 : 0),
  );
});
</script>

<template>
  <section class="auto-sized-demo">
    <c-checkbox v-model="wider"> Wider cards / 加宽卡片</c-checkbox>
    <c-checkbox v-model="compact"> 300px viewport / 窄容器</c-checkbox>
    <c-checkbox v-model="extra"> Extra card / 增加末项</c-checkbox>
    <c-checkbox v-model="empty"> Empty / 清空项目</c-checkbox>
    <c-checkbox v-model="reversed"> Reverse cards / 反转顺序</c-checkbox>
    <p role="status">Current: {{ current }} · Changes: {{ changes }}</p>
    <c-carousel
      v-model="current"
      slides-per-view="auto"
      :space-between="12"
      :style="{ width: compact ? '300px' : '100%' }"
      height="180px"
      centered-slides
      draggable
      @change="changes++"
    >
      <c-carousel-item
        v-for="width in widths"
        :key="width"
        :style="{ width: width + 'px' }"
      >
        <div class="carousel-demo-panel">{{ width }}px</div>
      </c-carousel-item>
    </c-carousel>
  </section>
</template>
<style scoped>
.carousel-demo-panel {
  display: grid;
  place-items: center;
  height: 100%;
  background: #e0e7ff;
  color: #312e81;
}
</style>
```

## Navigation and effects

### Navigation

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `show-arrow` | Arrow visibility | Navigation |
| `indicator-type` | Indicator appearance | Indicator style and position |
| `indicator-position` | Indicator edge or outer region of the carousel container, default bottom. Not a trigger-relative popup placement | Indicator style and position |
| `effect` | Effect; all supported by both libraries | Transition effects |
<!-- demo-config-notes:end -->


Preview configuration: `show-arrow="always"`, `show-arrow="hover"`.

Example source: src/carousel/__demos__/navigation.vue

```vue
<template>
  <div>
    <h4 style="margin:0 0 8px">Always</h4>
    <c-carousel show-arrow="always" :style="{width:'600px',height:'200px',marginBottom:'20px'}">
      <c-carousel-item><img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
    </c-carousel>
    <h4 style="margin:0 0 8px">Hover</h4>
    <c-carousel show-arrow="hover" :style="{width:'600px',height:'200px'}">
      <c-carousel-item><img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
      <c-carousel-item><img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none"></c-carousel-item>
    </c-carousel>
  </div>
</template>
```

### Indicator style and position

All indicator presets use the same three local slides and active-slide model. Click an indicator or a navigation arrow in any specimen: every specimen changes to the same slide. The first group compares dot, line and slider; the second compares top and outer positions. The grid stacks on narrow screens.

Example source: src/carousel/__demos__/indicator-comparison.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const current = ref(1)
const groups = [{"name":"indicator-type","zh":"指示器样式","en":"Indicator types","values":[{"label":"dot","type":"dot","position":"bottom"},{"label":"line","type":"line","position":"bottom"},{"label":"slider","type":"slider","position":"bottom"}]},{"name":"indicator-position","zh":"指示器位置","en":"Indicator positions","values":[{"label":"top","type":"dot","position":"top"},{"label":"outer","type":"dot","position":"outer"}]}] as const
const slides = ["data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22640%22%20height%3D%22240%22%3E%3Crect%20width%3D%22640%22%20height%3D%22240%22%20fill%3D%22%23286b72%22%2F%3E%3Ctext%20x%3D%22320%22%20y%3D%22130%22%20text-anchor%3D%22middle%22%20fill%3D%22white%22%20font-size%3D%2236%22%3ESlide%201%3C%2Ftext%3E%3C%2Fsvg%3E","data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22640%22%20height%3D%22240%22%3E%3Crect%20width%3D%22640%22%20height%3D%22240%22%20fill%3D%22%234b5694%22%2F%3E%3Ctext%20x%3D%22320%22%20y%3D%22130%22%20text-anchor%3D%22middle%22%20fill%3D%22white%22%20font-size%3D%2236%22%3ESlide%202%3C%2Ftext%3E%3C%2Fsvg%3E","data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22640%22%20height%3D%22240%22%3E%3Crect%20width%3D%22640%22%20height%3D%22240%22%20fill%3D%22%23965734%22%2F%3E%3Ctext%20x%3D%22320%22%20y%3D%22130%22%20text-anchor%3D%22middle%22%20fill%3D%22white%22%20font-size%3D%2236%22%3ESlide%203%3C%2Ftext%3E%3C%2Fsvg%3E"]
</script>
<template>
<div class="indicator-comparison">
<p role="status">Slide: {{ current }}</p>
<section v-for="group in groups" :key="group.name" :data-comparison-scene="group.name">
<h4><span lang="zh-CN">{{ group.zh }}</span><span lang="en-US">{{ group.en }}</span></h4>
<div class="indicator-comparison-grid">
<div v-for="preset in group.values" :key="preset.label">
<p><code>{{ preset.label }}</code></p>
<c-carousel v-model="current" :indicator-type="preset.type" :indicator-position="preset.position" style="height: 150px">
<c-carousel-item v-for="(src, index) in slides" :key="src"><img :src="src" :alt="'Slide ' + (index + 1)" /></c-carousel-item>
</c-carousel>
</div>
</div>
</section>
</div>
</template>
<style scoped>
.indicator-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.indicator-comparison-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 240px), 1fr)); gap: 16px; }
.indicator-comparison > section, .indicator-comparison-grid, .indicator-comparison-grid > div { min-width: 0; max-width: 100%; }
p, h4 { margin: 0 0 8px; }
img { width: 100%; height: 100%; object-fit: cover; pointer-events: none; }
html:not([lang='en-US']) h4 > [lang='en-US'], html[lang='en-US'] h4 > [lang='zh-CN'] { display: none; }
</style>
```

### Transition effects

Change adjacent slides to compare fade, card and slide effects independently of autoplay and input methods.

Example source: src/carousel/__demos__/effect-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="effect-fade">
    <h4><span lang="zh-CN">effect-fade</span><span lang="en-US">effect fade</span></h4>
    <c-carousel class="carousel" effect="fade">
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat2.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat3.jpg'" alt="" />
        </c-carousel-item>
      </c-carousel>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="effect-card">
    <h4><span lang="zh-CN">effect-card</span><span lang="en-US">effect card</span></h4>
    <c-carousel class="carousel" effect="card">
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat2.jpg'" alt="" />
        </c-carousel-item>
        <c-carousel-item>
          <img class="carousel-item" :src="'/cat3.jpg'" alt="" />
        </c-carousel-item>
      </c-carousel>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.carousel {
  height: 160px;
}

.carousel-example {
  height: 160px;
}

.carousel-item {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}

.carousel-custom-slide {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #4a90d9;
  color: #fff;
  font-size: 24px;
  font-weight: bold;
}

.carousel-custom-indicators {
  position: absolute;
  bottom: 10px;
  left: 50%;
  transform: translateX(-50%);
  display: flex;
  gap: 4px;
}

.carousel-custom-indicator {
  width: 20px;
  height: 20px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: rgba(0, 0, 0, 0.3);
  color: #fff;
  font-size: 12px;
  border-radius: 50%;
}

.carousel-custom--active {
  background: #4a90d9;
}

.space {
  height: 20px;
}

}
.demo-comparison-case--2 {

.carousel {
  height: 160px;
}

.carousel-example {
  height: 160px;
}

.carousel-item {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}

.carousel-custom-slide {
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  background: #4a90d9;
  color: #fff;
  font-size: 24px;
  font-weight: bold;
}

.carousel-custom-indicators {
  position: absolute;
  bottom: 10px;
  left: 50%;
  transform: translateX(-50%);
  display: flex;
  gap: 4px;
}

.carousel-custom-indicator {
  width: 20px;
  height: 20px;
  display: flex;
  align-items: center;
  justify-content: center;
  background: rgba(0, 0, 0, 0.3);
  color: #fff;
  font-size: 12px;
  border-radius: 50%;
}

.carousel-custom--active {
  background: #4a90d9;
}

.space {
  height: 20px;
}

}
</style>
```

### Custom Indicator

Example source: src/carousel/__demos__/custom-indicator.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }">
    <c-carousel-item
      ><img
        src="/cat.jpg"
        style="
          width: 100%;
          height: 100%;
          object-fit: cover;
          pointer-events: none;
        "
    /></c-carousel-item>
    <c-carousel-item
      ><img
        src="/cat2.jpg"
        style="
          width: 100%;
          height: 100%;
          object-fit: cover;
          pointer-events: none;
        "
    /></c-carousel-item>
    <c-carousel-item
      ><img
        src="/cat3.jpg"
        style="
          width: 100%;
          height: 100%;
          object-fit: cover;
          pointer-events: none;
        "
    /></c-carousel-item>
    <template #indicator="{ slideNumber, length, to }">
      <div
        style="
          position: absolute;
          bottom: 10px;
          left: 50%;
          transform: translateX(-50%);
          display: flex;
          gap: 4px;
        "
      >
        <c-button
          v-for="i in length"
          :key="i"
          size="xs"
          round
          :variant="i === slideNumber ? 'default' : 'tonal'"
          :status="i === slideNumber ? 'primary' : 'default'"
          :aria-label="`跳转至第 ${i} 页`"
          @click="to(i)"
          >{{ i }}</c-button
        >
      </div>
    </template>
  </c-carousel>
</template>
```

## Playback and interaction

### Forbid Loop

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `height` | Container height; numbers are px | Autoplay, Controlled, Interactive Content |
| `keyboard` | Scoped arrow/Home/End navigation | Keyboard, Controlled, Interactive Content |
| `auto-play` | Autoplay configuration | Autoplay, Auto Play Hover |
| `draggable` | Mouse dragging, independent of touch | controlled、interactive-content |
| `loop` | Loop without duplicating instances | Forbid Loop |
| `trigger` | Indicator trigger | Trigger |
<!-- demo-config-notes:end -->


Preview configuration: `:loop="false"`.

Example source: src/carousel/__demos__/forbid-loop.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" :loop="false">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Autoplay

- `height`: Constrains the component height.

Example source: src/carousel/__demos__/autoplay.vue

```vue
<script setup>
import { ref } from "vue";
const current = ref(1);
const playing = ref(true);
const changes = ref(0);
const sources = ["/cat.jpg", "/cat2.jpg", "/cat3.jpg"];
</script>

<template>
  <section class="carousel-autoplay-demo">
    <c-checkbox v-model="playing"> 自动播放</c-checkbox>
    <p role="status">当前页：{{ current + 1 }}；切换次数：{{ changes }}</p>
    <c-carousel
      v-model="current"
      height="180px"
      :auto-play="playing ? 2000 : false"
      @change="changes += 1"
    >
      <c-carousel-item v-for="(source, index) in sources" :key="source">
        <img
          class="carousel-autoplay-demo__image"
          :src="source"
          :alt="'示例图片 ' + (index + 1)"
        />
      </c-carousel-item>
    </c-carousel>
  </section>
</template>

<style scoped>
.carousel-autoplay-demo__image {
  width: 100%;
  height: 100%;
  object-fit: cover;
  pointer-events: none;
}
</style>
```

### Auto Play Hover

Preview configuration: `:auto-play="{ interval: 2000, hoverToPause: true }"`.

Example source: src/carousel/__demos__/auto-play-hover.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" :auto-play="{ interval: 2000, hoverToPause: true }">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Trigger

Preview configuration: `trigger="hover"`.

Example source: src/carousel/__demos__/trigger.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" trigger="hover">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Mousewheel

Preview configuration: `mousewheel`.

Example source: src/carousel/__demos__/mousewheel.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" mousewheel>
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Keyboard

Preview configuration: `keyboard`.

Example source: src/carousel/__demos__/keyboard.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" keyboard>
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>
```

### Change Event

Example source: src/carousel/__demos__/change-event.vue

```vue
<template>
  <c-carousel :style="{ width: '600px', height: '240px' }" @change="handleChange">
    <c-carousel-item>
      <img src="/cat.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat2.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
    <c-carousel-item>
      <img src="/cat3.jpg" style="width:100%;height:100%;object-fit:cover;pointer-events:none">
    </c-carousel-item>
  </c-carousel>
</template>

<script setup>
const handleChange = (slideNumber) => {
  console.log('slide:', slideNumber)
}
</script>
```

### Controlled

- `height`: Constrains the component height.

Example source: src/carousel/__demos__/controlled.vue

```vue
<script setup>
import { ref } from "vue";
const current = ref(1);
const accept = ref(true);
const proposal = ref(1);
function update(value) {
  proposal.value = value;
  if (accept.value) current.value = value;
}
</script>
<template>
  <c-checkbox v-model="accept"> Accept changes / 接受切换</c-checkbox>
  <p>Current: {{ current }} · Proposal: {{ proposal }}</p>
  <c-carousel
    :model-value="current"
    height="180px"
    keyboard
    draggable
    @update:modelValue="update"
  >
    <c-carousel-item v-for="item in 4" :key="item"
      ><div class="carousel-demo-panel">Slide {{ item }}</div></c-carousel-item
    >
  </c-carousel>
</template>
<style scoped>
.carousel-demo-panel {
  display: grid;
  place-items: center;
  height: 100%;
  background: #dbeafe;
  color: #1e3a8a;
}
</style>
```

### Interactive Content

- `height`: Constrains the component height.

Example source: src/carousel/__demos__/interactive-content.vue

```vue
<script setup>
import { ref } from "vue";

const current = ref(1);
const changes = ref(0);
</script>

<template>
  <p>
    Drag the background; inputs retain normal editing. /
    拖动背景切换，输入框保留原生编辑。
  </p>
  <p role="status">Current: {{ current }} · Changes: {{ changes }}</p>
  <c-carousel
    v-model="current"
    class="carousel-interactive-demo"
    height="180px"
    draggable
    touchable
    keyboard
    @change="changes++"
  >
    <c-carousel-item v-for="item in 3" :key="item">
      <div class="carousel-demo-panel">
        <label
          >Slide {{ item }}
          <c-input :aria-label="'Slide ' + item" placeholder="Type here"
        /></label>
      </div>
    </c-carousel-item>
  </c-carousel>
</template>
<style scoped>
.carousel-demo-panel {
  display: grid;
  place-items: center;
  height: 100%;
  background: #dcfce7;
  color: #14532d;
}
input {
  max-width: 150px;
}
</style>
```

## Lifecycle

### Scheduler Lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `auto-play` | Autoplay configuration | Scheduler Lifecycle |
| `move-speed` | Explicit duration in milliseconds | Scheduler Lifecycle |
| `height` | Container height; numbers are px | Scheduler Lifecycle |
| `keyboard` | Scoped arrow/Home/End navigation | Scheduler Lifecycle |
| `mousewheel` | Wheel navigation | Scheduler Lifecycle |
<!-- demo-config-notes:end -->


- `height`: Constrains the component height.

Example source: src/carousel/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref(true)
const mounted = ref(true)
const current = ref(1)
const playing = ref(false)
const moves = ref(0)
</script>
<template>
  <div>
    <c-button @click="playing = !playing">Autoplay / 自动播放</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <p>Current / 当前: {{ current }}; changes / 通知: {{ moves }}. Suspend during autoplay or loop settlement, then activate. Old work must not replay.</p>
    <KeepAlive v-if="mounted">
      <c-carousel v-if="active" v-model="current" :auto-play="playing ? { interval: 1000 } : false" :move-speed="600" :height="180" keyboard mousewheel @change="moves++">
        <c-carousel-item v-for="item in 3" :key="item">Slide / 幻灯片 {{ item }}</c-carousel-item>
      </c-carousel>
    </KeepAlive>
  </div>
</template>
```

## API

### Value and default value

Use ordinary `v-model`. `modelValue` is the current slide number, starting at 1. `defaultValue` initializes uncontrolled state only on creation; later changes do not reset it. An explicit bound value takes precedence. Initialization does not emit `update:modelValue`.

### Carousel Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `model-value` | Controlled one-based slide number | `number` | `undefined` |
| `default-value` | Uncontrolled initial index | `number` | `1` |
| `loop` | Loop without duplicating instances | `boolean` | `true` |
| `auto-play` | Autoplay configuration | `boolean \| number \| CarouselAutoPlayConfig` | `false` |
| `move-speed` | Explicit duration in milliseconds | `number` | `undefined (token)` |
| `trigger` | Indicator trigger | `click \| hover` | `click` |
| `orientation` | Horizontal/vertical axis of carousel sliding, default horizontal; does not determine indicator position | `horizontal \| vertical` | `horizontal` |
| `show-arrow` | Arrow visibility | `always \| hover \| never` | `always` |
| `arrow-class` | Additional arrow class | `string` | `undefined` |
| `indicator` | Show indicators | `boolean` | `true` |
| `indicator-type` | Indicator appearance | `dot \| line \| slider` | `dot` |
| `indicator-position` | Indicator edge or outer region of the carousel container, default bottom. Not a trigger-relative popup placement | `bottom \| top \| left \| right \| outer` | `bottom` |
| `indicator-class` | Additional indicator class | `string` | `undefined` |
| `indicator-color` | Custom indicator background | `string` | `undefined` |
| `height` | Container height; numbers are px | `number \| string` | `undefined` |
| `transition-timing-function` | Explicit timing function | `string` | `undefined (token)` |
| `touchable` | Touch dragging | `boolean` | `true` |
| `draggable` | Mouse dragging, independent of touch | `boolean` | `false` |
| `mousewheel` | Wheel navigation | `boolean` | `false` |
| `keyboard` | Scoped arrow/Home/End navigation | `boolean` | `false` |
| `slides-per-view` | Visible count; auto uses item size | `number \| auto` | `1` |
| `space-between` | Item gap; numbers/numeric strings are px | `number \| string` | `0` |
| `effect` | Effect; all supported by both libraries | `slide \| fade \| card` | `slide` |
| `centered-slides` | Center active slide | `boolean` | `false` |
| `aria-label` | Carousel accessible name | `string` | Locale |
| `previous-button-aria-label` | Previous button accessible name | `string` | Locale |
| `next-button-aria-label` | Next button accessible name | `string` | Locale |

### Model and interaction
Public slide numbers start at 1. Controlled actions emit update:model-value, then change(slideNumber, previousSlideNumber, isManual), and do not move until the parent accepts current. External assignments do not emit change. Method option event:false suppresses only change, not the model proposal. isManual is true for user actions and false for autoplay.

loop moves existing children across boundaries without cloning component instances. Without looping or centering, the final viewport is clamped to avoid empty space; selection can move within the final visible group without moving the track. Partly visible slides remain accessible; fully offscreen slides are inert. fade displays one slide. auto uses explicit CarouselItem width horizontally or height vertically; vertical mode requires a container height. Only CarouselItem children, including those inside Vue Fragments, count as slides; comments and ordinary elements do not.

auto-play=true uses 3000ms and pauses on hover; a number sets milliseconds without hover pausing; an object configures interval/hoverToPause. Focus within, dragging, hidden documents/ancestors and KeepAlive deactivation always pause playback. Reduced-motion preferences are respected. Interactive children such as inputs/buttons keep native behavior; mark custom interactive areas with data-carousel-no-drag. show-arrow=hover also shows arrows on keyboard focus.

### Events
| Event | Arguments |
| --- | --- |
| update:model-value | slideNumber: number |
| change | slideNumber: number, previousSlideNumber: number, isManual: boolean |

### Slots
| Slot | Arguments |
| --- | --- |
| default | CarouselItem |
| prev / next / indicator | { slideNumber, length, hovering, prev, next, to, resize } |

### Methods
| Method | Signature |
| --- | --- |
| prev / next | (options?: CarouselToOptions) => void |
| to | (slideNumber: number, options?: CarouselToOptions) => void |
| resize | () => void |

CarouselItem has no own props, events or methods. Its default slot supplies slide content.

### Types
CarouselProps, CarouselItemProps, CarouselInstance, CarouselItemInstance, CarouselEmits, CarouselSlots, CarouselItemSlots, CarouselExpose, CarouselSlotScope, CarouselToOptions, CarouselChangeData, CarouselOrientation, CarouselEffect, CarouselAutoPlayConfig, CarouselArrowType, CarouselIndicatorType, CarouselIndicatorPosition, CarouselTriggerEvent.

### Style variables

| Token | Default |
| --- | --- |
| `--c-carousel-indicator-dot-size` | `8px` |
| `--c-carousel-indicator-position` | `var(--c-sys-space-4)` |
| `--c-carousel-indicator-gap` | `var(--c-sys-space-3)` |
| `--c-carousel-indicator-color-default` | `rgb(255 255 255 / 35%)` |
| `--c-carousel-indicator-color-active` | `var(--c-sys-color-content-on-dark)` |
| `--c-carousel-indicator-outer-margin-bottom` | `var(--c-sys-space-8)` |
| `--c-carousel-indicator-line-width` | `20px` |
| `--c-carousel-indicator-line-height` | `3px` |
| `--c-carousel-indicator-line-border-radius` | `var(--c-sys-radius-sm)` |
| `--c-carousel-arrow-size` | `var(--c-sys-control-height-md)` |
| `--c-carousel-arrow-font-size` | `var(--c-sys-font-size-xl)` |
| `--c-carousel-arrow-margin` | `var(--c-sys-space-4)` |
| `--c-carousel-arrow-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-carousel-arrow-background` | `rgb(0 0 0 / 35%)` |
| `--c-carousel-arrow-background-hover` | `rgb(0 0 0 / 55%)` |
| `--c-carousel-arrow-disabled-opacity` | `0.4` |
| `--c-carousel-navigation-z-index` | `10` |
| `--c-carousel-transition-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-carousel-transition-timing-function` | `ease` |
| `--c-carousel-fade-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-carousel-card-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-carousel-card-scale` | `0.85` |
| `--c-carousel-card-opacity` | `0.6` |
| `--c-carousel-focus-width` | `2px` |
| `--c-carousel-focus-offset` | `2px` |
| `--c-carousel-focus-color` | `var(--c-sys-color-content-brand)` |

### Loop transition boundaries

Each slide always has one component instance. Ordinary previous/next navigation recycles positions after the departing slide exits. Multi-slide or centered jumps that would require one slide in two positions settle immediately without animation, cloning interactive content or queuing unlimited transitions. Fewer items than visible slides are not cloned to fill space. Accessible names follow global Locale; explicit label props take precedence.

Native root listeners such as `keydown`, `mouseenter`, `mouseleave`, `focusin` and `focusout` run alongside internal navigation and autoplay pause handling. Native `.once` listeners fire once for the root element lifetime.

---

Document: llms/en-US/components/cascader.md

<!-- Source: src/cascader/README.en-US.md; locale: en-US; page: /en/components/cascader/ -->

# Cascader

Hierarchical option selection with single, multiple and path models.

```ts
import type { CascaderProps, CascaderInstance } from "@cedar-design/ui";
```

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes null unchanged; omitted values preserve the existing default. Editors render null as blank without converting ordinary empty-string input to null. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

The candidate `options` prop accepts an array or `(query, { signal }) => array/Promise`. Components own loading, cancellation and stale results, and emit load-error on failure. Choice groups initialize with an empty query; searchable fields load when queries change. Root tree loaders remain independent of existing load-more child loading.

## Reading direction

Inherits source dir. Child columns, expansion icons and separators follow reading direction. Horizontal keys enter loaded children or return to the parent in the visible direction, skipping disabled children; vertical keys retain logical order. Search preserves native horizontal caret editing. Path and multiple-value arrays are not reversed. Clearing the last value while closed resets navigation before reopening.

## Basic examples

### Basic usage

Example source: src/cascader/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader v-model="value" :options="options" placeholder="请选择地区" />
    <p role="status">当前值：{{ value ?? '未选择' }}</p>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import type { CascaderProps } from '@cedar-design/ui'

const value = ref<CascaderProps['modelValue']>()

const options = [
  {
    value: 'beijing',
    label: 'Beijing',
    children: [
      {
        value: 'chaoyang',
        label: 'ChaoYang',
        children: [
          {
            value: 'datunli',
            label: 'Datunli',
          },
        ],
      },
      {
        value: 'haidian',
        label: 'Haidian',
      },
      {
        value: 'dongcheng',
        label: 'Dongcheng',
      },
      {
        value: 'xicheng',
        label: 'Xicheng',
        children: [
          {
            value: 'jinrongjie',
            label: 'Jinrongjie',
          },
          {
            value: 'tianqiao',
            label: 'Tianqiao',
          },
        ],
      },
    ],
  },
  {
    value: 'shanghai',
    label: 'Shanghai',
    children: [
      {
        value: 'huangpu',
        label: 'Huangpu',
      },
    ],
  },
]
</script>
```

## Appearance and states

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                             | Related examples                                   |
| ------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------- |
| `options`     | Tree options; leaf values must be unique in scalar mode; paths distinguish branches | Appearance configuration comparison, Control Sizes |
| `clearable`   | Allow clearing; preserve disabled selections                                        | Appearance configuration comparison, Control Sizes |
| `size`        | Supports all five sizes; inherits group/form settings                               | Control Sizes                                      |
| `variant`     | filled, outline, standard; inherits InputGroup                                      | Control Sizes                                      |
| `placeholder` | Placeholder                                                                         | Control Sizes                                      |
| `multiple`    | Multiple selection; enables search by default                                       | Control Sizes                                      |

<!-- demo-config-notes:end -->

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/cascader/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("shanghai");
const options = [
  {
    label: "华东",
    value: "east",
    children: [
      { label: "上海", value: "shanghai" },
      { label: "杭州", value: "hangzhou" },
    ],
  },
];
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-cascader
      v-model="value"
      :options="options"
      clearable
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-cascader>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Control Sizes

- `size`: The size of the select
- `variant`: Selects the visual variant.
- `options`: Options for cascader
- `placeholder`: Placeholder

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

## Selection modes and paths

### Multiple

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                                                                             | Related examples                    |
| ---------------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
| `options`        | Tree options; leaf values must be unique in scalar mode; paths distinguish branches | Multiple, Check Strictly, Path Mode |
| `placeholder`    | Placeholder                                                                         | Multiple, Check Strictly, Path Mode |
| `multiple`       | Multiple selection; enables search by default                                       | Multiple, Check Strictly            |
| `default-value`  | Default value (uncontrolled state)                                                  | Check Strictly, Path Mode           |
| `expand-trigger` | Menu / List expansion: click or hover                                               | Check Strictly, Path Mode           |
| `check-strictly` | Allow parent selection; unlink parent/child checks                                  | Check Strictly                      |

<!-- demo-config-notes:end -->

- `options`: Options for cascader
- `placeholder`: Placeholder
- `multiple`: Whether it is a multi-selection state (The search is turned on by default in the multi-select mode)

Example source: src/cascader/__demos__/multiple.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." multiple />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
          },
          {
            value: 'haidian',
            label: 'Haidian',
            isLeaf: true,
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
            isLeaf: true,
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
            isLeaf: true,
          },
        ],
      },
    ]
    return {
      options,
    }
  },
})
</script>
```

### Check Strictly

- `options`: Options for cascader
- `placeholder`: Placeholder
- `check-strictly`: Whether to enable strict selection mode
- `default-value`: Default value (uncontrolled state)

Example source: src/cascader/__demos__/check-strictly.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." check-strictly />
    <c-cascader
      :options="options"
      default-value="datunli"
      expand-trigger="hover"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      multiple
      check-strictly />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      options,
    }
  },
})
</script>
```

### Path Mode

- `options`: Options for cascader
- `placeholder`: Placeholder
- `path-mode`: Whether the value is a path
- `default-value`: Default value (uncontrolled state)

Example source: src/cascader/__demos__/path-mode.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader
      :options="options"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      path-mode
      @change="handleChange" />
    <c-cascader
      :options="options"
      default-value="datunli"
      expand-trigger="hover"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      path-mode
      @change="handleChange" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const handleChange = (path: any) => {
      console.log(path)
    }
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      options,
      handleChange,
    }
  },
})
</script>
```

### Clearable

- `options`: Options for cascader
- `placeholder`: Placeholder
- `clearable`: Whether to allow clear

Example source: src/cascader/__demos__/clearable.vue

```vue
<template>
  <c-cascader :options="options" v-model="value" placeholder="Please select ..." clearable />
</template>

<script lang="ts">
import { ref, defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('datunli')

    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      value,
      options,
    }
  },
})
</script>
```

## Search and presentation

### Filterable

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                                                                             | Related examples                         |
| ---------------- | ----------------------------------------------------------------------------------- | ---------------------------------------- |
| `options`        | Tree options; leaf values must be unique in scalar mode; paths distinguish branches | Filterable, Case Sensitive, Format Label |
| `placeholder`    | Placeholder                                                                         | Filterable, Case Sensitive, Format Label |
| `filterable`     | Enable search                                                                       | Filterable, Case Sensitive               |
| `case-sensitive` | Case-sensitive built-in filtering; custom filters take priority                     | Case Sensitive                           |
| `format-label`   | Format selected labels; use label slot for VNodes                                   | Format Label                             |

<!-- demo-config-notes:end -->

- `options`: Options for cascader
- `placeholder`: Placeholder
- `filterable`: Whether to allow searching

Example source: src/cascader/__demos__/filterable.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" placeholder="Please select ..." filterable />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    return {
      options,
    }
  },
})
</script>
```

### Case Sensitive

- `options`: Options for cascader
- `filterable`: Whether to allow searching
- `placeholder`: Placeholder

Example source: src/cascader/__demos__/case-sensitive.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string[]>([])
const caseSensitive = ref(false)
const options = [{ value: 'fruit', label: 'Fruit', children: [{ value: 'apple', label: 'Apple' }] }]
</script>
<template>
  <c-space direction="column" fill>
    <c-space><c-switch v-model="caseSensitive" /><span>区分大小写</span></c-space>
    <c-cascader v-model="value" :options="options" :case-sensitive="caseSensitive" filterable placeholder="输入 fruit、Fruit、apple 或 Apple" />
    <p>保留原有路径标签匹配。启用区分大小写后，输入 fruit 不匹配 Fruit。</p>
  </c-space>
</template>
```

### Format Label

- `options`: Options for cascader
- `placeholder`: Placeholder
- `format-label`: Format display content

Example source: src/cascader/__demos__/format-label.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." :format-label="format" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
            children: [
              {
                value: 'jinrongjie',
                label: 'Jinrongjie',
              },
              {
                value: 'tianqiao',
                label: 'Tianqiao',
              },
            ],
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
          },
        ],
      },
    ]
    interface Option {
      value: string
      label: string
    }

    const format = (options: Option[]) => {
      const labels = options.map((option) => option.label)
      return labels.join('-')
    }
    return {
      options,
      format,
    }
  },
})
</script>
```

## Interaction and control

### Interaction state comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                             | Related examples             |
| ------------- | ----------------------------------------------------------------------------------- | ---------------------------- |
| `options`     | Tree options; leaf values must be unique in scalar mode; paths distinguish branches | Interaction state comparison |
| `clearable`   | Allow clearing; preserve disabled selections                                        | Interaction state comparison |
| `disabled`    | Whether disabled                                                                    | Interaction state comparison |

<!-- demo-config-notes:end -->

Toggle the state, interact with the component, and restore editing using the controls outside the specimen. Error appearance alone does not run validation.

Example source: src/cascader/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("shanghai");
const options = [
  {
    label: "华东",
    value: "east",
    children: [
      { label: "上海", value: "shanghai" },
      { label: "杭州", value: "hangzhou" },
    ],
  },
];
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-cascader
      v-model="value"
      :options="options"
      clearable
      v-bind="__demoState"
    ></c-cascader>
  </c-space>
</template>
```

## Configuration and composition

### Passthrough Options

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration         | Purpose                                                                                                                          | Related examples                         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `edit-mode`           | Presentation                                                                                                                     | Passthrough Options, Copying and editing |
| `options`             | Tree options; leaf values must be unique in scalar mode; paths distinguish branches                                              | Passthrough Options, Copying and editing |
| `trigger-props`       | Menu Trigger props; field owns open state                                                                                        | Passthrough Options                      |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | Copying and editing                      |
| `filterable`          | Enable search                                                                                                                    | Copying and editing                      |

<!-- demo-config-notes:end -->

- `open`: Whether to show the dropdown
- `options`: Options for cascader
- `trigger-props`: Trigger props of the drop-down menu

Example source: src/cascader/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { CascaderTriggerOptions } from "@cedar-design/ui";
const open = ref(false);
const triggerOptions: CascaderTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
  popupContainer: false,
};
const options = [
  {
    value: "fruit",
    label: "水果",
    children: [{ value: "apple", label: "Apple" }],
  },
];
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-cascader
      edit-mode="direct"
      v-model:open="open"
      :options="options"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/cascader/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-cascader
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :filterable="editable"
      :options="[
        { value: 'a', label: 'Alpha' },
        { value: 'b', label: 'Beta' },
      ]"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("a");
</script>
```

## Async loading and value resolution

### Loading

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                             | Related examples                  |
| ------------- | ----------------------------------------------------------------------------------- | --------------------------------- |
| `options`     | Tree options; leaf values must be unique in scalar mode; paths distinguish branches | Loading, Load More, Async Devices |
| `placeholder` | Placeholder                                                                         | Loading, Load More, Async Devices |
| `loading`     | Loading state; blocks selection and confirmation                                    | Loading, Async Devices            |
| `load-more`   | Load children asynchronously; call done(children), or done() to allow retry         | Load More                         |
| `path-mode`   | Return a complete path instead of a node value                                      | Async Devices                     |
| `filterable`  | Enable search                                                                       | Async Devices                     |

<!-- demo-config-notes:end -->

- `options`: Options for cascader
- `placeholder`: Placeholder
- `loading`: Whether it is loading state

Example source: src/cascader/__demos__/loading.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="[]" :style="{ width: '320px' }" placeholder="Please select ..." loading />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### Load More

- `options`: Options for cascader
- `placeholder`: Placeholder
- `load-more`: Data lazy loading function, open the lazy loading function when it is passed in

Example source: src/cascader/__demos__/load-more.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-cascader :options="options" :style="{ width: '320px' }" placeholder="Please select ..." :load-more="loadMore" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
          },
          {
            value: 'haidian',
            label: 'Haidian',
            isLeaf: true,
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
            isLeaf: true,
          },
          {
            value: 'xicheng',
            label: 'Xicheng',
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'huangpu',
            label: 'Huangpu',
            isLeaf: true,
          },
        ],
      },
    ]
    const loadMore = (option: any, done: any) => {
      window.setTimeout(() => {
        const nodes = [
          {
            value: `${option.value}-option1`,
            label: `${option.label}-Option1`,
            isLeaf: true,
          },
          {
            value: `${option.value}-option2`,
            label: `${option.label}-Option2`,
            isLeaf: true,
          },
        ]
        done(nodes)
      }, 2000)
    }

    return {
      options,
      loadMore,
    }
  },
})
</script>
```

### Async Devices

- `options`: Options for cascader
- `loading`: Whether it is loading state
- `path-mode`: Whether the value is a path
- `filterable`: Whether to allow searching

Example source: src/cascader/__demos__/async-devices.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(['factory', 'device-2'])
const options = ref<Record<string, unknown>[]>([])
const loading = ref(false)
async function load() {
  loading.value = true
  try {
    options.value = await Promise.resolve([
      { id: 'factory', name: '工厂', nodes: [
        { id: 'device-1', name: '设备一' },
        { id: 'device-2', name: '设备二' },
        { id: 'device-3', name: '检修设备', disabled: true },
      ] },
    ])
  } finally { loading.value = false }
}
</script>
<template>
  <c-space direction="column" :size="16">
    <c-button @click="load">加载设备树</c-button>
    <c-cascader v-model="value" :options="options" :loading="loading" path-mode filterable clearable
      :field-names="{ label: 'name', value: 'id', children: 'nodes' }" placeholder="选择设备路径" />
    <p>已提交路径：{{ value }}。标签与 ID 分离，异步加载后自动回显。</p>
  </c-space>
</template>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Cascader props

Use `v-model`, `v-model:open` and `v-model:input-value` for controlled state. Clear values are `''` for single selection and `[]` for multiple selection. Select uses `undefined` when an actual empty-string option exists.

| Prop                                    | Description                                                                                                                                      | Type                                                          | Default                         |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | ------------------------------- |
| `open-trigger-target`                   | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available.                 | `'field' \| 'icon'`                                           | `'field'`                       |
| `model-value / default-value`           | Controlled value / uncontrolled initial value                                                                                                    | `Value`                                                       | `Single: ''; multiple: []`      |
| `open / default-open`                   | Controlled / initial open state                                                                                                                  | `boolean`                                                     | `undefined / false`             |
| `input-value / default-input-value`     | Search text, independent of selected values                                                                                                      | `string`                                                      | `undefined / ''`                |
| `multiple`                              | Multiple selection; enables search by default                                                                                                    | `boolean`                                                     | `false`                         |
| `size`                                  | Supports all five sizes; inherits group/form settings                                                                                            | `ComponentSize`                                               | `md`                            |
| `variant`                               | filled, outline, standard; inherits InputGroup                                                                                                   | `FormControlVariant`                                          | `filled`                        |
| `disabled / readonly / error`           | Inherits form state unless explicitly overridden                                                                                                 | `boolean`                                                     | `undefined`                     |
| `placeholder`                           | Placeholder                                                                                                                                      | `string`                                                      | `—`                             |
| `hint / line`                           | Floating hint / standard variant underline                                                                                                       | `boolean`                                                     | `true`                          |
| `text-color / focus-color / blur-color` | Field colors                                                                                                                                     | `string`                                                      | `—`                             |
| `loading`                               | Loading state; blocks selection and confirmation                                                                                                 | `boolean`                                                     | `false`                         |
| `show-tags`                             | Show tags; false displays separated text                                                                                                         | `boolean`                                                     | `true`                          |
| `separator`                             | Separator when show-tags=false                                                                                                                   | `string`                                                      | `,`                             |
| `text-align`                            | Text alignment: left / center / right. Inherits FormItem content-align when unset; standalone fields default to inline start                             | `'left' \| 'center' \| 'right'`                               | `-`                             |
| `max-tag-count`                         | Maximum visible tags; 0 means unlimited                                                                                                          | `number`                                                      | `0`                             |
| `tag-nowrap`                            | Keep tags on one line with ellipsis and preserved removal icons; overflow scrolls horizontally; hover, focus or tap truncated text to preview it | `boolean`                                                     | `false`                         |
| `popup-container`                       | Selector, element, element resolver, or false for inline rendering                                                                               | `PopupContainer`                                              | `—`                             |
| `trigger-props`                         | Menu Trigger props; field owns open state                                                                                                        | `TriggerProps`                                                | `—`                             |
| `virtual-list-props`                    | Pass the virtual list attribute, pass in this parameter to turn on virtual scrolling [VirtualListProps](#VirtualListProps)                       | `VirtualListProps`                                            | `—`                             |
| `search-delay`                          | Search debounce delay in ms                                                                                                                      | `number`                                                      | `500`                           |
| `format-label`                          | Format selected labels; use label slot for VNodes                                                                                                | `function`                                                    | `—`                             |
| `clearable`                             | Allow clearing; preserve disabled selections                                                                                                     | `boolean`                                                     | `false`                         |
| `options`                               | Tree options; leaf values must be unique in scalar mode; paths distinguish branches                                                              | `CascaderOption[]` / `(query, { signal }) => Array / Promise` | `undefined`                     |
| `field-names`                           | Map value, label, disabled, children, isLeaf, tagProps, render                                                                                   | `CascaderFieldNames`                                          | `—`                             |
| `path-mode`                             | Return a complete path instead of a node value                                                                                                   | `boolean`                                                     | `false`                         |
| `check-strictly`                        | Allow parent selection; unlink parent/child checks                                                                                               | `boolean`                                                     | `false`                         |
| `filterable`                            | Enable search                                                                                                                                    | `boolean`                                                     | `Single: false; multiple: true` |
| case-sensitive                          | Case-sensitive built-in filtering; custom filters take priority                                                                                  | boolean                                                       | false                           |
| `filter-option`                         | Receives query and raw node                                                                                                                      | `(input, option) => boolean`                                  | `—`                             |
| `expand-trigger`                        | Menu / List expansion: click or hover                                                                                                            | `string`                                                      | `click`                         |
| `expand-child`                          | Expand to first child                                                                                                                            | `boolean`                                                     | `false`                         |
| `load-more`                             | Load children asynchronously; call done(children), or done() to allow retry                                                                      | `(option, done) => void`                                      | `—`                             |
| `fallback-option`                       | Display unresolved values                                                                                                                        | `boolean or (value) => string`                                | `true`                          |
| `search-option-only-label`              | Show node label only in search results                                                                                                           | `boolean`                                                     | `false`                         |
| `auto-fit-popup-width`                  | Match Menu width to field                                                                                                                        | `boolean`                                                     | `false`                         |
| `edit-mode`                             | Presentation                                                                                                                                     | `menu`                                                        | `menu`                          |

### Events and methods

- `update:modelValue`, `change(value)`: emitted on commit, not while editing a draft.
- `update:open`, `open-change(open)`: request an expanded-state change.
- `update:inputValue`, `input-value-change(text)`, `search(text)`: search state.
- `focus(event)`, `blur(event)`, `clear(event)`: native field events; only the field owner notifies Form.
- Methods: `focus()`, `blur()`.

### Slots and option data

Use `label({ data })` for custom `selected` labels; `selected` replaces the whole selection area. Also supports `prefix`, `suffix`, `clear-icon({ clear })`, `arrow-icon`, `loading-icon`, `search-icon`, `empty`, and `option({ data })`.

Option `label` is searchable plain text. Use `render` or the `option` slot for custom `option` content, and `format-label` or `label` slot for selected content. Values identify selections; labels never do. `disabled` blocks selection/removal, and `tagProps` customizes selected tags.

### `<CascaderPanel>` Props

| Parameter                 | Description                                                                                                      | Type                                                                                                                                                               |         Default         |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------: |
| path-mode                 | Return a complete path instead of a node value                                                                   | `boolean`                                                                                                                                                          |         `false`         |
| multiple                  | Multiple selection; enables search by default                                                                    | `boolean`                                                                                                                                                          |         `false`         |
| model-value **(v-model)** | Bound value                                                                                                      | `string\| number\| Record<string, any>\| (    \| string    \| number    \| Record<string, any>    \| (string \| number \| Record<string, any>)[]  )[]\| undefined` |           `-`           |
| default-value             | Default value (uncontrolled state)                                                                               | `string\| number\| Record<string, any>\| (    \| string    \| number    \| Record<string, any>    \| (string \| number \| Record<string, any>)[]  )[]\| undefined` | `'' \| undefined \| []` |
| options                   | Tree options; leaf values must be unique in scalar mode; paths distinguish branches                              | `CascaderOption[]` / `(query, { signal }) => Array / Promise`                                                                                                      |       `undefined`       |
| expand-trigger            | Menu / List expansion: click or hover                                                                            | `string`                                                                                                                                                           |        `'click'`        |
| check-strictly            | Allow parent selection; unlink parent/child checks                                                               | `boolean`                                                                                                                                                          |         `false`         |
| load-more                 | Load children asynchronously; call done(children), or done() to allow retry                                      | `(  option: CascaderOption,  done: (children?: CascaderOption[]) => void) => void`                                                                                 |           `-`           |
| field-names               | Customize fields in `CascaderOption`; when option `value` is an object, `value` is also used as the key property | `CascaderFieldNames`                                                                                                                                               |           `-`           |
| expand-child              | Expand to first child                                                                                            | `boolean`                                                                                                                                                          |         `false`         |

### `<CascaderPanel>` Events

| Event  | Description                             | Arguments                                                                              |
| ------ | --------------------------------------- | -------------------------------------------------------------------------------------- |
| change | Emitted when the selected value changes | value: `string \| number \| (string \| number \| (string \| number)[])[] \| undefined` |

### `<CascaderPanel>` Slots

| Slot  |                   Description                   | Arguments |
| ----- | :---------------------------------------------: | --------- |
| empty | Content displayed when no options are available | -         |

### CascaderOption

| Parameter | Description                           | Type                                      | Default |
| --------- | ------------------------------------- | ----------------------------------------- | :-----: |
| value     | Option value                          | `string \| number \| Record<string, any>` |   `-`   |
| label     | Option text                           | `string`                                  |   `-`   |
| render    | Custom render function                | `RenderFunction`                          |   `-`   |
| disabled  | Whether disabled                      | `boolean`                                 | `false` |
| tagProps  | Property used for the displayed label | `TagProps`                                |   `-`   |
| children  | Child options                         | `CascaderOption[]`                        |   `-`   |
| isLeaf    | Whether this is a leaf node           | `boolean`                                 | `false` |

## Type definitions

The component exports the following types

```ts
import type { CascaderProps } from "@cedar-design/ui";
```

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

Field editing uses edit-mode: Cedar supports direct/click/dblclick, and Maple supports direct/popup. The old menu/list/picker editing values are not retained. Popup editors reuse the existing option index, search, asynchronous loading and virtual-list algorithms.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

### Single-selection checkmark variables

| Variable                        | Default                             |
| ------------------------------- | ----------------------------------- |
| `--c-cascader-item-check-color` | `var(--c-sys-color-action-primary)` |
| `--c-cascader-item-check-size`  | `var(--c-sys-font-size-md)`         |

### Built-in search fields

`searchFields` / `search-fields` is a readonly `('label' | 'value')[]`, defaulting to `['label']`. Multiple fields use OR matching, case-insensitive by default. `['value', 'label']` searches codes and names; fieldNames maps semantic fields to business fields. An empty array matches no items for a nonempty query. Values are compared as strings; object traversal, object values and pinyin matching require a custom callback. A custom callback takes precedence and decides case handling itself. Remote results use the existing protocol for disabling local filtering. Cascader retains path semantics and checks the configured fields on each path node.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

The `options` prop accepts an array or `(query, { signal }) => array/Promise`. The component manages loading, cancellation and stale-result isolation; failures emit load-error. Single/multiple groups initialize with an empty-string query, searchable fields reload when the query changes, and root loading for tree fields remains independent of existing load-more child loading.

---

Document: llms/en-US/components/checkbox.md

<!-- Source: src/checkbox/README.en-US.md; locale: en-US; page: /en/components/checkbox/ -->

# Checkbox

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Reading direction

Checkbox labels and groups follow source dir without reversing value arrays. Space keeps its toggle meaning; disabled and readonly behavior remains effective. Changing direction does not select or clear options.

## Basic examples

### Basic usage

Preview configuration: `value="1"`.

Example source: src/checkbox/__demos__/basic.vue

```vue
<template>
  <c-checkbox value="1">Option 1</c-checkbox>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

## Groups and layout

### Option declaration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                   | Related examples                    |
| ------------- | --------------------------------------------------------- | ----------------------------------- |
| `value`       | Option identifier in array/group mode                     | Option declaration comparison, Grid |
| `disabled`    | Disabled state; inherits from the form/group when omitted | Grid                                |

<!-- demo-config-notes:end -->

Compare child-component declarations with options data. Both use a group model; field mapping and asynchronous data are separate.

Example source: src/checkbox/__demos__/group-declaration-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


    const value1 = ref(['Plain 1'])


    const plainOptions = ['Plain 1', 'Plain 2', 'Plain 3']



    const value2 = ref(['1'])


    const options = [
      { label: 'Option 1', value: '1' },
      { label: 'Option 2', value: '2' },
      { label: 'Option 3', value: '3', disabled: true },
    ]
return { value1, plainOptions, value2, options }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="checkbox-group">
    <h4><span lang="zh-CN">复选框组</span><span lang="en-US">checkbox group</span></h4>
    <c-space direction="column" size="lg">
        <c-checkbox-group :default-value="['1']">
          <c-checkbox value="1">Option 1</c-checkbox>
          <c-checkbox value="2">Option 2</c-checkbox>
          <c-checkbox value="3">Option 3</c-checkbox>
        </c-checkbox-group>
        <c-checkbox-group orientation="vertical">
          <c-checkbox value="1">Option 1</c-checkbox>
          <c-checkbox value="2">Option 2</c-checkbox>
          <c-checkbox value="3">Option 3</c-checkbox>
        </c-checkbox-group>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="checkbox-group-options">
    <h4><span lang="zh-CN">复选框组选项</span><span lang="en-US">checkbox group options</span></h4>
    <c-space direction="column" size="lg">
        <c-checkbox-group v-model="scene2.value1" :options="scene2.plainOptions"> </c-checkbox-group>
        <c-checkbox-group v-model="scene2.value2" :options="scene2.options"> </c-checkbox-group>
        <c-checkbox-group v-model="scene2.value2" :options="scene2.options">
          <template #label="{ data }">
            <c-tag>{{ data.label }}</c-tag>
          </template>
        </c-checkbox-group>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Grid

- `disabled`: Prevents user interaction.

Example source: src/checkbox/__demos__/grid.vue

```vue
<template>
  <c-checkbox-group v-model="checkedValue">
    <c-grid :cols="3" :colGap="24" :rowGap="16">
      <c-grid-item>
        <c-checkbox value="1">Option 1</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="2" disabled>Option 2</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="3">Option 3</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="4">Option 4</c-checkbox>
      </c-grid-item>
      <c-grid-item>
        <c-checkbox value="5">Option 5</c-checkbox>
      </c-grid-item>
    </c-grid>
  </c-checkbox-group>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const checkedValue = ref(['1', '2'])

    return {
      checkedValue,
    }
  },
})
</script>
```

### Group State

Preview configuration: `:default-value="['a']"`, `:options="options"`, `:readonly="readonly"`, `:model-value="[]"`.

Example source: src/checkbox/__demos__/group-state.vue

```vue
<script setup>
import { ref } from 'vue'

const accepted = ref(['a'])
const proposed = ref([])
const readonly = ref(false)
const options = [{ label: '设备 A', value: 'a' }, { label: '设备 B', value: 'b' }]
</script>

<template>
  <c-space direction="column">
    <div>
      <p>非受控：default-value 只用于初始值</p>
      <c-checkbox-group :default-value="['a']" :options="options" />
    </div>
    <div>
      <p>受控：父级接受更新 {{ accepted }}</p>
      <c-checkbox-group v-model="accepted" :options="options" :readonly="readonly" />
      <c-button size="sm" @click="readonly = !readonly">{{ readonly ? '解除只读' : '设为只读' }}</c-button>
    </div>
    <div>
      <p>父级拒绝更新：仅记录提议 {{ proposed }}</p>
      <c-checkbox-group :model-value="[]" :options="options" @update:model-value="proposed = $event" />
    </div>
  </c-space>
</template>
```

## Options and value model

### Control Value

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                   | Related examples               |
| --------------- | --------------------------------------------------------- | ------------------------------ |
| `default-value` | Initial uncontrolled value                                | Control Value, Controlled Mode |
| `value`         | Option identifier in array/group mode                     | Control Value                  |
| `readonly`      | Readonly state; inherits from the form/group when omitted | Control Value                  |
| `disabled`      | Disabled state; inherits from the form/group when omitted | Control Value                  |

<!-- demo-config-notes:end -->

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/checkbox/__demos__/control-value.vue

```vue
<script setup>
import { ref } from 'vue'
const control = ref()
const value = ref(false)
const selected = ref([0])
</script>
<template>
  <c-space direction="column">
    <p>布尔模型始终返回布尔值；数组模型用 value 标识选项。 当前值：{{ value }}</p>
    <c-checkbox ref="control" v-model="value">启用通知</c-checkbox>
    <c-space wrap>
      <c-button size="sm" @click="control?.toggle()">切换选择</c-button>
      <c-button size="sm" @click="control?.focus()">聚焦</c-button>
      <c-button size="sm" @click="value = false">重置</c-button>
    </c-space>
    <p>数组模型：{{ selected }}</p>
    <c-checkbox v-model="selected" :value="0">数值 0</c-checkbox>
    <c-checkbox v-model="selected" :value="false">布尔 false</c-checkbox>
    <p>只读允许聚焦，禁用不允许操作；Enter/空格只影响当前控件。</p>
    <c-checkbox :default-value="true" readonly>只读</c-checkbox>
    <c-checkbox :default-value="true" disabled>禁用</c-checkbox>
  </c-space>
</template>
```

### Option Data

Preview configuration: `:options="options"`, `:field-names="fields"`, `orientation="vertical"`, `:options="renderOptions"`.

Example source: src/checkbox/__demos__/option-data.vue

```vue
<script setup lang="ts">
import { h, ref } from 'vue'

const value = ref<Array<string | number | boolean>>(['locked'])
const fields = { value: 'id', label: 'name', disabled: 'unavailable', readonly: 'locked' }
const options = ref([
  { id: false, name: '布尔 false' },
  { id: 0, name: '数字 0' },
  { id: '', name: '空字符串' },
  { id: 'locked', name: '只读选项', locked: true },
  { id: 'disabled', name: '禁用选项', unavailable: true },
])
const renderOptions = [
  { value: 'render', label: (_data: unknown, checked: boolean) => h('strong', checked ? '已选择' : '渲染函数标签') },
]
</script>

<template>
  <section class="option-demo">
    <p>字段映射与标签插槽；只读可聚焦，禁用不可操作。</p>
    <c-checkbox-group v-model="value" :options="options" :field-names="fields" orientation="vertical">
      <template #label="{ data, checked }">{{ data.label }} {{ checked ? '✓' : '' }}</template>
    </c-checkbox-group>
    <p>当前值：{{ JSON.stringify(value) }}</p>
    <c-button @click="value = []">清空</c-button>
    <p>标签也支持渲染函数；不传 options 时使用默认插槽，传入 [] 时保持空组。</p>
    <c-checkbox-group :options="renderOptions" />
  </section>
</template>

<style scoped>
.option-demo { display: flex; flex-direction: column; gap: 12px; }
.option-demo p { margin: 0; }
</style>
```

### Controlled Mode

Preview configuration: `:model-value="true"`, `:model-value="checked2"`, `:default-value="true"`.

Example source: src/checkbox/__demos__/controlled-mode.vue

```vue
<template>
  <c-space wrap size="lg">
    <c-checkbox v-model="checked1">v-model</c-checkbox>
    <c-checkbox :model-value="true">binding value</c-checkbox>
    <c-checkbox :model-value="checked2">binding value2</c-checkbox>
    <c-checkbox :default-value="true">uncontrolled state</c-checkbox>
  </c-space>
  <div :style="{ marginTop: '20px' }">
    <c-button status="primary" @click="handleSetCheck">
      {{ checked2 ? "uncheck" : "check" }} value2
    </c-button>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from "vue";
export default defineComponent({
  setup() {
    const checked1 = ref(false);
    const checked2 = ref(false);

    const handleSetCheck = () => {
      checked2.value = !checked2.value;
    };

    return {
      checked1,
      checked2,
      handleSetCheck,
    };
  },
});
</script>
```

## Selection and bulk actions

### Max Checked

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                   | Related examples                          |
| --------------- | --------------------------------------------------------- | ----------------------------------------- |
| `value`         | Option identifier in array/group mode                     | Max Checked, Checked All Indeterminate    |
| `disabled`      | Disabled state; inherits from the form/group when omitted | Max Checked, Interaction state comparison |
| `indeterminate` | Whether to display an indeterminate state                 | Checked All Indeterminate                 |
| `readonly`      | Readonly state; inherits from the form/group when omitted | Interaction state comparison              |
| `error`         | Error state; inherits from the form/group when omitted    | Interaction state comparison              |

<!-- demo-config-notes:end -->

- `disabled`: Prevents user interaction.

Example source: src/checkbox/__demos__/max-checked.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-checkbox-group :max="2" v-model="value1" :options="plainOptions" />
    <c-checkbox-group :max="2" :default-value="['1']">
      <c-checkbox value="1" disabled>Option 1</c-checkbox>
      <c-checkbox value="2">Option 2</c-checkbox>
      <c-checkbox value="3">Option 3</c-checkbox>
      <c-checkbox value="4">Option 4</c-checkbox>
    </c-checkbox-group>
  </c-space>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value1 = ref(['Plain 1'])
    const plainOptions = ['Plain 1', 'Plain 2', 'Plain 3', 'Plain 4']

    return {
      plainOptions,
      value1,
    }
  },
})
</script>
```

### Checked All Indeterminate

Preview configuration: `:model-value="checkedAll"`, `:indeterminate="indeterminate"`, `value="1"`, `value="2"`.

Example source: src/checkbox/__demos__/checked-all-indeterminate.vue

```vue
<template>
  <c-space direction="column">
    <c-checkbox :model-value="checkedAll" :indeterminate="indeterminate" @change="handleChangeAll">Check All </c-checkbox>
    <c-checkbox-group v-model="data" @change="handleChange">
      <c-checkbox value="1">Option 1</c-checkbox>
      <c-checkbox value="2">Option 2</c-checkbox>
      <c-checkbox value="3">Option 3</c-checkbox>
    </c-checkbox-group>
  </c-space>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const indeterminate = ref(false)
    const checkedAll = ref(false)
    const data = ref<string[]>([])

    const handleChangeAll = (value) => {
      indeterminate.value = false
      if (value) {
        checkedAll.value = true
        data.value = ['1', '2', '3']
      } else {
        checkedAll.value = false
        data.value = []
      }
    }

    const handleChange = (values) => {
      if (values.length === 3) {
        checkedAll.value = true
        indeterminate.value = false
      } else if (values.length === 0) {
        checkedAll.value = false
        indeterminate.value = false
      } else {
        checkedAll.value = false
        indeterminate.value = true
      }
    }

    return {
      indeterminate,
      checkedAll,
      data,
      handleChangeAll,
      handleChange,
    }
  },
})
</script>
```

### Group Methods

Preview configuration: `:options="reverse ? [...options].reverse() : options"`, `:max="4"`, `orientation="vertical"`.

Example source: src/checkbox/__demos__/group-methods.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { CheckboxGroupInstance } from '@cedar-design/ui'

const group = ref<CheckboxGroupInstance>()
const value = ref<Array<string | number | boolean>>(['remote', 'locked', 'a'])
const reverse = ref(false)
const proposal = ref<Array<string | number | boolean>>([])
const options = [
  { value: 'a', label: '任务 A' },
  { value: 'b', label: '任务 B' },
  { value: 'c', label: '任务 C' },
  { value: 'locked', label: '只读，保留选择', readonly: true },
  { value: 'disabled', label: '禁用，不参与操作', disabled: true },
]
</script>

<template>
  <section class="group-methods-demo">
    <p>最多选择 4 项（包含未加载的 remote）。全选/反选保留只读和未加载的已选值。</p>
    <c-checkbox-group ref="group" v-model="value" :options="reverse ? [...options].reverse() : options" :max="4" orientation="vertical" />
    <c-space wrap>
      <c-button @click="proposal = group?.checkAll() ?? []">全选</c-button>
      <c-button @click="proposal = group?.inverseAll() ?? []">反选</c-button>
      <c-button @click="reverse = !reverse">调整选项顺序</c-button>
    </c-space>
    <p>当前值：{{ JSON.stringify(value) }}</p>
    <p>方法返回值：{{ JSON.stringify(proposal) }}</p>
  </section>
</template>

<style scoped>
.group-methods-demo { display: flex; flex-direction: column; gap: 12px; }
.group-methods-demo p { margin: 0; }
</style>
```

### Interaction state comparison

Toggle the state, interact with the component, and restore editing using the controls outside the specimen. Error appearance alone does not run validation.

Example source: src/checkbox/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(false);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-checkbox v-model="value" v-bind="__demoState">同意条款</c-checkbox>
  </c-space>
</template>
```

## Control and slot customization

### Native Control

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                   | Related examples |
| --------------- | --------------------------------------------------------- | ---------------- |
| `name`          | Native field name; inherits from Group when omitted       | Native Control   |
| `indeterminate` | Whether to display an indeterminate state                 | Native Control   |
| `aria-label`    | Accessible name when no visible label exists              | Native Control   |
| `default-value` | Initial uncontrolled value                                | Native Control   |
| `readonly`      | Readonly state; inherits from the form/group when omitted | Native Control   |
| `disabled`      | Disabled state; inherits from the form/group when omitted | Native Control   |

<!-- demo-config-notes:end -->

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/checkbox/__demos__/native-control.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
const choices = ref(['read'])
</script>
<template>
  <div class="checkbox-native-demo">
    <p>按 Tab 聚焦，按空格或 Enter 切换。禁用项跳过，只读项可聚焦。</p>
    <c-checkbox v-model="value" name="agreement">接受协议：{{ value ? '已接受' : '未接受' }}</c-checkbox>
    <c-checkbox indeterminate aria-label="部分选中" />
    <c-checkbox :default-value="true" readonly>只读已选</c-checkbox>
    <c-checkbox disabled>禁用</c-checkbox>
    <c-checkbox error>错误状态</c-checkbox>
    <c-checkbox-group v-model="choices" name="permissions" aria-label="权限" :max="2" :options="[{ label: '读取', value: 'read' }, { label: '编辑', value: 'edit' }, { label: '管理', value: 'admin' }]" />
    <p>最多选择两项：{{ choices.join(', ') }}</p>
  </div>
</template>
<style scoped>
.checkbox-native-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.checkbox-native-demo p { margin: 0; }
</style>
```

### Checked Custom

Preview configuration: `:default-value="['1']"`, `value="1"`, `:model-value="checked"`, `value="2"`.

Example source: src/checkbox/__demos__/checked-custom.vue

```vue
<template>
  <c-checkbox-group :default-value="['1']">
    <c-checkbox value="1">
      <template #checkbox="{ checked }">
        <c-tag :model-value="checked">This is a tag checkbox 1</c-tag>
      </template>
    </c-checkbox>
    <c-checkbox value="2">
      <template #checkbox="{ checked }">
        <c-tag :model-value="checked">This is a tag checkbox 2</c-tag>
      </template>
    </c-checkbox>
    <c-checkbox value="3">
      <template #checkbox="{ checked }">
        <c-tag :model-value="checked">This is a tag checkbox 3</c-tag>
      </template>
    </c-checkbox>
  </c-checkbox-group>

  <div :style="{ marginTop: '20px' }">
    <c-checkbox-group :default-value="[1]">
      <template v-for="item in 2" :key="item">
        <c-checkbox :value="item">
          <template #checkbox="{ checked }">
            <c-space wrap align="flex-start" class="custom-checkbox-card" :class="{ 'custom-checkbox-card-checked': checked }">
              <div class="custom-checkbox-card-mask">
                <div class="custom-checkbox-card-mask-dot" />
              </div>
              <div>
                <div class="custom-checkbox-card-title">Checkbox Card {{ item }}</div>
                <span>this is a text</span>
              </div>
            </c-space>
          </template>
        </c-checkbox>
      </template>
    </c-checkbox-group>
  </div>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>

<style scoped>
.custom-checkbox-card {
  padding: 10px 16px;
  border: 1px solid var(--color-border-2);
  border-radius: 4px;
  width: 250px;
  box-sizing: border-box;
}

.custom-checkbox-card-mask {
  height: 14px;
  width: 14px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  border-radius: 2px;
  border: 1px solid var(--color-border-2);
  box-sizing: border-box;
}

.custom-checkbox-card-mask-dot {
  width: 8px;
  height: 8px;
  border-radius: 2px;
}

.custom-checkbox-card-title {
  color: var(--color-text-1);
  font-size: 14px;
  font-weight: bold;
  margin-bottom: 8px;
}

.custom-checkbox-card:hover,
.custom-checkbox-card-checked,
.custom-checkbox-card:hover .custom-checkbox-card-mask,
.custom-checkbox-card-checked .custom-checkbox-card-mask {
  border-color: rgb(var(--primary-6));
}

.custom-checkbox-card-checked {
  background-color: var(--color-primary-light-1);
}

.custom-checkbox-card:hover .custom-checkbox-card-title,
.custom-checkbox-card-checked .custom-checkbox-card-title {
  color: rgb(var(--primary-6));
}

.custom-checkbox-card-checked .custom-checkbox-card-mask-dot {
  background-color: rgb(var(--primary-6));
}
</style>
```

### Custom Control

Preview configuration: `:icon-size="28"`, `checked-color="#137547"`, `unchecked-color="#656565"`, `icon-size="1.5rem"`.

Example source: src/checkbox/__demos__/custom-control.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const checked = ref(true)
</script>
<template>
  <div class="checkbox-custom-demo">
    <c-checkbox v-model="checked" :icon-size="28" checked-color="#137547" unchecked-color="#656565">数字尺寸（px）与实例颜色</c-checkbox>
    <c-checkbox icon-size="1.5rem" :ripple="false">CSS 长度尺寸，无波纹</c-checkbox>
    <c-checkbox v-model="checked">
      <template #checked-icon><span class="checkbox-custom-icon" aria-hidden="true">✓</span></template>
      <template #unchecked-icon><span class="checkbox-custom-icon" aria-hidden="true">○</span></template>
      自定义图标，仍保留原生键盘与无障碍语义
    </c-checkbox>
    <c-checkbox-group :default-value="['a']" :options="[{ label: '方案 A', value: 'a' }, { label: '方案 B', value: 'b' }]">
      <template #checkbox="{ checked: selected }"><span class="checkbox-custom-icon">{{ selected ? '✓' : '○' }}</span></template>
    </c-checkbox-group>
  </div>
</template>
<style scoped>
.checkbox-custom-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.checkbox-custom-icon { display: inline-flex; justify-content: center; align-items: center; width: 28px; height: 28px; border: 1px solid currentColor; border-radius: 4px; }
</style>
```

## Async options

### Async Options

Preview configuration: `edit-mode="direct"`, `:options="options"`, `:max="2"`.

Example source: src/checkbox/__demos__/async-options.vue

```vue
<script setup>
import { onDeactivated, onUnmounted, ref, shallowRef } from "vue";

const value = ref(["remote"]);
const options = ref([]);
const loading = ref(false);
let pendingTimer;
const manual = ref(false);
const waiting = shallowRef([]);
const applied = ref(0);
const ignored = ref(0);
const changeCount = ref(0);
let version = 0;
let sequence = 0;

function cancelPending() {
  version++;
  if (pendingTimer !== undefined) {
    clearTimeout(pendingTimer);
  }
  pendingTimer = undefined;
  loading.value = false;
}

function load() {
  cancelPending();
  loading.value = true;
  const ticket = version;
  const id = ++sequence;
  const complete = () => {
    if (ticket !== version) {
      ignored.value++;
      return;
    }
    applied.value = id;
    options.value = [
      { label: "异步设备", value: "remote" },
      { label: "设备 A", value: "a" },
      { label: "设备 B", value: "b" },
      { label: "停用设备", value: "locked", disabled: true },
    ];
    pendingTimer = undefined;
    loading.value = false;
  };
  if (manual.value) {
    new Promise((resolve) => {
      waiting.value = [...waiting.value, { id, resolve }];
    }).then(complete);
  } else {
    pendingTimer = setTimeout(complete, 800);
  }
}

function settle(latest) {
  const jobs = [...waiting.value];
  const job = latest ? jobs.pop() : jobs.shift();
  waiting.value = jobs;
  job?.resolve();
}

function cleanup() {
  cancelPending();
  const jobs = waiting.value;
  waiting.value = [];
  jobs.forEach((job) => job.resolve());
}

function remove() {
  cancelPending();
  options.value = [];
}

onDeactivated(cleanup);
onUnmounted(cleanup);
</script>

<template>
  <c-space class="checkbox-async-demo" direction="column">
    <p>业务值独立于当前选项，加载或移除选项不会清空已选值：{{ value }}</p>
    <c-checkbox v-model="manual" edit-mode="direct" @change="remove"
      >Manual responses / 手动返回</c-checkbox
    >
    <c-space wrap>
      <c-button size="sm" @click="load">加载选项</c-button>
      <c-button size="sm" @click="remove">移除选项</c-button>
      <c-button
        size="sm"
        :disabled="waiting.length === 0"
        @click="settle(false)"
        >返回最早加载</c-button
      >
      <c-button size="sm" :disabled="waiting.length === 0" @click="settle(true)"
        >返回最新加载</c-button
      >
    </c-space>
    <p aria-live="polite">
      {{
        loading
          ? "加载中，可在完成前移除选项以取消本次加载。"
          : "加载完成后保留当前选值和键盘焦点。"
      }}
    </p>
    <c-checkbox-group
      v-model="value"
      edit-mode="direct"
      :options="options"
      :max="2"
      @change="changeCount++"
    />
    <p>用户变更次数：{{ changeCount }}</p>
    <p role="status">
      Applied: {{ applied }} · Ignored: {{ ignored }} · Pending:
      {{ waiting.length }}
    </p>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

`ChoiceValue = string | number | boolean`；`CheckboxModel = boolean | ChoiceValue[]`；`RadioModel = ChoiceValue | null`。

### Checkbox Props

| Prop                   | Description                                                     | Type                     | Default   |
| ---------------------- | --------------------------------------------------------------- | ------------------------ | --------- |
| model-value (v-model)  | Controlled value                                                | boolean \| ChoiceValue[] | undefined |
| default-value          | Initial uncontrolled value                                      | boolean \| ChoiceValue[] | false     |
| value                  | Option identifier in array/group mode                           | string\|number\|boolean  | true      |
| disabled               | Disabled state; inherits from the form/group when omitted       | boolean                  | undefined |
| readonly               | Readonly state; inherits from the form/group when omitted       | boolean                  | undefined |
| error                  | Error state; inherits from the form/group when omitted          | boolean                  | undefined |
| indeterminate          | Whether to display an indeterminate state                       | boolean                  | false     |
| checked-color          | Instance checked color; error/disabled states take precedence   | string                   | undefined |
| unchecked-color        | Instance unchecked color; error/disabled states take precedence | string                   | undefined |
| icon-size              | Numbers are px; strings are CSS lengths                         | number \| string         | undefined |
| ripple                 | Whether to enable ripple feedback                               | boolean                  | true      |
| uninject-group-context | Ignore surrounding CheckboxGroup; form state still applies      | boolean                  | false     |
| name                   | Native field name; inherits from Group when omitted             | string                   | undefined |
| aria-label             | Accessible name when no visible label exists                    | string                   | undefined |

### Checkbox Events

| Event              | Description                       | Arguments                           |
| ------------------ | --------------------------------- | ----------------------------------- |
| update:model-value | Proposes a new value              | value: CheckboxModel                |
| change             | Value change                      | value: CheckboxModel, event?: Event |
| click              | Click; not emitted while disabled | event: MouseEvent                   |
| focus              | Focus                             | event: FocusEvent                   |
| blur               | Blur                              | event: FocusEvent                   |

### Checkbox Methods

| Method | Arguments              | Returns |
| ------ | ---------------------- | ------- |
| toggle | checked?: boolean      | void    |
| focus  | options?: FocusOptions | void    |
| blur   | -                      | void    |

### Checkbox Slots

| Slot               | Description                               | Arguments                                                   |
| ------------------ | ----------------------------------------- | ----------------------------------------------------------- |
| checkbox           | Customize the complete control appearance | checked: boolean, disabled: boolean, indeterminate: boolean |
| checked-icon       | Checked icon                              | -                                                           |
| unchecked-icon     | Unchecked icon                            | -                                                           |
| indeterminate-icon | Half icon                                 | -                                                           |
| default            | Label                                     | checked: boolean                                            |

### CheckboxGroup Props

| Prop                  | Description                                                                                               | Type                                                                                                       | Default      |
| --------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------ |
| model-value (v-model) | Controlled value                                                                                          | ChoiceValue[]                                                                                              | undefined    |
| default-value         | Initial uncontrolled value                                                                                | ChoiceValue[]                                                                                              | []           |
| max                   | Maximum selection count                                                                                   | number                                                                                                     | undefined    |
| options               | Options; replaces default slot when supplied                                                              | Array<ChoiceValue \| CheckboxOption \| Record<string, unknown>> / `(query, { signal }) => Array / Promise` | `undefined`  |
| orientation           | Horizontal/vertical arrangement of checkbox-group options, default horizontal; not text reading direction | Orientation                                                                                                | 'horizontal' |
| disabled              | Disabled state; inherits from the form/group when omitted                                                 | boolean                                                                                                    | undefined    |
| readonly              | Readonly state; inherits from the form/group when omitted                                                 | boolean                                                                                                    | undefined    |
| error                 | Error state; inherits from the form/group when omitted                                                    | boolean                                                                                                    | undefined    |
| field-names           | Option field mapping                                                                                      | ChoiceFieldNames                                                                                           | undefined    |
| name                  | Native input name within the group                                                                        | string                                                                                                     | undefined    |
| aria-label            | Accessible group name                                                                                     | string                                                                                                     | undefined    |

### CheckboxGroup Methods

| Method     | Arguments | Returns       |
| ---------- | --------- | ------------- |
| checkAll   | -         | ChoiceValue[] |
| inverseAll | -         | ChoiceValue[] |

### CheckboxGroup Events

| Event              | Description                          | Arguments                                          |
| ------------------ | ------------------------------------ | -------------------------------------------------- |
| update:model-value | Proposes a new value                 | value: (string \| number \| boolean)[]             |
| change             | Value change; notified once by Group | value: (string \| number \| boolean)[], ev?: Event |

### CheckboxGroup Slots

| Slot     | Description            | Arguments                              |
| -------- | ---------------------- | -------------------------------------- |
| checkbox | Custom checkbox        | checked: boolean<br/>disabled: boolean |
| label    | Checkbox label content | data: CheckboxOption, checked: boolean |

### CheckboxOption

| Field         | Description                      | Type                                                                 |
| ------------- | -------------------------------- | -------------------------------------------------------------------- |
| value         | Option identity                  | ChoiceValue                                                          |
| label         | Label or render function         | VNodeChild \| (data: CheckboxOption, checked: boolean) => VNodeChild |
| disabled      | Disable interaction              | boolean                                                              |
| readonly      | Read-only interaction            | boolean                                                              |
| indeterminate | Display-only indeterminate state | boolean                                                              |

## Type definitions

The component exports the following types

```ts
import type { CheckboxProps } from "@cedar-design/ui";
```

### ChoiceFieldNames

`{ label?: string; value?: string; disabled?: string; readonly?: string; indeterminate?: string }`

Exported types：`CheckboxOption`、`ChoiceFieldNames`。

Public method type：`CheckboxGroupMethods`；`CheckboxGroupInstance` includes these methods.

### Reduced motion

Built-in CSS transitions follow `prefers-reduced-motion: reduce`. Removing transitions does not change final visibility, selected/expanded state or event semantics. Applications control custom animations inside slots.

### Style variables

| Variable                                 | Default                                |
| ---------------------------------------- | -------------------------------------- |
| `--c-checkbox-control-color`             | `var(--c-sys-color-content-secondary)` |
| `--c-checkbox-control-color-checked`     | `var(--c-sys-color-content-brand)`     |
| `--c-checkbox-mark-color`                | `var(--c-sys-color-surface-default)`   |
| `--c-checkbox-control-color-disabled`    | `var(--c-sys-color-content-disabled)`  |
| `--c-checkbox-control-color-error`       | `var(--c-sys-color-content-danger)`    |
| `--c-checkbox-control-size`              | `14px`                                 |
| `--c-checkbox-label-text-color`          | `var(--c-sys-color-content-primary)`   |
| `--c-checkbox-label-text-color-disabled` | `var(--c-sys-color-content-disabled)`  |
| `--c-checkbox-label-font-size`           | `var(--c-font-size-body-3)`            |
| `--c-checkbox-label-gap`                 | `var(--c-spacing-4)`                   |
| `--c-checkbox-action-padding`            | `5px`                                  |
| `--c-checkbox-group-gap`                 | `var(--c-spacing-7)`                   |
| `--c-checkbox-animation-duration`        | `var(--c-transition-duration-3)`       |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

The `options` prop accepts an array or `(query, { signal }) => array/Promise`. The component manages loading, cancellation and stale-result isolation; failures emit load-error. Single/multiple groups initialize with an empty-string query, searchable fields reload when the query changes, and root loading for tree fields remains independent of existing load-more child loading.

---

Document: llms/en-US/components/col.md

<!-- Source: src/col/README.en-US.md; locale: en-US; page: /en/components/col/ -->

# Col

24-column Flex layout. Row manages gutters and alignment; Col manages spans, offsets, ordering and breakpoints. Use Grid for CSS Grid collapse and suffix items.

> **Choosing a layout**
>
> - Grid + GridItem: Use for form columns and card grids with consistent column widths, spans, responsive column counts, or collapsed rows and suffix items.
> - Row + Col: Use for 24-column Flex layouts that need horizontal/vertical alignment, wrapping control, fixed and flexible widths together, or responsive ordering. Row controls the row; Col controls width, offset and order.
> - Space: Use for simple groups of buttons, tags or text that only need spacing, direction and alignment. Use native Flex for more flexible width allocation.

## Basic examples

### Span and offset

Example source: src/col/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const span = ref(8)
const offset = ref(4)
</script>
<template><div>
  <div class="controls">Span<c-radio-group v-model="span"><c-radio v-for="value in [4, 8, 12]" :key="value" :value="value">{{ value }}</c-radio></c-radio-group></div>
  <div class="controls">Offset<c-radio-group v-model="offset"><c-radio v-for="value in [0, 4, 8]" :key="value" :value="value">{{ value }}</c-radio></c-radio-group></div>
  <c-row :gutter="12"><c-col :span="span" :offset="offset"><div class="cell">{{ span }} / +{{ offset }}</div></c-col><c-col :span="4"><div class="cell soft">4</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## Layout and arrangement

### Flexible ratios and fixed widths

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `flex` | Ratio, fixed length or CSS flex value | Flexible ratios and fixed widths |
| `xs` | Responsive span or object containing span, offset and order | Responsive objects and visibility |
| `sm` | Responsive span or object containing span, offset and order | Responsive objects and visibility |
| `md` | Responsive span or object containing span, offset and order | Responsive objects and visibility |
| `span` | Column span; 0 hides | Responsive objects and visibility |
<!-- demo-config-notes:end -->


Example source: src/col/__demos__/flex.vue

```vue
<template><div>
  <c-row :gutter="12"><c-col :flex="1"><div class="cell">1</div></c-col><c-col :flex="2"><div class="cell soft">2</div></c-col></c-row>
  <c-row :gutter="12" :wrap="false"><c-col flex="100px"><div class="cell">100px</div></c-col><c-col flex="auto"><div class="cell soft">auto</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### Responsive objects and visibility

Example source: src/col/__demos__/responsive.vue

```vue
<template><div>
  <p>xs → sm (576px) → md (768px). Hidden columns return at larger breakpoints.</p>
  <c-row :gutter="[12, 12]"><c-col :xs="24" :sm="12" :md="8"><div class="cell">24 / 12 / 8</div></c-col><c-col :xs="0" :sm="12" :md="8"><div class="cell soft">Hidden / 12 / 8</div></c-col><c-col :span="8" :xs="{ span: 20, offset: 4, order: 2 }" :md="{ span: 8, offset: 0, order: 0 }"><div class="cell">Reset offset / order</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

<!-- same-source-api:start -->

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| span | Column span; 0 hides | `number` | `24` |
| offset | Offset; 0 resets | `number` | `undefined` |
| order | Order; 0 resets | `number` | `undefined` |
| xs | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| sm | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| md | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| lg | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| xl | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| xxl | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| flex | Ratio, fixed length or CSS flex value | `number / string` | `undefined` |

### Events

| Event | Description |
| --- | --- |
| click | Native MouseEvent, emitted once per click |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

The order example restores every column to `order: 0` when reverse is turned off. Responsive breakpoints use the browser viewport rather than the demo card width; widening the card alone does not activate a breakpoint. `span: 0` hides a column, and a matching larger breakpoint can restore it.

## Content and presentation

### Ordering and resetting to zero

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `span` | Column span; 0 hides | Ordering and resetting to zero |
| `order` | Order; 0 resets | Ordering and resetting to zero |
<!-- demo-config-notes:end -->


Example source: src/col/__demos__/order.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const reverse = ref(false)
</script>
<template><div><div class="controls"><c-switch v-model="reverse" aria-label="Reverse order" />Reverse order</div><c-row :gutter="12"><c-col v-for="i in 3" :key="i" :span="8" :order="reverse ? 3 - i : 0"><div class="cell">{{ i }}</div></c-col></c-row></div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| span | Column span; 0 hides | `number` | `24` |
| offset | Offset; 0 resets | `number` | `undefined` |
| order | Order; 0 resets | `number` | `undefined` |
| xs | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| sm | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| md | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| lg | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| xl | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| xxl | Responsive span or object containing span, offset and order | `number / ColSizeDescriptor` | `undefined` |
| flex | Ratio, fixed length or CSS flex value | `number / string` | `undefined` |

### Events

| Event | Description |
| --- | --- |
| click | Native MouseEvent, emitted once per click |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

The order example restores every column to `order: 0` when reverse is turned off. Responsive breakpoints use the browser viewport rather than the demo card width; widening the card alone does not activate a breakpoint. `span: 0` hides a column, and a matching larger breakpoint can restore it.

## Responsiveness and accessibility

Breakpoints use the browser viewport: xs is the base; sm ≥576, md ≥768, lg ≥992, xl ≥1200 and xxl ≥1600px. Configured values resolve downward from the largest matching breakpoint. SSR starts with xs and responds to the viewport after mounting. Grid collapsing and dynamic ordering are calculated after mounting. These layout containers add no keyboard shortcuts; callers supply content semantics and focusable elements. There are no public methods or dedicated theme tokens.

## Imports

Grid contains only Grid.Item. Row and Col are independent components with their own source, styles, navigation, documentation and demos. Grid.Row/Grid.Col, Row/Col re-exports from Grid and GridRowInstance/GridColInstance are removed. Import them from the library root or separate row/col entries. Installing Grid no longer registers Row/Col automatically.

---

Document: llms/en-US/components/collapse.md

<!-- Source: src/collapse/README.en-US.md; locale: en-US; page: /en/components/collapse/ -->

# Collapse

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:default-value="['1', 2]"`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`, `:name="2"`.

Example source: src/collapse/__demos__/basic.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]">
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

## Appearance and states

### Disabled

Preview configuration: `:default-value="[1]"`, `title="Beijing Toutiao Technology Co., Ltd."`, `:name="1"`, `:disabled="disabled"`.

Example source: src/collapse/__demos__/disabled.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-button @click="disabled = !disabled">
      {{ disabled ? 'Enable' : 'Disable' }}
    </c-button>
    <c-collapse :default-value="[1]">
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="1" :disabled="disabled">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2" :disabled="disabled">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const disabled = ref(false)
</script>
```

## Layout and arrangement

### Nested

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Uncontrolled initial expanded names | Nested, Icon Position |
| `destroy-on-hide` | Destroy content when hidden | Nested |
| `offset` | Gap between expanded panels | Offset |
| `expand-icon-position` | Expand-icon position within the header: left or right, default left. Does not control content expansion direction | Icon Position |
| `show-expand-icon` | Whether to show expansion icons; child items decide when omitted | Icon Position |
<!-- demo-config-notes:end -->


Preview configuration: `:default-value="['1', 2]"`, `destroy-on-hide`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`.

Example source: src/collapse/__demos__/nested.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]" destroy-on-hide>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <c-collapse :default-value="['1.1']" destroy-on-hide>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1.1">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1.2">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
      </c-collapse>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### Offset

Preview configuration: `:offset="offset"`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`, `name="2"`.

Example source: src/collapse/__demos__/offset.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-button @click="offset = !offset">
      {{ offset ? 'Hide offset' : 'Show offset' }}
    </c-button>
    <c-collapse v-model="activeNames" :offset="offset">
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const offset = ref(true)
const activeNames = ref<(string | number)[]>(['1', '2'])
</script>
```

### Icon Position

Preview configuration: `:default-value="['1']"`, `:expand-icon-position="position"`, `:show-expand-icon="!hideIcon"`, `title="Beijing Toutiao Technology Co., Ltd."`.

Example source: src/collapse/__demos__/icon-position.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-space>
      <c-button @click="position = position === 'right' ? 'left' : 'right'">
        {{ position === 'right' ? 'Icon left' : 'Icon right' }}
      </c-button>
      <c-button @click="hideIcon = !hideIcon">
        {{ hideIcon ? 'Show icon' : 'Hide icon' }}
      </c-button>
    </c-space>
    <c-collapse :default-value="['1']" :expand-icon-position="position" :show-expand-icon="!hideIcon">
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
        <template #extra>
          <c-tag size="sm">city</c-tag>
        </template>
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2" disabled>
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
      <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
        <div>Beijing Toutiao Technology Co., Ltd.</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const position = ref<'left' | 'right'>('left')
const hideIcon = ref(false)
</script>
```

## Content and presentation

### Accordion

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Uncontrolled initial expanded names | Accordion, Borders and dividers, Expand Icon |
| `accordion` | Accordion mode; at most one open panel | Accordion |
| `bordered` | Whether to show border | Borders and dividers |
| `divider` | Show dividers | Borders and dividers |
| `destroy-on-hide` | Destroy content when hidden | Destroy |
<!-- demo-config-notes:end -->


Preview configuration: `:default-value="[1]"`, `accordion`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`.

Example source: src/collapse/__demos__/accordion.vue

```vue
<template>
  <c-collapse :default-value="[1]" accordion>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### Borders and dividers

Compare outer borders and separators between panels, including their appearance while expanded.

Example source: src/collapse/__demos__/border-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


const divider = ref(true)
return { divider }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="border-less">
    <h4><span lang="zh-CN">无边框模式</span><span lang="en-US">border less</span></h4>
    <c-collapse :default-value="['1']" :bordered="false">
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2" disabled>
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
        <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
          <div>Beijing Toutiao Technology Co., Ltd.</div>
        </c-collapse-item>
      </c-collapse>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="divider">
    <h4><span lang="zh-CN">分割线</span><span lang="en-US">divider</span></h4>
    <c-space direction="column" :style="{
      width: '100%'
    }">
        <c-button @click="scene2.divider = !scene2.divider">
          {{ scene2.divider ? 'Hide divider' : 'Show divider' }}
        </c-button>
        <c-collapse :default-value="[]" :divider="scene2.divider">
          <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
            <div>Beijing Toutiao Technology Co., Ltd.</div>
          </c-collapse-item>
          <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="2">
            <div>Beijing Toutiao Technology Co., Ltd.</div>
          </c-collapse-item>
          <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
            <div>Beijing Toutiao Technology Co., Ltd.</div>
          </c-collapse-item>
        </c-collapse>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Extra

Preview configuration: `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`, `:name="2"`, `name="3"`.

Example source: src/collapse/__demos__/extra.vue

```vue
<template>
  <c-collapse>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <template #extra>Extra</template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <template #extra>
        <c-button status="primary" size="sm">Action</c-button>
      </template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <template #extra>
        <c-tag size="sm">city</c-tag>
      </template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### Expand Icon

Preview configuration: `:default-value="['1', 2]"`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`, `:name="2"`.

Example source: src/collapse/__demos__/expand-icon.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]">
    <template #expand-icon="{ expanded }">
      <span>{{ expanded ? '▼' : '▶' }}</span>
    </template>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <template #expand-icon="{ expanded }">
        <span>{{ expanded ? '^^' : 'vv' }}</span>
      </template>
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

### Destroy

Preview configuration: `:default-value="['1', 2]"`, `destroy-on-hide`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`.

Example source: src/collapse/__demos__/destroy.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]" destroy-on-hide>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." name="3" :show-expand-icon="false">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
</script>
```

## Customization and slots

### Custom

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Uncontrolled initial expanded names | Custom |
| `bordered` | Whether to show border | Custom |
<!-- demo-config-notes:end -->


Preview configuration: `:default-value="['1', 2]"`, `:bordered="false"`, `title="Beijing Toutiao Technology Co., Ltd."`, `name="1"`.

Example source: src/collapse/__demos__/custom.vue

```vue
<template>
  <c-collapse :default-value="['1', 2]" :bordered="false">
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :style="customStyle" name="1">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :style="customStyle" :name="2">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
    <c-collapse-item title="Beijing Toutiao Technology Co., Ltd." :style="customStyle" name="3">
      <div>Beijing Toutiao Technology Co., Ltd.</div>
    </c-collapse-item>
  </c-collapse>
</template>
<script lang="ts" setup>
const customStyle = {
  borderRadius: '6px',
  marginBottom: '12px',
  overflow: 'hidden',
}
</script>
```

## Interaction and control

### Toggle All

Preview configuration: `title="Panel 1"`, `name="1"`, `title="Panel 2"`, `name="2"`.

Example source: src/collapse/__demos__/toggle-all.vue

```vue
<template>
  <c-space direction="column" :style="{ width: '100%' }">
    <c-space wrap>
      <c-button @click="toggleAll({ expand: 'inverse' })">Toggle all</c-button>
      <c-button @click="toggleAll({ expand: 'inverse', skipDisabled: true })">Toggle all (skip disabled)</c-button>
      <c-button @click="toggleAll({ expand: true })">Expand all</c-button>
      <c-button @click="toggleAll({ expand: true, skipDisabled: true })">Expand all (skip disabled)</c-button>
      <c-button @click="toggleAll({ expand: false })">Collapse all</c-button>
      <c-button @click="toggleAll({ expand: false, skipDisabled: true })">Collapse all (skip disabled)</c-button>
    </c-space>
    <c-collapse ref="collapseRef" v-model="activeNames">
      <c-collapse-item title="Panel 1" name="1">
        <div>Content 1</div>
      </c-collapse-item>
      <c-collapse-item title="Panel 2" name="2">
        <div>Content 2</div>
      </c-collapse-item>
      <c-collapse-item title="Panel 3" name="3" disabled>
        <div>Content 3</div>
      </c-collapse-item>
      <c-collapse-item title="Panel 4" name="4" disabled>
        <div>Content 4</div>
      </c-collapse-item>
    </c-collapse>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'

const collapseRef = ref<{
  toggleAll: (options: { expand: boolean | 'inverse'; skipDisabled?: boolean }) => void
}>()
const activeNames = ref<(string | number)[]>(['2', '4'])

const toggleAll = (options: { expand: boolean | 'inverse'; skipDisabled?: boolean }) => {
  collapseRef.value?.toggleAll(options)
}
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Titles and expanded content inherit reading direction without changing expansion state. The left/right values of expand-icon-position remain physical sides. Custom expansion graphics are not additionally mirrored.

## API

The main value uses ordinary `v-model`: `modelValue` is an array of expanded panel names, including in accordion mode. `defaultValue` initializes uncontrolled state only on creation; later changes do not reset it. Initialization does not emit `update:modelValue`. When `modelValue` is provided, the parent controls the state and its value is authoritative.

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| model-value | Expanded names; v-model | `(string \| number)[]` | `—` |
| default-value | Uncontrolled initial expanded names | `(string \| number)[]` | `[]` |
| accordion | Accordion mode; at most one open panel | `boolean` | `false` |
| show-expand-icon | Whether to show expansion icons; child items decide when omitted | `boolean` | `—` |
| expand-icon-position | Expand-icon position within the header: left or right, default left. Does not control content expansion direction | `'left' \| 'right'` | `'left'` |
| bordered | Whether to show border | `boolean` | `true` |
| divider | Show dividers | `boolean` | `true` |
| offset | Gap between expanded panels | `boolean` | `false` |
| destroy-on-hide | Destroy content when hidden | `boolean` | `false` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:model-value | Request an expanded-name update | `(string \| number)[]` |
| change | Emitted when expanded panels change | `(string \| number)[]`, `Event` |

### Slots

| Slot | Description | Scope |
| --- | --- | --- |
| default | Panel list | `—` |

### Methods

| Method | Description |
| --- | --- |
| toggleAll | Expand or collapse all panels (no-op in accordion) |

<!-- same-source-api:end -->

The parent `expand-icon` slot is forwarded to items that do not provide their own icon. Scope: `expanded`, `disabled`, `position`. It is not rendered on the root node.

#### CollapseToggleAllOptions

| Arguments | Description | Type | Default |
| --- | --- | --- | --- |
| expand | `'inverse'` toggles all; `boolean` expands or collapses all | `'inverse' \| boolean` | `—` |
| skipDisabled | Skip disabled panels | `boolean` | `false` |

### `<collapse-item>` Props

| Parameter | Description | Type | Default |
| --- | --- | --- | --- |
| name **(required)** | Unique panel identifier corresponding to a value in `modelValue` | `string \| number` | `—` |
| title | Panel title | `string` | `—` |
| disabled | Whether disabled | `boolean` | `false` |
| show-expand-icon | Whether to show an expansion icon | `boolean` | `true` |
| destroy-on-hide | Destroy content when hidden | `boolean` | `false` |

### `<collapse-item>` Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| title | Panel title | `—` |
| extra | Extra content | `—` |
| expand-icon | Expand icon | expanded: `boolean`<br>disabled: `boolean`<br>position: `'left' \| 'right'` |
| default | Panel content | `—` |

### Type definitions

The component exports the following types. `Collapse.Item` and `CollapseItem` refer to the same component.

```ts
import type { CollapseInstance, CollapseToggleAllOptions, ExpandIconPosition } from '@cedar-design/ui'
```

## Color variables

Collapse public color variables default to system semantics consistently in Cedar and Maple:

| Variable | Default semantic value |
| --- | --- |
| `--c-collapse-border-color` | `--c-sys-color-border-default` |
| `--c-collapse-title-bg` | `--c-sys-color-surface-default` |
| `--c-collapse-title-bg-active` | `--c-sys-color-surface-default` |
| `--c-collapse-title-bg-disabled` | `--c-sys-color-surface-default` |
| `--c-collapse-title-text-color` | `--c-sys-color-content-primary` |
| `--c-collapse-title-text-color-disabled` | `--c-sys-color-content-disabled` |
| `--c-collapse-content-text-color` | `--c-sys-color-content-primary` |
| `--c-collapse-content-text-color-disabled` | `--c-sys-color-content-disabled` |
| `--c-collapse-content-bg` | `--c-sys-color-surface-muted` |
| `--c-collapse-expand-icon` | `var(--c-sys-color-content-secondary)` |
| `--c-collapse-item-border-color` | `--c-sys-color-border-default` |

### Reduced motion

Built-in CSS transitions follow `prefers-reduced-motion: reduce`. Removing transitions does not change final visibility, selected/expanded state or event semantics. Applications control custom animations inside slots.

---

Document: llms/en-US/components/color-picker.md

<!-- Source: src/color-picker/README.en-US.md; locale: en-US; page: /en/components/color-picker/ -->

# Color Picker

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `default-value`: Default value (uncontrolled state)

Example source: src/color-picker/__demos__/basic.vue

```vue
<template>
  <c-color-picker default-value="#00BEBE" />
</template>
```

## Appearance and states

### Disabled

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Default | Disabled |
| `disabled` | Disabled | Disabled |
| `hide-trigger` | Panel only, without a trigger | Disabled |
| `show-text` | Show color value | Disabled |
<!-- demo-config-notes:end -->


- `default-value`: Default value (uncontrolled state)
- `disabled`: disabled
- `hide-trigger`: There is no trigger element, only the color panel is displayed
- `show-text`: Show color value

Example source: src/color-picker/__demos__/disabled.vue

```vue
<template>
  <c-space>
    <c-color-picker defaultValue="#00BEBE" disabled :hide-trigger="false" />
    <c-color-picker defaultValue="#00BEBE" showText disabled :hide-trigger="false" />
  </c-space>
</template>
```

## Content and presentation

### Colors

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Default | Colors |
| `history-colors` | History colors | Colors |
| `show-history` | Show history colors | Colors |
| `show-preset` | Show preset colors | Colors |
<!-- demo-config-notes:end -->


- `default-value`: Default value (uncontrolled state)
- `history-colors`: Color array of historical colors
- `show-history`: Show history colors
- `show-preset`: Show preset colors

Example source: src/color-picker/__demos__/colors.vue

```vue
<template>
  <c-color-picker
    defaultValue="#00BEBE"
    :historyColors="history"
    showHistory
    showPreset
    @open-change="addHistory" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const history = ref(['#00BEBE'])
const addHistory = (visible, color) => {
  if (!visible) {
    const index = history.value.indexOf(color)
    if (index !== -1) {
      history.value.splice(index, 1)
    }
    history.value.unshift(color)
  }
}
</script>
```

## Data and options

### Format

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | Default | Format |
| `format` | Color value format | Format |
| `show-text` | Show color value | Format |
| `hide-trigger` | Panel only, without a trigger | Format |
<!-- demo-config-notes:end -->


- `default-value`: Default value (uncontrolled state)
- `format`: Color value format
- `show-text`: Show color value
- `hide-trigger`: There is no trigger element, only the color panel is displayed

Example source: src/color-picker/__demos__/format.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group type="button" v-model="format">
      <c-radio v-for="item in formatList" :value="item">{{ item }}</c-radio>
    </c-radio-group>
    <c-color-picker defaultValue="#00BEBE" :format="format" showText :hide-trigger="false" />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const format = ref('hex')
const formatList = ['hex', 'rgb']
</script>
```

## API

### `<ColorPicker>` Props

| Parameter | Description | Type | Default |
| --- | --- | --- | --- |
| model-value **(v-model)** | Bound value | `string` | `-` |
| default-value | Default | `string` | `-` |
| format | Color value format | `'hex' \| 'rgb'` | `-` |
| size | Size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| show-text | Show color value | `boolean` | `false` |
| show-history | Show history colors | `boolean` | `false` |
| show-preset | Show preset colors | `boolean` | `false` |
| disabled | Disable interaction | `boolean` | `false` |
| disabled-alpha | Disable alpha | `boolean` | `false` |
| hide-trigger | Panel only, without a trigger | `boolean` | `true` |
| history-colors | History colors | `string[]` | `-` |
| preset-colors | Preset colors | `string[]` | `-` |


### Existing precedence of forwarded configuration (F07)

Existing triggerProps are spread after some internal Trigger settings, so nested fields such as disabled can currently override internal values. F07 preserves this order and type for compatibility; it does not apply AutoComplete managed-field rules, promise a new safe subset or automatically prohibit these existing capabilities.

Dragging uses the control owner view. KeepAlive deactivation or unmount ends the gesture and releases its listeners; a new activation requires a new gesture, and callbacks from old gestures cannot change its value.

---

Document: llms/en-US/components/color.md

<!-- Source: src/color/README.en-US.md; locale: en-US; page: /en/components/color/ -->

# Color

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `show-text`: Show color value

Example source: src/color/__demos__/basic.vue

```vue
<template>
  <c-color v-model="value" show-text />
</template>

<script setup>
import { ref } from 'vue'

const value = ref('#00BEBE')
</script>
```

## Appearance and states

### Size

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose          | Related examples |
| ------------- | ---------------- | ---------------- |
| `size`        | Size             | Size             |
| `show-text`   | Show color value | Size             |

<!-- demo-config-notes:end -->

- `size`: ComponentSize
- `show-text`: Show color value

Example source: src/color/__demos__/size.vue

```vue
<template>
  <c-space>
    <c-color v-model="value" size="xs" />
    <c-color v-model="value" size="sm" />
    <c-color v-model="value" size="md" show-text />
    <c-color v-model="value" size="lg" show-text />
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('#165DFF')
</script>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Arguments            | Description              | Type                         | Default |
| -------------------- | ------------------------ | ---------------------------- | ------- |
| `model-value`        | Bound value              | `string`                     | `-`     |
| `format`             | Color format             | `hex \| rgb`                 | `-`     |
| `size`               | Size                     | `xs \| sm \| md \| lg \| xl` | `md`    |
| `show-text`          | Show color value         | `boolean`                    | `false` |
| `show-history`       | Show history colors      | `boolean`                    | `false` |
| `show-preset`        | Show preset colors       | `boolean`                    | `false` |
| `disabled`           | Disable interaction      | `boolean`                    | `false` |
| `disabled-alpha`     | Disable alpha            | `boolean`                    | `false` |
| `color-picker-props` | Forwarded to ColorPicker | `object`                     | `{}`    |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

Dragging uses the control owner view. KeepAlive deactivation or unmount ends the gesture and releases its listeners; a new activation requires a new gesture, and callbacks from old gestures cannot change its value.

---

Document: llms/en-US/components/config-provider.md

<!-- Source: src/config-provider/README.en-US.md; locale: en-US; page: /en/components/config-provider/ -->

# Config Provider

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `size`: ComponentSize

Example source: src/config-provider/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-button @click="large = !large">切换尺寸</c-button>
    <c-config-provider :size="large ? 'lg' : 'sm'">
      <c-space>
        <c-input placeholder="继承全局尺寸" />
        <c-button>继承尺寸</c-button>
      </c-space>
    </c-config-provider>
    <p role="status">当前尺寸：{{ large ? 'lg' : 'sm' }}</p>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const large = ref(false)
</script>
```

## API

### ConfigProvider Props

| Prop | Description | Type | Default |
| ---- | -------- | ------ | ------ |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| type | Argument type | string | - |

### ConfigProvider Events

| Event | Description | Arguments |
| ------ | -------------- | ----------------------------- |
| click | Click event | `(event: MouseEvent) => void` |

### ConfigProvider Slots

| Slot | Description |
| ------- | -------------- |
| default | Custom default content |

## Type definitions

The component exports the following types

```ts
import type { ConfigProviderProps } from '@cedar-design/ui'
```


## Reading direction

Use `<c-config-provider dir="rtl">` to scope right-to-left layout. Omit `dir` to inherit, or nest `dir="ltr"` for a local override. Native DOM `dir` containers work too. The provider renders a `display: contents` div to carry direction to ordinary descendants without adding a layout box; place it in an HTML context that permits a div. It does not change the document direction. The former boolean `rtl` option is replaced by `dir` before release. Physical left/right placements retain their meaning.

---

Document: llms/en-US/components/count-to.md

<!-- Source: src/count-to/README.en-US.md; locale: en-US; page: /en/components/count-to/ -->

# Count To

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:to="123456"`.

Example source: src/count-to/__demos__/basic.vue

```vue
<template>
  <c-count-to :to="123456" />
</template>
```

## Content and presentation

### Precision, duration and easing

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `to` | Target value | Precision, duration and easing |
| `precision` | Decimal precision | Precision, duration and easing |
| `duration` | Animation duration in milliseconds | Precision, duration and easing |
| `timing-function` | Animation easing function | Precision, duration and easing |
<!-- demo-config-notes:end -->


Compare final precision and the effect of duration and easing on number transitions. Manual playback remains separate.

Example source: src/count-to/__demos__/number-format-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene3 = demoProxyRefs((() => {

const easeOutCubic = (v: number) => 1 - Math.pow(1 - v, 3)
return { easeOutCubic }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="precision">
    <h4><span lang="zh-CN">精度</span><span lang="en-US">precision</span></h4>
    <c-count-to :to="123456" :precision="2" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="duration">
    <h4><span lang="zh-CN">自定义时长</span><span lang="en-US">duration</span></h4>
    <c-count-to :to="123456" :duration="10000" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="timing-function">
    <h4><span lang="zh-CN">自定义动画曲线</span><span lang="en-US">timing function</span></h4>
    <c-count-to :to="123456" :timing-function="scene3.easeOutCubic" />
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Customization and slots

### Custom

Preview configuration: `:to="123456"`.

Example source: src/count-to/__demos__/custom.vue

```vue
<template>
  <c-count-to :to="123456">
    <template #default="{ value }">
      {{ value.toLocaleString() }}
    </template>
  </c-count-to>
</template>
```

## Interaction and control

### Manual

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `to` | Target value | Manual |
| `auto-start` | Whether to start animation automatically | Manual |
<!-- demo-config-notes:end -->


Preview configuration: `:to="123456"`, `:auto-start="false"`.

Example source: src/count-to/__demos__/manual.vue

```vue
<template>
  <c-space direction="column">
    <c-count-to ref="countToRef" :to="123456" :auto-start="false" />
    <c-space>
      <c-button status="primary" @click="countToRef?.start()">开始</c-button>
      <c-button @click="countToRef?.pause()">暂停</c-button>
      <c-button @click="countToRef?.reset()">重置</c-button>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import type { CountToInstance } from '../index'

const countToRef = ref<CountToInstance>()
</script>
```

## API

### CountTo Props

| Prop | Description | Type | Default |
| ----------------- | ------------------------ | ------------------------ | -------- |
| from | Start value | _number \| string_ | `0` |
| to | Target value | _number \| string_ | `0` |
| duration | Animation duration in milliseconds | _number \| string_ | `2000` |
| precision | Decimal precision | _number \| string_ | `0` |
| auto-start | Whether to start animation automatically | _boolean_ | `true` |
| timing-function | Animation easing function | _(v: number) => number_ | `-` |

### CountTo Events

| Event | Description | Callback arguments |
| ------ | -------------- | -------- |
| end | Triggered when animation ends | `-` |

### CountTo Slots

| Slot | Description | Arguments |
| ------- | ---------- | ----------------- |
| default | Custom content | `value: number` |

### CountTo Methods

| Method | Description | Arguments | Returns |
| ------ | ---------------------------------------------------------------- | ---- | ------ |
| start | Start the animation | `-` | `-` |
| pause | Pause the animation | `-` | `-` |
| reset | Reset the animation; when `auto-start` is `true`, playback starts automatically after reset | `-` | `-` |

## Type definitions

The component exports the following types

```ts
import type { CountToProps, CountToInstance } from '@cedar-design/ui'
```

### Style variables

| Variable | Default |
| ----------------------------- | -------------------------- |
| `--c-count-to-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-count-to-text-font-size` | `var(--c-font-size-lg)` |

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Animation pauses on unmount and KeepAlive deactivation and resumes on reactivation. Each instance keeps independent values and animation state.

---

Document: llms/en-US/components/countdown.md

<!-- Source: src/countdown/README.en-US.md; locale: en-US; page: /en/components/countdown/ -->

# Countdown

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:time="2 * 60 * 60 * 1000"`.

Example source: src/countdown/__demos__/basic.vue

```vue
<template>
  <c-countdown :time="2 * 60 * 60 * 1000" />
</template>
```

## Content and presentation

### Time format and custom content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `time` | Countdown duration in milliseconds | Time format and custom content, Statistic |
| `format` | Display format | Time format and custom content, Statistic |
<!-- demo-config-notes:end -->


Compare unit formats, milliseconds and custom time fragments, independently of playback controls.

Example source: src/countdown/__demos__/format-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="format">
    <h4><span lang="zh-CN">自定义格式</span><span lang="en-US">format</span></h4>
    <c-countdown :time="4 * 24 * 60 * 60 * 1000" format="DD 天 HH 时 mm 分 ss 秒" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="millisecond">
    <h4><span lang="zh-CN">显示毫秒</span><span lang="en-US">millisecond</span></h4>
    <c-countdown :time="2 * 60 * 60 * 1000" format="HH:mm:ss.SSS" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="custom">
    <h4><span lang="zh-CN">自定义样式</span><span lang="en-US">custom</span></h4>
    <c-countdown :time="108000000">
        <template #default="{ hours, minutes, seconds }">
          <span class="countdown-block">{{ hours }}</span>
          <span class="countdown-colon">:</span>
          <span class="countdown-block">{{ minutes }}</span>
          <span class="countdown-colon">:</span>
          <span class="countdown-block">{{ seconds }}</span>
        </template>
      </c-countdown>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--3 {

.countdown-block {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  width: 36px;
  height: 36px;
  color: var(--c-color-white);
  background: var(--c-color-primary-6);
  border-radius: 8px;
}

.countdown-colon {
  margin: 0 6px;
  font-weight: 500;
}

}
</style>
```

### Statistic

- `format`: Controls the displayed format.

Example source: src/countdown/__demos__/statistic.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Countdown">
      <c-countdown :time="2 * 60 * 60 * 1000" />
    </c-statistic>
    <c-statistic title="Campaign">
      <c-countdown :time="4 * 24 * 60 * 60 * 1000" format="DD 天 HH 时 mm 分 ss 秒" />
    </c-statistic>
  </c-space>
</template>
```

## Interaction and control

### Manual

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `time` | Countdown duration in milliseconds | Manual |
| `auto-start` | Whether to auto start count down | Manual |
| `format` | Display format | Manual |
<!-- demo-config-notes:end -->


- `format`: Controls the displayed format.

Example source: src/countdown/__demos__/manual.vue

```vue
<template>
  <c-space direction="column" align="flex-start">
    <c-countdown
      ref="countdownRef"
      :time="5000"
      :auto-start="false"
      format="ss.SSS"
      @end="handleEnd"
    />
    <c-space>
      <c-button status="primary" @click="countdownRef?.start()">开始</c-button>
      <c-button @click="countdownRef?.pause()">暂停</c-button>
      <c-button @click="countdownRef?.reset()">重置</c-button>
    </c-space>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Message } from '@cedar-design/ui'
import type { CountdownInstance } from '../index'

const countdownRef = ref<CountdownInstance>()

const handleEnd = () => {
  Message.info('end!')
}
</script>
```

## API

### Countdown Props

| Prop | Description | Type | Default |
| ------------- | ------------------------------------------ | -------------------- | ------------ |
| `time` | Countdown duration in milliseconds | `number \| string` | `0` |
| `format` | Display format | `string` | `'HH:mm:ss'` |
| `auto-start` | Whether to auto start count down | `boolean` | `true` |

### format placeholders

| Format | Description |
| ----- | ------------- |
| `DD` | Day |
| `HH` | Hour |
| `mm` | Minute |
| `ss` | Seconds |
| `S` | Milliseconds: 1 digit |
| `SS` | Milliseconds: 2 digits |
| `SSS` | Milliseconds: 3 digits |

### Countdown Events

| Event | Description | Arguments |
| -------- | ---------------- | --------------------- |
| `change` | Emitted after countdown changed | `timeData: TimeData` |
| `end` | Emitted after countdown ended | `-` |

### Countdown Slots

| Slot | Description | Arguments |
| --------- | ---------- | --------------------- |
| `default` | Custom content | `timeData: TimeData` |

### TimeData

| Name | Description | Type |
| -------------- | -------- | -------- |
| `days` | Remain days | `number` |
| `hours` | Remain hours | `number` |
| `minutes` | Remain minutes | `number` |
| `seconds` | Remaining seconds | `number` |
| `milliseconds` | Remain milliseconds | `number` |

### Countdown Methods

| Method | Description | Arguments | Returns |
| ------- | ----------------------------------------------------------------- | ---- | ------ |
| `start` | Start countdown | `-` | `-` |
| `pause` | Pause countdown | `-` | `-` |
| `reset` | Reset the countdown; when `auto-start` is `true`, it starts automatically after reset | `-` | `-` |

## Type definitions

The component exports the following types

```ts
import type { CountdownProps, CountdownInstance, TimeData } from '@cedar-design/ui'
```

### Style variables

| Variable | Default |
| ------------------------------- | -------------------------- |
| `--c-countdown-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-countdown-text-font-size` | `var(--c-font-size-lg)` |

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

SSR renders the initial formatted time. Changing format while paused updates the display. The finish event fires once per round; reset starts another round. Unmounting cleans up animation frames.

---

Document: llms/en-US/components/date-picker.md

<!-- Source: src/date/picker/README.en-US.md; locale: en-US; page: /en/components/date-picker/ -->

# Date Picker

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `default-value`: Default value

Example source: src/date/picker/__demos__/basic.vue

```vue
<template>
  <c-date-picker default-value="2019-06-03" />
</template>
```

## Date views and presentation

### Mode

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `type` | Panel type | Mode, Month Labels, Locale Isolation |
| `disable-confirm` | Commit immediately | Month Labels, Responsive Panels |
| `day-start-of-week` | First weekday, calendar only; integer 0–6 | Locale Isolation |
| `show-time` | Include time selection | Responsive Panels |
<!-- demo-config-notes:end -->


Preview configuration: `type="week"`, `type="month"`, `type="year"`, `type="quarter"`.

Example source: src/date/picker/__demos__/mode.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-date-picker type="week" />
    <c-date-picker type="month" />
    <c-date-picker type="year" />
    <c-date-picker type="quarter" />
  </c-space>
</template>
```

### Month Labels

- `picker-value`: The date displayed in the default panel
- `abbreviation`: Whether to enable abbreviation

Example source: src/date/picker/__demos__/month-labels.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const abbreviation = ref(true)
</script>

<template>
  <c-checkbox v-model="abbreviation">月份缩写</c-checkbox>
  <c-date-picker type="month" picker-value="2025-01" :abbreviation="abbreviation" :disable-confirm="false" />
  <c-date-range-picker type="month" :abbreviation="abbreviation" />
</template>
```

### Locale Isolation

- `picker-value`: The date displayed in the default panel
- `day-start-of-week`: The first day of the week starts on the day of the week, 0-Sunday, 1-Monday, and so on.

Example source: src/date/picker/__demos__/locale-isolation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const first = ref('2021-01-03')
const second = ref('2021-01-03')
const monday = ref(true)
const monthModel = ref('2025 January 15')
</script>

<template>
  <p>两个实例独立管理周起始日。可切换顶部语言，模型不随展示语言改变。</p>
  <c-date v-model="first" type="week" :date-picker-props="{ dayStartOfWeek: 0 }" />
  <c-date v-model="second" type="week" :date-picker-props="{ dayStartOfWeek: monday ? 1 : 2 }" />
  <c-checkbox v-model="monday">第二个实例周一起始（关闭为周二）</c-checkbox>
  <c-date-picker type="week" v-model="first" picker-value="2021-01-01" :day-start-of-week="0" />
  <c-date-picker type="week" v-model="second" picker-value="2021-01-01" :day-start-of-week="monday ? 1 : 2" />
  <c-date v-model="monthModel" value-format="YYYY MMMM DD" format="YYYY MMMM DD" />
  <p>月份名称模型（稳定英文协议）：{{ monthModel }}</p>
</template>
```

### Responsive Panels

- `show-time`: Whether to increase time selection
- `shortcuts`: Quick selection of preset time range
- `shortcuts-position`: The position of the preset range on the panel, which is placed at the bottom by default, and the side is generally used for scenes with a large number of preset times

Example source: src/date/picker/__demos__/responsive-panels.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref("2026-10-20 09:30:00");
const selectedRange = ref(["2026-10-20 09:30:00", "2026-10-22 18:00:00"]);
const position = ref<"left" | "right" | "bottom">("left");
const positions = ["left", "right", "bottom"].map((value) => ({
  label: value,
  value,
}));
const types = ["date", "month", "year"] as const;
const shortcuts = [{ label: "本月工作日范围", value: "2026-10-20 09:30:00" }];
const rangeShortcuts = [
  {
    label: "本月工作日范围",
    value: ["2026-10-20 09:30:00", "2026-10-22 18:00:00"],
  },
];
</script>
<template>
  <div>
    <c-form-item layout="vertical" size="sm" label="独立面板快捷位置">
      <c-radio-group
        v-model="position"
        aria-label="独立面板快捷位置"
        :options="positions"
        variant="button"
        size="sm"
      />
    </c-form-item>

    <section
      v-for="type in types"
      :key="type"
      :aria-label="'独立 ' + type + ' 面板'"
    >
      <h4>{{ type }} · DatePicker / DateRangePicker</h4>
      <c-date-picker :type="type" :disable-confirm="false" />
      <c-date-range-picker :type="type" :disable-confirm="false" />
    </section>
    <section aria-label="独立日期时间面板">
      <h4>DatePicker · 时间与快捷项</h4>
      <c-date-picker
        v-model="selected"
        show-time
        :shortcuts="shortcuts"
        :shortcuts-position="position"
        :disable-confirm="false"
      />
    </section>
    <p role="status" aria-label="独立日期时间已提交">{{ selected }}</p>
    <section aria-label="独立日期时间范围面板">
      <h4>DateRangePicker · 时间与快捷项</h4>
      <c-date-range-picker
        v-model="selectedRange"
        show-time
        :shortcuts="rangeShortcuts"
        :shortcuts-position="position"
        :disable-confirm="false"
      />
    </section>
    <p role="status" aria-label="独立日期时间范围已提交">{{ selectedRange }}</p>
  </div>
</template>
```

## Time and selection rules

### Show Time

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `show-time` | Include time selection | Show Time, Disabled Parts, Time Presentation |
| `format` | Display format | Show Time, Time Presentation |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | Current Range, Time Presentation |
| `default-value` | Uncontrolled initial value, read once | Show Time |
| `disabled-date` | Return true to disable a date | Disabled Parts |
| `disabled-time` | Disabled times for the current date and endpoint | Disabled Parts |
<!-- demo-config-notes:end -->


- `show-time`: Whether to increase time selection
- `default-value`: Default value
- `format`: Display the format of the date, refer to [String Parsing Format](#string-parsing-format)

Example source: src/date/picker/__demos__/show-time.vue

```vue
<template>
  <c-date-picker
    show-time
    default-value="2025-01-15 09:09:06"
    format="YYYY-MM-DD HH:mm:ss"
  />
</template>
```

### Disabled Parts

- `disabled-date`: Unselectable date
- `show-time`: Whether to increase time selection
- `disabled-time`: Unselectable time

Example source: src/date/picker/__demos__/disabled-parts.vue

```vue
<template>
  <c-date-picker style="margin: 0 24px 24px 0"
    :disabled-date="(current: any) => dayjs(current).isBefore(dayjs())"
  />
  <c-date-picker style="margin-right: 24px; margin-bottom: 24px"
    show-time
    :disabled-date="(current: any) => dayjs(current).isBefore(dayjs())"
    :disabled-time="getDisabledTime"
  />
</template>

<script lang="ts">
import { defineComponent } from 'vue'
import dayjs from 'dayjs'

export default defineComponent({
  setup() {
    function range(start: any, end: any) {
      const result = []
      for (let i = start; i < end; i++) {
        result.push(i)
      }
      return result
    }

    function getDisabledTime(date: any) {
      return {
        disabledHours: () => range(6, 24),
        disabledMinutes: () => range(30, 60),
        disabledSeconds: () => range(30, 60),
      }
    }
    return {
      dayjs,
      getDisabledTime,
    }
  },
})
</script>
```

### Current Range

- `value-format`: The format of the value, valid for `value` `defaultValue` `pickerValue` `defaultPickerValue` and the return value in the event, supports setting as timestamp, Date and string (refer to [String parsing format](#string-parsing-format) ). If not specified, it will be formatted as a string, in the same format as `format`.
- `default-picker-value`: Date displayed on the panel
- `show-now-button`: Whether to display the now button when showTime

Example source: src/date/picker/__demos__/current-range.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const yesterday = new Date()
yesterday.setDate(yesterday.getDate() - 1)
const selected = ref(yesterday)
const showCurrent = ref(true)
const showNowButton = ref(true)
const exchangeTime = ref(true)
const range = ref(['2025-01-05 09:00', '2025-01-10 18:00'])
</script>
<template>
  <div>
    <p>今日高亮和选择当前是两个独立功能。</p>
    <c-checkbox v-model="showCurrent"> 今日高亮</c-checkbox>
    <c-checkbox v-model="showNowButton"> 选择当前按钮</c-checkbox>
    <c-date-picker
      v-model="selected"
      value-format="Date"
      :default-picker-value="new Date()"
      :show-current="showCurrent"
      :show-now-button="showNowButton"
      :disable-confirm="false"
    />
    <p>确认后选中：{{ selected }}</p>
    <c-checkbox v-model="exchangeTime"> 日期反序时连同时间交换</c-checkbox>
    <p>先选较晚日期，再选较早日期，对比起止时间。</p>
    <c-date-range-picker
      v-model="range"
      show-time
      format="YYYY-MM-DD HH:mm"
      value-format="YYYY-MM-DD HH:mm"
      :exchange-time="exchangeTime"
      :disable-confirm="false"
    />
    <p>确认后范围：{{ range }}</p>
  </div>
</template>
```

### Time Presentation

- `model-value`: Value
- `show-time`: Whether to increase time selection
- `format`: Display the format of the date, refer to [String Parsing Format](#string-parsing-format)
- `value-format`: The format of the value, valid for `value` `defaultValue` `pickerValue` `defaultPickerValue` and the return value in the event, supports setting as timestamp, Date and string (refer to [String parsing format](#string-parsing-format) ). If not specified, it will be formatted as a string, in the same format as `format`.

Example source: src/date/picker/__demos__/time-presentation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const use12Hours = ref(true)
const timeOptions = { step: { minute: 15 }, hideDisabledOptions: true }
</script>

<template>
  <c-checkbox v-model="use12Hours">十二小时展示</c-checkbox>

  <c-date-picker
    model-value="2025-01-05 13:30"
    show-time
    format="YYYY-MM-DD HH:mm"
    value-format="YYYY-MM-DD HH:mm"
    :time-picker-props="{ ...timeOptions, use12Hours }"
  />
</template>
```

## Shortcuts and customization

### Short Cuts

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `disable-confirm` | Commit immediately | Panel Tools, Entry Boundary |
| `show-time` | Include time selection | Short Cuts |
| `day-start-of-week` | First weekday, calendar only; integer 0–6 | Entry Boundary |
<!-- demo-config-notes:end -->


- `shortcuts`: Quick selection of preset time range
- `show-time`: Whether to increase time selection

Example source: src/date/picker/__demos__/short-cuts.vue

```vue
<template>
  <c-date-picker style="margin: 0 24px 24px 0"
    :shortcuts="[
      {
        label: '2 hours later',
        value: () => dayjs().add(2, 'hour'),
      },
      {
        label: 'a week later',
        value: () => dayjs().add(1, 'week'),
      },
      {
        label: 'a month later',
        value: () => dayjs().add(1, 'month'),
      },
    ]"
    show-time
  />
</template>

<script lang="ts">
import { defineComponent } from 'vue'
import dayjs from 'dayjs'

export default defineComponent({
  setup() {
    return {
      dayjs,
    }
  },
})
</script>
```

### Footer

Preview configuration: `showTime`.

Example source: src/date/picker/__demos__/footer.vue

```vue
<template>
  <c-date-picker style="margin-bottom: 20px">
    <template #extra>Extra footer</template>
  </c-date-picker>
  <br />
  <c-date-range-picker showTime>
    <template #extra>Extra footer</template>
  </c-date-range-picker>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### Panel Tools

- `picker-value`: The date displayed in the default panel
- `shortcuts`: Quick selection of preset time range

Example source: src/date/picker/__demos__/panel-tools.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref("2025-01-15");
const viewport = ref("2025-01-01");
const acceptNavigation = ref(true);
const shortcuts = [
  { label: "月初", value: "2025-01-01" },
  { label: "下个月", value: () => "2025-02-01" },
  { label: "不可选", value: "2025-03-01", disabled: true },
];
function navigate(value: unknown) {
  if (acceptNavigation.value && typeof value === "string")
    viewport.value = value;
}
</script>
<template>
  <div>
    <p>选择值：{{ selected }}；视口：{{ viewport }}</p>
    <c-checkbox v-model="acceptNavigation"> 接受视口导航</c-checkbox>
    <c-date-picker
      v-model="selected"
      :picker-value="viewport"
      :shortcuts="shortcuts"
      :disable-confirm="false"
      @update:picker-value="navigate"
    />
    <p>范围快捷项走同一套确认与校验。</p>
    <c-date-range-picker
      :default-value="['2025-01-10', '2025-01-15']"
      :shortcuts="[{ label: '第一周', value: ['2025-01-01', '2025-01-07'] }]"
      :disable-confirm="false"
    />
  </div>
</template>
```

### Entry Boundary

- `min`: Sets the lower bound.
- `max`: Sets the upper bound.
- `day-start-of-week`: The first day of the week starts on the day of the week, 0-Sunday, 1-Monday, and so on.

Example source: src/date/picker/__demos__/entry-boundary.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateSelection } from "@cedar-design/ui";
const limited = ref(true);
const fieldValue = ref<DateSelection>("2025-02-12");
const panelValue = ref<DateSelection>("2025-02-12");
const week = ref<0 | 1 | 6>(1);
</script>

<template>
  <div class="entry-demo">
    <p>仅允许选择 2025 年 2 月；移除限制不会改变已有选中值。</p>
    <c-button @click="limited = !limited">{{
      limited ? "移除日期限制" : "恢复日期限制"
    }}</c-button>
    <c-space wrap>
      <c-button @click="week = 0">周日起始</c-button>
      <c-button @click="week = 1">周一起始</c-button>
      <c-button @click="week = 6">周六起始</c-button>
    </c-space>
    <div>
      <p>字段：管理输入与浮层；面板参数放在 date-picker-props。</p>
      <c-date
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="fieldValue"
        :date-picker-props="{ dayStartOfWeek: week }"
        placeholder="选择日期"
      />
    </div>
    <div>
      <p>纯面板：直接嵌入页面，不使用 open / popup-container。</p>
      <c-date-picker
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="panelValue"
        :day-start-of-week="week"
        :disable-confirm="false"
      />
      <p>已提交：{{ panelValue }}</p>
    </div>
  </div>
</template>

<style scoped>
.entry-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
</style>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"`, including runtime changes and local overrides. Calendar dates, months and years follow reading order; navigation icons mirror, while date values keep their meaning. In paged grids, Left/Right moves focus visually, Up/Down moves one row, and Home/End moves to the row boundary, skipping disabled items. Focus navigation does not select; Enter/Space keeps the existing selection behavior. Navigation is bounded by the displayed grid. Explicit `shortcuts-position="left|right"` remains physical; `bottom` stays below. Field popovers inherit their source direction.

## API

### Props

Pure panels do not accept field/popup props such as open/default-open, popup-container, placement, trigger-props, placeholder, variant or clearable. Configure popups through Date/DateRange popup-props, and typing through input-editable. disable-confirm alone controls confirmation tools; show-confirm-btn is removed.

| Arguments | Description | Type | Default |
| ------------------- | ------------------------------- | ------------------------------------------ | ------- |
| `model-value` | Bound value | `Date \| string \| number` | `-` |
| `type` | Panel type | `date \| week \| month \| year \| quarter` | `date` |
| `format` | Display format | `string \| Function` | `-` |
| `day-start-of-week` | First weekday, calendar only; integer 0–6 | `DateWeekStart` | `0` |
| `readonly` | Readonly; does not change selection | `boolean` | `false` |
| `time-picker-props` | Local time-panel display options | `Partial<TimePickerProps>` | `-` |
| `show-time` | Include time selection | `boolean` | `false` |
| `disabled` | Disable interaction | `boolean` | `false` |
| `disabled-date` | Return true to disable a date | `Function` | `-` |

Desktop calendar capabilities, including shortcuts, footer and cell slots, remain in a separate presentation implementation.

### Shared date-family contract

| Arguments | Description | Type | Default |
| ----------------- | ------------------------------------------------------- | ------------------------------------------------ | ------- |
| `default-value` | Uncontrolled initial value, read once | DateValue / DateValue[] | — |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | string | Follows type |
| `min` / `max` | Inclusive bounds; string bounds use value-format | DateValue | — |
| `disabled-time` | Disabled times for the current date and endpoint | (date: Date, side: DateSide) => DateDisabledTime | — |
| `disable-confirm` | Commit immediately | boolean | true |

`DateValue = Date | string | number`. Clearing a single value produces undefined; clearing a range produces [].
The date argument of `disabledDate(date, side)` and `disabledTime(date, side)` is always a Date; side is start/end.
Time callbacks return numeric lists from `disabledHours()`, `disabledMinutes(hour)` and `disabledSeconds(hour, minute)`.
Invalid dates and incomplete/reversed ranges cannot be committed. Confirmation revalidates dynamic disabling rules. Locked range endpoints cannot be cleared or changed.
Nested panel props configure presentation only; they must not override top-level model-value, format, bounds, disabling rules or control events.

### Events

| Event | Description | Arguments |
| -------------------- | ----------------------- | --------------------------------- |
| `update:model-value` | Request a model update | value |
| `select` | Select a draft; does not imply submission | value, date(s), formatted text(s) |
| `change` | Committed value changes | value, date(s), formatted text(s) |
| `confirm` | Confirm valid selection; does not use ok | value, date(s), formatted text(s) |

Set `:disable-confirm="false"` to show confirmation tools. The `actions` slot provides `{ confirm, disabled }`; custom `actions` must still call confirm to validate.

---

Document: llms/en-US/components/date-range.md

<!-- Source: src/date-range/README.en-US.md; locale: en-US; page: /en/components/date-range/ -->

# DateRange

A date range field. The bound model is an array; use DateRangePicker for a standalone panel.

## String range models

Set format="MM-DD" and value-format="MM-DD" to get ['09-10', '10-10'] directly. These values have no year; parsing uses the current year and cannot preserve cross-year ordering. For real bookings store YYYY-MM-DD and map the payload in application code. format only changes display, while value-format changes the model and events.

Without time-zone the browser-local time zone remains in effect. An explicit IANA time zone changes the civil-time interpretation of strings; Date/timestamp values preserve their instant. Editing one endpoint does not change an untouched endpoint's repeated-hour occurrence or milliseconds.

## Basic examples

### Basic

Example source: src/date-range/__demos__/basic.vue

```vue
<template>
  <c-date-range v-model="range" style="width: 300px" clearable />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

### Interaction state comparison

Toggle disabled, read-only and error states, then interact with the same instance. Recovery controls remain outside the target; error appearance alone does not validate data.

<details>
<summary>Configuration details and limits</summary>

#### State Lab

## Appearance and date presentation

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                                | Related examples                    |
| -------------- | ---------------------------------------------------------------------- | ----------------------------------- |
| `clearable`    | Show the clear action                                                  | Mode, Separator                     |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | Appearance configuration comparison |
| `type`         | Mode                                                                   | Mode                                |
| `separator`    | Range separator                                                        | Separator                           |
| `placeholder`  | Placeholder                                                            | Separator                           |

<!-- demo-config-notes:end -->

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/date-range/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(["2026-10-23", "2026-10-25"]);
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-date-range
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-date-range>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Mode

Example source: src/date-range/__demos__/mode.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-date-range v-model="dateRange" style="width: 300px" clearable />
    <c-date-range v-model="weekRange" type="week" style="width: 300px" clearable />
    <c-date-range v-model="monthRange" type="month" style="width: 300px" clearable />
    <c-date-range v-model="yearRange" type="year" style="width: 300px" clearable />
    <c-date-range v-model="quarterRange" type="quarter" style="width: 300px" clearable />
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const dateRange = ref()
const weekRange = ref()
const monthRange = ref()
const yearRange = ref()
const quarterRange = ref()
</script>
```

### Separator

Example source: src/date-range/__demos__/separator.vue

```vue
<template>
  <c-date-range
    v-model="range"
    style="width: 300px"
    separator=" 至 "
    :placeholder="['开始日期', '结束日期']"
    clearable
  />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

## Time and range rules

### Show Time

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                | Related examples      |
| --------------- | ---------------------------------------------------------------------- | --------------------- |
| `format`        | Display format                                                         | Show Time, Boundaries |
| `show-time`     | Include time selection                                                 | Show Time             |
| `clearable`     | Show the clear action                                                  | Show Time             |
| `value-format`  | Model and event value format: a date format string, Date, or timestamp | Boundaries            |
| `disabled-date` | Return true to disable a date                                          | Boundaries            |

<!-- demo-config-notes:end -->

Example source: src/date-range/__demos__/show-time.vue

```vue
<template>
  <c-date-range
    v-model="range"
    style="width: 380px"
    show-time
    format="YYYY-MM-DD HH:mm:ss"
    clearable
  />
  <p role="status" aria-label="Date-time range model">{{ JSON.stringify(range) ?? 'undefined' }}</p>
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

### Boundaries

Example source: src/date-range/__demos__/boundaries.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(['2026/09/10', '2026/09/15'])
const disabledDate = (date: Date, side: 'start' | 'end') => side === 'end' && date.getDay() === 0
</script>
<template>
  <div class="date-contract-demo">
    <c-date-range v-model="value" value-format="YYYY/MM/DD" format="DD-MM-YYYY"
      min="2026/09/01" max="2026/09/30" :disabled-date="disabledDate" />
    <p>仅可选九月，结束日期不能是周日。请选齐两个端点；确认提交，Escape 取消草稿。</p>
    <output>{{ value }}</output>
  </div>
</template>
<style scoped>
.date-contract-demo { display: flex; flex-direction: column; gap: 12px; }
.date-contract-demo p { margin: 0; }
</style>
```

## Value model and text input

### String Values

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                                | Related examples          |
| -------------- | ---------------------------------------------------------------------- | ------------------------- |
| `format`       | Display format                                                         | String Values, Text Entry |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | String Values             |
| `disabled`     | Disable interaction                                                    | Text Entry                |

<!-- demo-config-notes:end -->

Example source: src/date-range/__demos__/en-US/string-values.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const date = ref("2026-09-10");
const month = ref("2026-09");
const range = ref(["09-10", "10-10"]);
</script>
<template>
  <c-space direction="column">
    <c-date v-model="date" format="YYYY-MM-DD" value-format="YYYY-MM-DD" />
    <p>String: {{ JSON.stringify(date) }}</p>
    <c-date
      v-model="month"
      type="month"
      format="YYYY-MM"
      value-format="YYYY-MM"
    />
    <p>Month string: {{ JSON.stringify(month) }}</p>
    <c-date-range v-model="range" format="MM-DD" value-format="MM-DD" />
    <p>Month/day array: {{ JSON.stringify(range) }}</p>
  </c-space>
</template>
```

### Text Entry

Example source: src/date/picker/__demos__/text-entry.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const value = ref('2025-01-15')
const range = ref(['2025-01-15', '2025-01-20'])
const panelOnly = ref(false)
</script>

<template>
  <p>输入 DD/MM/YYYY，Enter 或失焦提交；非法日期和范围外输入恢复模型显示。</p>
  <c-date v-model="value" format="DD/MM/YYYY" min="2025-01-10" max="2025-01-25" :input-editable="!panelOnly" />
  <p>模型：{{ value }}</p>
  <c-switch v-model="panelOnly" />
  <p>仅面板选择：{{ panelOnly }}</p>
  <c-date-range v-model="range" format="DD/MM/YYYY" :disabled="[true, false]" :input-editable="!panelOnly" />
  <p>起点锁定，终点不能早于起点：{{ range }}</p>
</template>
```

## Interaction and field configuration

### Api Review

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration             | Purpose                                                                      | Related examples                    |
| ------------------------- | ---------------------------------------------------------------------------- | ----------------------------------- |
| `open`                    | Controlled popup visibility                                                  | Rejected Close, Passthrough Options |
| `date-range-picker-props` | Panel presentation options                                                   | Field Panel Tools, Entry Boundary   |
| `value-format`            | Model and event value format: a date format string, Date, or timestamp       | Api Review                          |
| `readonly`                | Read-only interaction                                                        | Api Review                          |
| `format`                  | Display format                                                               | Field Panel Tools                   |
| `popup-props`             | Trigger presentation options; cannot override owned visibility or date rules | Passthrough Options                 |

<!-- demo-config-notes:end -->

</details>

Example source: src/date-range/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(["2026-10-23", "2026-10-25"]);
const __demoState = __demoReactive({ readonly: false, error: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-date-range
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="__demoState"
    ></c-date-range>
  </c-space>
</template>
```

### Rejected Close

Example source: src/date-range/__demos__/rejected-close.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["2026-09-22", "2026-09-24"]);
const open = ref(false);
const closeRequests = ref(0);
const commits = ref(0);

function requestOpen(next) {
  if (next) open.value = true;
  else closeRequests.value++;
}
</script>

<template>
  <c-space direction="column" size="12px">
    <p>
      关闭请求会被父级拒绝；修改起止日期后可再次确认，重复确认不应重复提交。
    </p>
    <c-date-range
      v-model="value"
      :open="open"
      @update:open="requestOpen"
      @change="commits++"
    >
      <template #actions="{ confirm, disabled }">
        <c-button :disabled="disabled" @click="confirm()">确认</c-button>
        <c-button @click="open = false">允许关闭</c-button>
      </template>
    </c-date-range>
    <span data-test="date-range-transaction-state"
      >值：{{ value.join(" ~ ") }}；提交：{{ commits }}；拒绝关闭：{{
        closeRequests
      }}</span
    >
  </c-space>
</template>
```

### Field Panel Tools

Example source: src/date-range/__demos__/field-panel-tools.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateShortcut } from "@cedar-design/ui";

const selected = ref(["2025-01-15", "2025-01-20"]);
const viewport = ref(["2025-01-01", "2025-02-01"]);
const acceptNavigation = ref(true);
const notice = ref("");
const shortcutNotice = ref("");
const shortcuts: DateShortcut[] = [
  { label: "下个月", value: ["2025-02-15", "2025-02-20"] },
  { label: "不可选", value: ["2025-03-01", "2025-03-05"], disabled: true },
];
function navigate(value: unknown) {
  if (
    acceptNavigation.value &&
    Array.isArray(value) &&
    value.length === 2 &&
    value.every((part) => typeof part === "string")
  )
    viewport.value = value;
}
function observe(_value: unknown, _dates: unknown, texts: unknown) {
  notice.value = String(texts);
}
function choose(shortcut: DateShortcut) {
  shortcutNotice.value = String(shortcut.label);
}
</script>

<template>
  <c-checkbox v-model="acceptNavigation"> 接受视口请求</c-checkbox>
  <c-date-range
    v-model="selected"
    :input-editable="false"
    format="DD/MM/YYYY"
    :date-range-picker-props="{ pickerValue: viewport, shortcuts }"
    @update:picker-value="navigate"
    @picker-value-change="observe"
    @select-shortcut="choose"
  />
  <p>选择模型：{{ selected }}；受控视口：{{ viewport }}</p>
  <p>视口通知：{{ notice }}；快捷项通知：{{ shortcutNotice }}</p>
  <p>
    导航不改变选择模型；拒绝视口请求后，日历仍显示原月份。快捷项先选择草稿，确认后提交。
  </p>
</template>
```

### Entry Boundary

Example source: src/date-range/__demos__/entry-boundary.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateValue } from "@cedar-design/ui";
const limited = ref(true);
const blockEnd20 = ref(false);
const disabledEnd = (date: Date, side: "start" | "end") =>
  side === "end" && blockEnd20.value && date.getDate() === 20;
const fieldValue = ref<DateValue[]>(["2025-02-12", "2025-02-14"]);
const panelValue = ref<DateValue[]>(["2025-02-12", "2025-02-14"]);
</script>

<template>
  <div class="entry-demo">
    <p>仅允许选择 2025 年 2 月；移除限制不会改变已有选中值。</p>
    <c-button @click="limited = !limited">{{
      limited ? "移除日期限制" : "恢复日期限制"
    }}</c-button>
    <div>
      <p>范围字段：管理输入、浮层和确认流程。</p>
      <c-date-range
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="fieldValue"
        :date-range-picker-props="{ dayStartOfWeek: 1 }"
      />
    </div>
    <div>
      <p>范围面板：日历从周一开始，点击确认后才提交。</p>
      <c-checkbox v-model="blockEnd20">
        禁用20日结束（不改已提交值）</c-checkbox
      >
      <c-date-range-picker
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="panelValue"
        :day-start-of-week="1"
        :disable-confirm="false"
        :disabled-date="disabledEnd"
      >
        <template #actions="{ confirm, disabled }">
          <c-button :disabled="disabled" @click="confirm"
            >提交日期范围</c-button
          >
        </template>
      </c-date-range-picker>
      <p>已提交：{{ panelValue.join(" ~ ") }}</p>
    </div>
  </div>
</template>

<style scoped>
.entry-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
</style>
```

### Passthrough Options

Example source: src/date-range/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateRangePopupOptions } from "@cedar-design/ui";
const open = ref(false);
const popupOptions: DateRangePopupOptions = {
  placement: "top-start",
  popupTranslate: [0, -8],
  popupContainer: false,
};
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-date-range
      edit-mode="direct"
      v-model:open="open"
      :popup-props="popupOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### Props

| Arguments                 | Description                                                                                                                      | Type                                       | Default   |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | --------- |
| `open-trigger-target`     | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                        | `'field'` |
| `model-value`             | Bound value                                                                                                                      | `(Date \| string \| number)[]`             | `-`       |
| `type`                    | Date precision                                                                                                                   | `date \| week \| month \| year \| quarter` | `date`    |
| `open`                    | Controlled popup visibility                                                                                                      | `boolean`                                  | `-`       |
| `clearable`               | Show the clear action                                                                                                            | `boolean`                                  | `true`    |
| `disabled`                | Disable interaction                                                                                                              | `boolean \| boolean[]`                     | `-`       |
| `readonly`                | Read-only interaction                                                                                                            | `boolean`                                  | `false`   |
| `size`                    | Component size                                                                                                                   | `xs \| sm \| md \| lg \| xl`               | `-`       |
| `variant`                 | Field appearance                                                                                                                 | `filled \| outline \| standard`            | `filled`  |
| `separator`               | Range separator                                                                                                                  | `string`                                   | `-`       |
| `placeholder`             | Placeholder                                                                                                                      | `string[]`                                 | `-`       |
| `disabled-date`           | Return true to disable a date                                                                                                    | `Function`                                 | `-`       |
| `format`                  | Display format                                                                                                                   | `string`                                   | `-`       |
| `show-time`               | Include time selection                                                                                                           | `boolean`                                  | `false`   |
| `date-range-picker-props` | Panel presentation options                                                                                                       | `DateRangePickerOptions`                   | `{}`      |

#### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/date-range/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-date-range
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref(["2026-10-27", "2026-10-28"]);
</script>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## Reading direction

Range values remain `[start, end]` across direction changes; switching direction neither swaps endpoints nor commits drafts. Range ribbons and boundary corners follow reading order. Paged calendar grids use visual Left/Right focus movement and chronological rows. Maple endpoint editing and continuous range highlighting are separate presentations. Explicit shortcut positions `left/right` remain physical, and popovers inherit their source direction.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Arguments                 | Description                                                                                                                      | Type                                       | Default   |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | --------- |
| `open-trigger-target`     | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                        | `'field'` |
| `model-value`             | Bound value                                                                                                                      | `(Date \| string \| number)[]`             | `-`       |
| `type`                    | Date precision                                                                                                                   | `date \| week \| month \| year \| quarter` | `date`    |
| `open`                    | Controlled popup visibility                                                                                                      | `boolean`                                  | `-`       |
| `clearable`               | Show the clear action                                                                                                            | `boolean`                                  | `true`    |
| `disabled`                | Disable interaction                                                                                                              | `boolean \| boolean[]`                     | `-`       |
| `readonly`                | Read-only interaction                                                                                                            | `boolean`                                  | `false`   |
| `size`                    | Size                                                                                                                             | `xs \| sm \| md \| lg \| xl`               | `-`       |
| `variant`                 | Field appearance                                                                                                                 | `filled \| outline \| standard`            | `filled`  |
| `separator`               | Range separator                                                                                                                  | `string`                                   | `-`       |
| `placeholder`             | Placeholder                                                                                                                      | `string[]`                                 | `-`       |
| `disabled-date`           | Return true to disable a date                                                                                                    | `Function`                                 | `-`       |
| `format`                  | Display format                                                                                                                   | `string`                                   | `-`       |
| `show-time`               | Include time selection                                                                                                           | `boolean`                                  | `false`   |
| `date-range-picker-props` | Panel presentation options                                                                                                       | `DateRangePickerOptions`                   | `{}`      |

### Shared date-family contract

| Arguments         | Description                                                                   | Type                                               | Default      |
| ----------------- | ----------------------------------------------------------------------------- | -------------------------------------------------- | ------------ |
| `default-value`   | Uncontrolled initial value, read once                                         | DateValue / DateValue[]                            | —            |
| `value-format`    | Model and event value format: a date format string, Date, or timestamp        | string                                             | Follows type |
| `min` / `max`     | Inclusive bounds; string bounds use value-format                              | DateValue                                          | —            |
| `disabled-time`   | Disabled times for the current date and endpoint                              | (date: Date, side: DateSide) => DateDisabledTime   | —            |
| `disable-confirm` | Commit immediately                                                            | boolean                                            | false        |
| `default-open`    | Uncontrolled initial open state                                               | boolean                                            | false        |
| `popup-props`     | Trigger presentation options; cannot override owned visibility or date rules  | object                                             | {}           |
| `popup-container` | Portal target; the top-level value wins, including false for inline rendering | string / HTMLElement / (() => HTMLElement) / false | —            |

`DateValue = Date | string | number`. Clearing a single value produces undefined; clearing a range produces [].
The date argument of `disabledDate(date, side)` and `disabledTime(date, side)` is always a Date; side is start/end.

`disabled-date` restricts range endpoints. A range may cross disabled interior values; it is not scanned item by item or truncated automatically. This applies to dates, months and years. Interior disabled values remain gray. Changing pages preserves the selected start and clears hover preview; reverse selection is sorted chronologically.
Time callbacks return numeric lists from `disabledHours()`, `disabledMinutes(hour)` and `disabledSeconds(hour, minute)`.
Invalid dates and incomplete/reversed ranges cannot be committed. Confirmation revalidates dynamic disabling rules. Locked range endpoints cannot be cleared or changed.
Nested panel props configure presentation only; they must not override top-level model-value, format, bounds, disabling rules or control events.

### Events

| Event                         | Description                               | Arguments                         |
| ----------------------------- | ----------------------------------------- | --------------------------------- |
| `update:model-value`          | Request a model update                    | value                             |
| `select`                      | Select a draft; does not imply submission | value, date(s), formatted text(s) |
| `change`                      | Committed value changes                   | value, date(s), formatted text(s) |
| `update:open` / `open-change` | Popup visibility changes                  | open: boolean                     |
| `clear`                       | Clear the selection                       | None                              |
| `focus` / `blur`              | Focus enters or leaves the whole field    | None                              |
| `click`                       | Click the field                           | event                             |

Desktop supports keyboard editing. The default panel edits a draft before confirmation; disable-confirm commits directly. Escape or closing discards the draft. focus(index = 0) focuses a start/end input, and blur() closes the popup.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/date.md

<!-- Source: src/date/README.en-US.md; locale: en-US; page: /en/components/date/ -->

# Date

Floating date panels use the visual viewport height so the full calendar is visible when space permits. Short windows scroll content while keeping actions visible. Override `--c-date-picker-popover-max-height` to adjust the limit (default `100dvh - 32px`).

A date field with a trigger. Use DatePicker for a standalone panel.

## String models and time zones

format controls display; value-format controls the model and events. Use YYYY-MM-DD for a date string or YYYY-MM for a month string. MM-DD has no year and parsing uses the current year, so retain a full date for cross-year ordering or explicit leap-year rules.

Omitting time-zone preserves browser-local behavior. With an IANA time zone, Date and timestamps represent instants while strings represent local civil times in that zone. Invalid DST times are rejected; newly entered repeated times resolve to the first occurrence. Untouched Date/timestamp range endpoints preserve their exact instant and hidden precision. Maple-only scroll/line views do not change Cedar panel defaults.

## Basic examples

### Basic

Example source: src/date/__demos__/basic.vue

```vue
<template>
  <c-date v-model="value" style="width: 200px" clearable />
</template>

<script setup>
import { ref } from 'vue'

const value = ref()
</script>
```

### Interaction state comparison

Toggle disabled, read-only and error states, then interact with the same instance. Recovery controls remain outside the target; error appearance alone does not validate data.

<details>
<summary>Configuration details and limits</summary>

#### State Lab

## Appearance and date presentation

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                                | Related examples                                      |
| -------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | Appearance configuration comparison, Locale Isolation |
| `type`         | Type                                                                   | Type, Locale Isolation                                |
| `size`         | Size                                                                   | Control Sizes                                         |
| `variant`      | Field appearance                                                       | Control Sizes                                         |
| `placeholder`  | Placeholder                                                            | Control Sizes                                         |
| `clearable`    | Show the clear action                                                  | Type                                                  |

<!-- demo-config-notes:end -->

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/date/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("2026-10-23");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-date
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-date>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Control Sizes

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### Type

Example source: src/date/__demos__/type.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-date v-model="date" style="width: 200px" clearable />
    <c-date v-model="week" type="week" style="width: 200px" clearable />
    <c-date v-model="month" type="month" style="width: 200px" clearable />
    <c-date v-model="year" type="year" style="width: 200px" clearable />
    <c-date v-model="quarter" type="quarter" style="width: 200px" clearable />
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const date = ref()
const week = ref()
const month = ref()
const year = ref()
const quarter = ref()
</script>
```

### Month Labels

Example source: src/date/picker/__demos__/month-labels.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const abbreviation = ref(true)
</script>

<template>
  <c-checkbox v-model="abbreviation">月份缩写</c-checkbox>
  <c-date-picker type="month" picker-value="2025-01" :abbreviation="abbreviation" :disable-confirm="false" />
  <c-date-range-picker type="month" :abbreviation="abbreviation" />
</template>
```

### Locale Isolation

Example source: src/date/picker/__demos__/locale-isolation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const first = ref('2021-01-03')
const second = ref('2021-01-03')
const monday = ref(true)
const monthModel = ref('2025 January 15')
</script>

<template>
  <p>两个实例独立管理周起始日。可切换顶部语言，模型不随展示语言改变。</p>
  <c-date v-model="first" type="week" :date-picker-props="{ dayStartOfWeek: 0 }" />
  <c-date v-model="second" type="week" :date-picker-props="{ dayStartOfWeek: monday ? 1 : 2 }" />
  <c-checkbox v-model="monday">第二个实例周一起始（关闭为周二）</c-checkbox>
  <c-date-picker type="week" v-model="first" picker-value="2021-01-01" :day-start-of-week="0" />
  <c-date-picker type="week" v-model="second" picker-value="2021-01-01" :day-start-of-week="monday ? 1 : 2" />
  <c-date v-model="monthModel" value-format="YYYY MMMM DD" format="YYYY MMMM DD" />
  <p>月份名称模型（稳定英文协议）：{{ monthModel }}</p>
</template>
```

## Time and selection rules

### Show Time

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                                | Related examples |
| -------------- | ---------------------------------------------------------------------- | ---------------- |
| `show-time`    | Include time selection                                                 | Show Time        |
| `format`       | Display format                                                         | Show Time        |
| `value-format` | Model and event value format: a date format string, Date, or timestamp | Show Time        |
| `clearable`    | Show the clear action                                                  | Show Time        |

<!-- demo-config-notes:end -->

Example source: src/date/__demos__/show-time.vue

```vue
<script setup>
import { ref } from 'vue'
const minute = ref()
const second = ref()
</script>

<template>
  <c-space direction="column" size="lg">
    <span>分钟精度：显式设置显示格式和模型格式</span>
    <c-date v-model="minute" show-time format="YYYY-MM-DD HH:mm" value-format="YYYY-MM-DD HH:mm" clearable />
    <span>已提交值：{{ minute || '未选择' }}</span>
    <span>秒精度：Cedar 的日期时间默认格式</span>
    <c-date v-model="second" show-time clearable />
    <span>已提交值：{{ second || '未选择' }}</span>
  </c-space>
</template>
```

### Time Presentation

Example source: src/date/picker/__demos__/time-presentation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const use12Hours = ref(true)
const timeOptions = { step: { minute: 15 }, hideDisabledOptions: true }
</script>

<template>
  <c-checkbox v-model="use12Hours">十二小时展示</c-checkbox>

  <c-date-picker
    model-value="2025-01-05 13:30"
    show-time
    format="YYYY-MM-DD HH:mm"
    value-format="YYYY-MM-DD HH:mm"
    :time-picker-props="{ ...timeOptions, use12Hours }"
  />
</template>
```

## Value model and text input

### Value Formats

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration       | Purpose                                                                | Related examples                         |
| ------------------- | ---------------------------------------------------------------------- | ---------------------------------------- |
| `format`            | Display format                                                         | Value Formats, String Values, Text Entry |
| `value-format`      | Model and event value format: a date format string, Date, or timestamp | Value Formats, String Values             |
| `type`              | Type                                                                   | String Values, Period Text               |
| `date-picker-props` | Panel presentation options                                             | Period Text                              |

<!-- demo-config-notes:end -->

Example source: src/date/__demos__/value-formats.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const timestamp = ref(new Date(2026, 8, 15).getTime())
const objectValue = ref(new Date(2026, 8, 16))
</script>
<template>
  <div class="date-contract-demo">
    <c-date v-model="timestamp" value-format="timestamp" format="DD/MM/YYYY" />
    <p>时间戳模型：{{ timestamp }}</p>
    <c-date v-model="objectValue" value-format="Date" format="YYYY年MM月DD日" />
    <p>Date 对象模型：{{ objectValue }}</p>
  </div>
</template>
<style scoped>
.date-contract-demo { display: flex; flex-direction: column; gap: 12px; }
.date-contract-demo p { margin: 0; }
</style>
```

### String Values

Example source: src/date/__demos__/en-US/string-values.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const date = ref("2026-09-10");
const month = ref("2026-09");
const range = ref(["09-10", "10-10"]);
</script>
<template>
  <c-space direction="column">
    <c-date v-model="date" format="YYYY-MM-DD" value-format="YYYY-MM-DD" />
    <p>String: {{ JSON.stringify(date) }}</p>
    <c-date
      v-model="month"
      type="month"
      format="YYYY-MM"
      value-format="YYYY-MM"
    />
    <p>Month string: {{ JSON.stringify(month) }}</p>
    <c-date-range v-model="range" format="MM-DD" value-format="MM-DD" />
    <p>Month/day array: {{ JSON.stringify(range) }}</p>
  </c-space>
</template>
```

### Period Text

Example source: src/date/picker/__demos__/period-text.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const week = ref('2020-12-28')
const quarter = ref('2025-04')
const range = ref(['2020-12-28', '2021-01-04'])
</script>

<template>
  <p>周一起始，中文可手输 2020-53周；切换英文后使用英文序数。提交为该周起始日。</p>
  <c-date v-model="week" type="week" :date-picker-props="{ dayStartOfWeek: 1 }" />
  <p>周模型：{{ week }}</p>
  <c-date v-model="quarter" type="quarter" />
  <p>季度输入 2025-Q2，模型为季度首月：{{ quarter }}</p>
  <c-date-range v-model="range" type="week" :date-range-picker-props="{ dayStartOfWeek: 1 }" />
  <p>周范围不自动交换手输端点：{{ range }}</p>
</template>
```

### Text Entry

Example source: src/date/picker/__demos__/text-entry.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const value = ref('2025-01-15')
const range = ref(['2025-01-15', '2025-01-20'])
const panelOnly = ref(false)
</script>

<template>
  <p>输入 DD/MM/YYYY，Enter 或失焦提交；非法日期和范围外输入恢复模型显示。</p>
  <c-date v-model="value" format="DD/MM/YYYY" min="2025-01-10" max="2025-01-25" :input-editable="!panelOnly" />
  <p>模型：{{ value }}</p>
  <c-switch v-model="panelOnly" />
  <p>仅面板选择：{{ panelOnly }}</p>
  <c-date-range v-model="range" format="DD/MM/YYYY" :disabled="[true, false]" :input-editable="!panelOnly" />
  <p>起点锁定，终点不能早于起点：{{ range }}</p>
</template>
```

## Interaction and field configuration

### Api Review

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration       | Purpose                                                                | Related examples                    |
| ------------------- | ---------------------------------------------------------------------- | ----------------------------------- |
| `disabled`          | Disable interaction                                                    | Api Review, Field Protocol          |
| `open`              | Controlled popup visibility                                            | Rejected Close, Passthrough Options |
| `date-picker-props` | Panel presentation options                                             | Field Panel Tools, Entry Boundary   |
| `placeholder`       | Placeholder                                                            | Field Protocol, Entry Boundary      |
| `value-format`      | Model and event value format: a date format string, Date, or timestamp | Api Review                          |
| `readonly`          | Read-only interaction                                                  | Api Review                          |

<!-- demo-config-notes:end -->

</details>

Example source: src/date/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("2026-10-23");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-date
      v-model="value"
      value-format="YYYY-MM-DD"
      v-bind="__demoState"
    ></c-date>
  </c-space>
</template>
```

### Rejected Close

Example source: src/date/__demos__/rejected-close.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("2026-09-22");
const open = ref(false);
const closeRequests = ref(0);
const commits = ref(0);

function requestOpen(next) {
  if (next) open.value = true;
  else closeRequests.value++;
}
</script>

<template>
  <c-space direction="column" size="12px">
    <p>关闭请求会被父级拒绝；选择新日期后可再次确认，重复确认不应重复提交。</p>
    <c-date
      v-model="value"
      :open="open"
      @update:open="requestOpen"
      @change="commits++"
    >
      <template #actions="{ confirm, disabled }">
        <c-button :disabled="disabled" @click="confirm()">确认</c-button>
        <c-button @click="open = false">允许关闭</c-button>
      </template>
    </c-date>
    <span data-test="date-transaction-state"
      >值：{{ value }}；提交：{{ commits }}；拒绝关闭：{{ closeRequests }}</span
    >
  </c-space>
</template>
```

### Field Panel Tools

Example source: src/date/picker/__demos__/field-panel-tools.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateShortcut } from "@cedar-design/ui";

const selected = ref("2025-01-15");
const viewport = ref("2025-01-01");
const acceptNavigation = ref(true);
const notice = ref("");
const shortcutNotice = ref("");
const shortcuts: DateShortcut[] = [
  { label: "下个月", value: "2025-02-15" },
  { label: "不可选", value: "2025-03-01", disabled: true },
];
function navigate(value: unknown) {
  if (acceptNavigation.value && typeof value === "string")
    viewport.value = value;
}
function observe(_value: unknown, _dates: unknown, texts: unknown) {
  notice.value = String(texts);
}
function choose(shortcut: DateShortcut) {
  shortcutNotice.value = String(shortcut.label);
}
</script>

<template>
  <c-checkbox v-model="acceptNavigation"> 接受视口请求</c-checkbox>
  <c-date
    v-model="selected"
    :input-editable="false"
    format="DD/MM/YYYY"
    :date-picker-props="{ pickerValue: viewport, shortcuts }"
    @update:picker-value="navigate"
    @picker-value-change="observe"
    @select-shortcut="choose"
  />
  <p>选择模型：{{ selected }}；受控视口：{{ viewport }}</p>
  <p>视口通知：{{ notice }}；快捷项通知：{{ shortcutNotice }}</p>
  <p>
    导航不改变选择模型；拒绝视口请求后，日历仍显示原月份。快捷项先选择草稿，确认后提交。
  </p>
</template>
```

### Field Protocol

Example source: src/date/__demos__/field-protocol.vue

```vue
<script setup>
import { ref } from 'vue'
const disabled = ref(false)
const date = ref('2026-09-22')
const dateRange = ref(['2026-09-22', '2026-09-24'])
const time = ref('09:00:00')
const timeRange = ref(['23:00:00', '01:00:00'])
</script>

<template>
  <c-space direction="column">
    <p>范围字段：点击右侧输入可从结束端选择；Tab 切换两端不提交，回车或离开整个字段再提交。</p>
    <span>禁用字段</span>
    <c-switch v-model="disabled" aria-label="禁用字段" />
    <c-date v-model="date" :disabled="disabled" clearable placeholder="日期" />
    <c-date-range v-model="dateRange" :disabled="disabled" clearable :placeholder="['开始日期', '结束日期']" />
    <c-time v-model="time" :disabled="disabled" clearable placeholder="时间" />
    <c-time-range v-model="timeRange" :disabled="disabled" clearable show-next-day :placeholder="['开始时间', '结束时间']" />
    <p>日期：{{ date || '未选择' }}；日期范围：{{ dateRange }}</p>
    <p>时间：{{ time || '未选择' }}；时间范围：{{ timeRange }}</p>
  </c-space>
</template>
```

### Entry Boundary

Example source: src/date/picker/__demos__/entry-boundary.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DateSelection } from "@cedar-design/ui";
const limited = ref(true);
const fieldValue = ref<DateSelection>("2025-02-12");
const panelValue = ref<DateSelection>("2025-02-12");
const week = ref<0 | 1 | 6>(1);
</script>

<template>
  <div class="entry-demo">
    <p>仅允许选择 2025 年 2 月；移除限制不会改变已有选中值。</p>
    <c-button @click="limited = !limited">{{
      limited ? "移除日期限制" : "恢复日期限制"
    }}</c-button>
    <c-space wrap>
      <c-button @click="week = 0">周日起始</c-button>
      <c-button @click="week = 1">周一起始</c-button>
      <c-button @click="week = 6">周六起始</c-button>
    </c-space>
    <div>
      <p>字段：管理输入与浮层；面板参数放在 date-picker-props。</p>
      <c-date
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="fieldValue"
        :date-picker-props="{ dayStartOfWeek: week }"
        placeholder="选择日期"
      />
    </div>
    <div>
      <p>纯面板：直接嵌入页面，不使用 open / popup-container。</p>
      <c-date-picker
        :min="limited ? '2025-02-01' : undefined"
        :max="limited ? '2025-02-28' : undefined"
        v-model="panelValue"
        :day-start-of-week="week"
        :disable-confirm="false"
      />
      <p>已提交：{{ panelValue }}</p>
    </div>
  </div>
</template>

<style scoped>
.entry-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
</style>
```

### Passthrough Options

Example source: src/date/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DatePopupOptions } from "@cedar-design/ui";
const open = ref(false);
const popupOptions: DatePopupOptions = {
  placement: "top-start",
  popupTranslate: [0, -8],
  popupContainer: false,
};
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-date
      edit-mode="direct"
      v-model:open="open"
      :popup-props="popupOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### Props

| Arguments             | Description                                                                                                                      | Type                                       | Default         |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | --------------- |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                        | `'field'`       |
| `model-value`         | Bound value                                                                                                                      | `Date \| string \| number`                 | `-`             |
| `type`                | Date precision                                                                                                                   | `date \| week \| month \| year \| quarter` | `date`          |
| `open`                | Controlled popup visibility                                                                                                      | `boolean`                                  | `-`             |
| `clearable`           | Show the clear action                                                                                                            | `boolean`                                  | `true`          |
| `disabled`            | Disable interaction                                                                                                              | `boolean`                                  | `false`         |
| `readonly`            | Read-only interaction                                                                                                            | `boolean`                                  | `false`         |
| `size`                | Component size                                                                                                                   | `xs \| sm \| md \| lg \| xl`               | `-`             |
| `variant`             | Field appearance                                                                                                                 | `filled \| outline \| standard`            | `filled`        |
| `placeholder`         | Placeholder                                                                                                                      | `string`                                   | `-`             |
| `disabled-date`       | Return true to disable a date                                                                                                    | `Function`                                 | `-`             |
| `format`              | Display format                                                                                                                   | `string \| Function`                       | Depends on type |
| `show-time`           | Include time selection                                                                                                           | `boolean`                                  | `false`         |
| `date-picker-props`   | Panel presentation options                                                                                                       | `DatePickerOptions`                        | `{}`            |

#### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/date/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-date
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("2026-10-27");
</script>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## Reading direction

Inherits the nearest `dir="ltr|rtl"`, including runtime changes and local overrides. Calendar dates, months and years follow reading order; navigation icons mirror, while date values keep their meaning. In paged grids, Left/Right moves focus visually, Up/Down moves one row, and Home/End moves to the row boundary, skipping disabled items. Focus navigation does not select; Enter/Space keeps the existing selection behavior. Navigation is bounded by the displayed grid. Explicit `shortcuts-position="left|right"` remains physical; `bottom` stays below. Field popovers inherit their source direction.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Arguments             | Description                                                                                                                      | Type                                       | Default        |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------------- |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                        | `'field'`      |
| `model-value`         | Bound value                                                                                                                      | `Date \| string \| number`                 | `-`            |
| `type`                | Date precision                                                                                                                   | `date \| week \| month \| year \| quarter` | `date`         |
| `open`                | Controlled popup visibility                                                                                                      | `boolean`                                  | `-`            |
| `clearable`           | Show the clear action                                                                                                            | `boolean`                                  | `true`         |
| `disabled`            | Disable interaction                                                                                                              | `boolean`                                  | `false`        |
| `readonly`            | Read-only interaction                                                                                                            | `boolean`                                  | `false`        |
| `size`                | Size                                                                                                                             | `xs \| sm \| md \| lg \| xl`               | `-`            |
| `variant`             | Field appearance                                                                                                                 | `filled \| outline \| standard`            | `filled`       |
| `placeholder`         | Placeholder                                                                                                                      | `string`                                   | `-`            |
| `disabled-date`       | Return true to disable a date                                                                                                    | `Function`                                 | `-`            |
| `format`              | Display format                                                                                                                   | `string \| Function`                       | Follows `type` |
| `show-time`           | Include time selection                                                                                                           | `boolean`                                  | `false`        |
| `date-picker-props`   | Panel presentation options                                                                                                       | `DatePickerOptions`                        | `{}`           |

### Shared date-family contract

| Arguments         | Description                                                                                                                                                                                                                                             | Type                                               | Default      |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------ |
| `default-value`   | Uncontrolled initial value, read once                                                                                                                                                                                                                   | DateValue / DateValue[]                            | —            |
| `value-format`    | Model and event value format: a date format string, Date, or timestamp                                                                                                                                                                                  | string                                             | Follows type |
| `min` / `max`     | Inclusive bounds; string bounds use value-format                                                                                                                                                                                                        | DateValue                                          | —            |
| `disabled-time`   | Disabled times for the current date and endpoint                                                                                                                                                                                                        | (date: Date, side: DateSide) => DateDisabledTime   | —            |
| `disable-confirm` | Commit immediately                                                                                                                                                                                                                                      | boolean                                            | false        |
| `default-open`    | Uncontrolled initial open state                                                                                                                                                                                                                         | boolean                                            | false        |
| `popup-props`     | Optional field-popup presentation settings. Placement defaults to bottom-start and is positioned automatically by the underlying Trigger; the preferred side can be overridden. No top-level placement prop; field state and rules cannot be overridden | object                                             | {}           |
| `popup-container` | Portal target; the top-level value wins, including false for inline rendering                                                                                                                                                                           | string / HTMLElement / (() => HTMLElement) / false | —            |

`DateValue = Date | string | number`. Clearing a single value produces undefined; clearing a range produces [].
The date argument of `disabledDate(date, side)` and `disabledTime(date, side)` is always a Date; side is start/end.
Time callbacks return numeric lists from `disabledHours()`, `disabledMinutes(hour)` and `disabledSeconds(hour, minute)`.
Invalid dates and incomplete/reversed ranges cannot be committed. Confirmation revalidates dynamic disabling rules. Locked range endpoints cannot be cleared or changed.
Nested panel props configure presentation only; they must not override top-level model-value, format, bounds, disabling rules or control events.

### Events

| Event                         | Description                               | Arguments                         |
| ----------------------------- | ----------------------------------------- | --------------------------------- |
| `update:model-value`          | Request a model update                    | value                             |
| `select`                      | Select a draft; does not imply submission | value, date(s), formatted text(s) |
| `change`                      | Committed value changes                   | value, date(s), formatted text(s) |
| `update:open` / `open-change` | Popup visibility changes                  | open: boolean                     |
| `clear`                       | Clear the selection                       | None                              |
| `focus` / `blur`              | Focus enters or leaves the whole field    | None                              |
| `click`                       | Click the field                           | event                             |

Desktop supports keyboard editing. The default panel edits a draft before confirmation; disable-confirm commits directly. Escape or closing discards the draft. focus(index = 0) focuses a start/end input, and blur() closes the popup.

## Explicit time zones

`timeZone` accepts IANA names such as `Asia/Shanghai`. Date objects and millisecond timestamps represent instants; strings represent local time in the target zone. Display, typed input, min/max, shortcuts and disabling rules use the same protocol; event Date objects retain the actual instant. Omitting `timeZone` preserves local-zone behavior. Nonexistent daylight-saving times and invalid zones cannot be committed; repeated times use the first occurrence. Maple scroll / line are mobile calendar presentations; desktop retains its existing panel.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

### Placement semantics and configuration

The Date field prefers bottom-start below its input. Override the preferred side through popupProps.placement only when needed; the underlying Trigger positions it, not Popup or Popover. DatePicker is a standalone date panel with no input anchor; placement in the legacy date/picker directory is not a current public DatePicker prop.

---

Document: llms/en-US/components/descriptions.md

<!-- Source: src/descriptions/README.en-US.md; locale: en-US; page: /en/components/descriptions/ -->

# Descriptions

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `data`: Supplies the example data.

Example source: src/descriptions/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <c-descriptions :data="data" title="User Info" />
    <c-descriptions :column="{ xs: 1, md: 3, lg: 4 }" title="User Info">
      <c-descriptions-item v-for="item of data" :key="item.label" :label="item.label" :span="item.span ?? 1">
        <c-tag>{{ item.value }}</c-tag>
      </c-descriptions-item>
    </c-descriptions>
  </c-space>
</template>

<script lang="ts" setup>
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

## Layout and arrangement

### Label Text Alignment

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Description-list data | Label Text Alignment, Layout Pattern |
| `title` | Description-list title | Label Text Alignment, Layout Pattern |
| `layout` | Description-list arrangement | Label Text Alignment, Layout Pattern |
| `align` | Text alignment | Label Text Alignment |
| `size` | Description-list size | Layout Pattern |
| `bordered` | Whether to show border | Layout Pattern |
<!-- demo-config-notes:end -->


- `data`: Supplies the example data.
- `align`: Controls alignment on the cross axis.

Example source: src/descriptions/__demos__/label-text-alignment.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-descriptions :data="data" align="right" title="User Info" />
    <c-descriptions :align="{ label: 'right' }" :data="data" title="User Info" />
    <c-descriptions :data="data" layout="inline-vertical" title="User Info" />
  </c-space>
</template>

<script lang="ts" setup>
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

### Layout Pattern

- `data`: Supplies the example data.
- `size`: Controls the component size.

Example source: src/descriptions/__demos__/layout-pattern.vue

```vue
<template>
  <c-radio-group v-model="size" variant="button">
    <c-radio value="xs">xs</c-radio>
    <c-radio value="sm">sm</c-radio>
    <c-radio value="md">md</c-radio>
    <c-radio value="lg">lg</c-radio>
    <c-radio value="xl">xl</c-radio>
  </c-radio-group>
  <div style="margin-top: 20px">
    <c-descriptions :data="data" :size="size" title="User Info (horizontal)" bordered />
    <c-descriptions :data="data" :size="size" title="User Info (inline-horizontal)" layout="inline-horizontal" bordered />
    <c-descriptions :data="data" :size="size" title="User Info (vertical)" layout="vertical" bordered />
    <c-descriptions :data="data" :size="size" title="User Info (inline-vertical)" layout="inline-vertical" bordered />
    <c-descriptions :data="inlineAutoData" :size="size" title="User Info (inline-auto)" layout="inline-auto" />
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')

const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]

const inlineAutoData = [
  {
    label: 'Name:',
    value: 'Socrates',
  },
  {
    label: 'Mobile:',
    value: '123-1234-1234',
  },
  {
    label: 'Residence:',
    value: 'Beijing',
  },
]
</script>
```

## Content and presentation

### Singel Column Style

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Description-list data | Singel Column Style, Border Background List |
| `title` | Description-list title | Singel Column Style, Border Background List |
| `column` | Items per row. Responsive configuration is supported since 2.20.0; see Grid | Singel Column Style |
| `size` | Description-list size | Singel Column Style |
| `bordered` | Whether to show border | Border Background List |
<!-- demo-config-notes:end -->


- `data`: Supplies the example data.
- `size`: Controls the component size.

Example source: src/descriptions/__demos__/singel-column-style.vue

```vue
<template>
  <c-radio-group v-model="size" variant="button">
    <c-radio value="xs">xs</c-radio>
    <c-radio value="sm">sm</c-radio>
    <c-radio value="md">md</c-radio>
    <c-radio value="lg">lg</c-radio>
    <c-radio value="xl">xl</c-radio>
  </c-radio-group>
  <c-descriptions :column="1" :data="data" :size="size" style="margin-top: 20px" title="User Info" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

### Border Background List

- `data`: Supplies the example data.

Example source: src/descriptions/__demos__/border-background-list.vue

```vue
<template>
  <c-descriptions :data="data" title="User Info" bordered />
</template>

<script lang="ts" setup>
const data = [
  {
    label: 'Name',
    value: 'Socrates',
  },
  {
    label: 'Mobile',
    value: '123-1234-1234',
  },
  {
    label: 'Residence',
    value: 'Beijing',
  },
  {
    label: 'Hometown',
    value: 'Beijing',
  },
  {
    label: 'Address',
    value: 'Yingdu Building, Zhichun Road, Beijing',
  },
]
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Labels, values, borders and default text alignment follow logical reading edges. Direction changes do not reverse records, column definitions or span semantics.

## API

### `<Descriptions>` Props

| Prop | Description | Type | Default |
| ------------ | ------------------------------------------------------------------ | :---------------------------------------------------------------------------------------: | :------------- |
| data | Description-list data | `DescData[]` | `[]` |
| column | Items per row. Responsive configuration is supported since 2.20.0; see Grid | `number \| ResponsiveValue` | `3` |
| title | Description-list title | `string` | `-` |
| layout | Description-list arrangement | `'horizontal' \| 'vertical' \| 'inline-horizontal' \| 'inline-vertical' \| 'inline-auto'` | `'horizontal'` |
| align | Text alignment | `TextAlign \| { label?: TextAlign; value?: TextAlign }` | `'left'` |
| size | Description-list size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `-` |
| bordered | Whether to show border | `boolean` | `false` |
| label-style | Label styles | `CSSProperties` | `-` |
| value-style | Content styles | `CSSProperties` | `-` |
| table-layout | Table-style `layout-fixed`; setting `fixed` distributes widths evenly | `'auto' \| 'fixed'` | `'auto'` |
| aria-label | Accessible description-list label | `string` | `-` |

### `<Descriptions>` Slots

| Slot | Description | Arguments |
| ------ | :------: | ------------------------------------------------------ |
| value | Content | value: `string`<br>index: `number`<br>data: `DescData` |
| label | Label | label: `string`<br>index: `number`<br>data: `DescData` |
| title | Title | - |

### `<DescriptionsItem>` Props

| Prop | Description | Type | Default |
| ----- | -------- | :------: | :----- |
| span | Column span | `number` | `1` |
| label | Label | `string` | `-` |

### `<DescriptionsItem>` Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| default | Content | - |
| label | Label | - |

### DescData

| Parameter | Description | Type | Default |
| ------ | -------- | -------------------------- | :----: |
| label | Label | `string \| RenderFunction` | `-` |
| value | Data | `string \| RenderFunction` | `-` |
| span | Column span | `number` | `-` |

## Type definitions

The component exports the following types

```ts
import type { DescriptionsProps } from "@cedar-design/ui";
```

---

Document: llms/en-US/components/dialog.md

<!-- Source: src/dialog/README.en-US.md; locale: en-US; page: /en/components/dialog/ -->

# Dialog

A modal dialog with matching declarative and programmatic APIs.

## Basic examples

### Basic

Example source: src/dialog/__demos__/basic.vue

```vue
<template>
  <c-button @click="open = true">Open Dialog</c-button>

  <c-dialog
    v-model:open="open"
    title="Dialog Title"
    message="This is a basic component dialog."
    @confirm="Message.success('Confirmed')"
    @cancel="Message.info('Cancelled')"
  />
</template>

<script setup lang="ts">
import { Message } from "@cedar-design/ui";
import { ref } from "vue";

const open = ref(false);
</script>
```

## Invocation and content

### Global

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title | Confirm, Form, Simple |
| `type` | Status icon: `info`, `success`, `warning` or `error` | Confirm, Simple |
| `message` | Message content; the default slot is also supported | Confirm, Simple |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | Form |
| `simple` | Compact layout with a centered footer | Simple |
<!-- demo-config-notes:end -->


Example source: src/dialog/__demos__/global.vue

```vue
<template>
  <c-space>
    <c-button @click="openBasic">Basic</c-button>
    <c-button @click="openDialog">Open</c-button>
    <c-button @click="openAndUpdate">Open and Update</c-button>
    <c-button @click="awaitAction">Await Action</c-button>
    <c-button @click="hideButtons">Hide Footer Buttons</c-button>
  </c-space>
</template>

<script setup lang="ts">
import { Dialog, Message } from "@cedar-design/ui";

function openBasic() {
  Dialog.open("This dialog was opened from a string message.");
}

function openDialog() {
  Dialog.open({
    title: "Global Method",
    message: "This dialog was opened programmatically.",
  });
}

function openAndUpdate() {
  const instance = Dialog.open({
    title: "Submitting",
    message: "Processing the request…",
  });
  window.setTimeout(
    () =>
      instance.update({
        title: "Completed",
        message: "The request succeeded.",
      }),
    800,
  );
}

async function awaitAction() {
  const action = await Dialog.open("Choose an action to close this dialog.");
  if (action) Message.info(`Dialog action: ${action}`);
}

function hideButtons() {
  Dialog.open({
    title: "No Footer Buttons",
    message: "Click the overlay or press Esc to dismiss this dialog.",
    confirmButton: false,
    cancelButton: false,
  });
}
</script>
```

### Alert

Example source: src/dialog/__demos__/alert.vue

```vue
<template>
  <c-button @click="handleClick">Alert</c-button>
</template>

<script lang="ts">
import { Dialog } from '@cedar-design/ui'

export default {
  setup() {
    const handleClick = () => {
      Dialog.alert({
        title: 'Alert',
        message: 'This is an alert description.',
        type: 'info',
      })
    }

    return { handleClick }
  },
}
</script>
```

### Confirm

Example source: src/dialog/__demos__/confirm.vue

```vue
<template>
  <c-space>
    <c-button @click="openConfirm">Confirm</c-button>
    <c-button status="danger" @click="openDangerConfirm">Delete</c-button>
    <c-button @click="componentOpen = true">Component Confirm</c-button>
  </c-space>

  <c-dialog
    v-model:open="componentOpen"
    type="warning"
    title="Confirm Action"
    message="Are you sure you want to continue?"
  />
</template>

<script setup lang="ts">
import { ref } from "vue";
import { Dialog, Message } from "@cedar-design/ui";

const componentOpen = ref(false);

async function openConfirm() {
  const action = await Dialog.confirm({
    title: "Confirm Action",
    message: "Are you sure you want to continue?",
  });
  if (action) Message.info(`Dialog action: ${action}`);
}

async function openDangerConfirm() {
  const action = await Dialog.confirm({
    title: "Dangerous Action",
    message: "This action cannot be undone. Continue?",
    confirmButtonText: "Delete",
    confirmButtonProps: { variant: "default", status: "danger" },
  });
  if (action) Message.info(`Dialog action: ${action}`);
}
</script>
```

### Message

Example source: src/dialog/__demos__/message.vue

```vue
<template>
  <c-space>
    <c-button @click="handleClickInfo">Info</c-button>
    <c-button status="success" @click="handleClickSuccess">Success</c-button>
    <c-button status="warning" @click="handleClickWarning">Warning</c-button>
    <c-button status="danger" @click="handleClickError">Error</c-button>
  </c-space>
</template>

<script lang="ts">
import { Dialog } from '@cedar-design/ui'

export default {
  setup() {
    const handleClickInfo = () => {
      Dialog.info({
        title: 'Info Notification',
        message: 'This is an info description which directly indicates a neutral informative change or action.',
      })
    }
    const handleClickSuccess = () => {
      Dialog.success({
        title: 'Success Notification',
        message: 'This is a success notification',
      })
    }
    const handleClickWarning = () => {
      Dialog.warning({
        title: 'Warning Notification',
        message: 'This is a warning description which directly indicates a warning that might need attention.',
      })
    }
    const handleClickError = () => {
      Dialog.error({
        title: 'Error Notification',
        message: 'This is an error description which directly indicates a dangerous or potentially negative action.',
      })
    }

    return {
      handleClickInfo,
      handleClickSuccess,
      handleClickWarning,
      handleClickError,
    }
  },
}
</script>
```

### Form

Example source: src/dialog/__demos__/form.vue

```vue
<template>
  <c-button @click="handleClick">Open Form Dialog</c-button>
  <c-dialog v-model:open="visible" title="Dialog Form" @cancel="handleCancel" :before-close="handleBeforeClose">
    <c-form :model="form">
      <c-form-item field="name" label="Name">
        <c-input v-model="form.name" />
      </c-form-item>
      <c-form-item field="post" label="Post">
        <c-select v-model="form.post">
          <c-option value="post1">Post1</c-option>
          <c-option value="post2">Post2</c-option>
          <c-option value="post3">Post3</c-option>
          <c-option value="post4">Post4</c-option>
        </c-select>
      </c-form-item>
    </c-form>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, reactive, ref } from 'vue'

export default defineComponent({
  setup() {
    const visible = ref(false)
    const form = reactive({
      name: '',
      post: '',
    })

    const handleClick = () => {
      visible.value = true
    }

    const handleBeforeClose = ({ action }, done) => {
      if (action !== 'confirm') {
        done()
        return
      }

      window.setTimeout(() => {
        done()
      }, 2000)
    }

    const handleCancel = () => {
      visible.value = false
    }

    return {
      visible,
      form,
      handleClick,
      handleBeforeClose,
      handleCancel,
    }
  },
})
</script>
```

### Simple

Example source: src/dialog/__demos__/simple.vue

```vue
<template>
  <c-button @click="open = true">Open Simple Dialog</c-button>

  <c-dialog
    v-model:open="open"
    simple
    type="info"
    title="Simple Dialog"
    message="A compact dialog for short and focused information."
  />
</template>

<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>
```

## Sizing and layout

### Dialog sizing and long content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title | No Padding, Max Height |
| `body-style` | Body style | No Padding, Max Height |
| `width` | Width | Dialog sizing and long content |
| `fullscreen` | Fullscreen layout | Dialog sizing and long content |
<!-- demo-config-notes:end -->


Open one dialog at a time to compare widths, fullscreen layouts and long-content boundaries.

Example source: src/dialog/__demos__/size-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


    const visibleSmall = ref(false)


    const visibleMedium = ref(false)


    const visibleLarge = ref(false)



    const handleClickSmall = () => {
      visibleSmall.value = true
    }


    const handleClickMedium = () => {
      visibleMedium.value = true
    }


    const handleClickLarge = () => {
      visibleLarge.value = true
    }


    const handleConfirm = () => {
      visibleSmall.value = false
      visibleMedium.value = false
      visibleLarge.value = false
    }


    const handleCancel = () => {
      visibleSmall.value = false
      visibleMedium.value = false
      visibleLarge.value = false
    }
return { visibleSmall, visibleMedium, visibleLarge, handleClickSmall, handleClickMedium, handleClickLarge, handleConfirm, handleCancel }
})())

const scene2 = demoProxyRefs((() => {


    const show = ref(false)



    const handleClick = () => {
      show.value = true
    }


    const handleConfirm = () => {
      show.value = false
    }


    const handleCancel = () => {
      show.value = false
    }
return { show, handleClick, handleConfirm, handleCancel }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="width">
    <h4><span lang="zh-CN">对话框宽度</span><span lang="en-US">Width</span></h4>
    <c-space>
        <c-button @click="scene1.handleClickSmall">Small Dialog</c-button>
        <c-button @click="scene1.handleClickMedium">Medium Dialog</c-button>
        <c-button @click="scene1.handleClickLarge">Large Dialog</c-button>
      </c-space>
      <c-dialog :width="400" v-model:open="scene1.visibleSmall" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel">
        <template #title>Small Dialog</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
      <c-dialog v-model:open="scene1.visibleMedium" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel">
        <template #title>Medium Dialog</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
      <c-dialog :width="720" v-model:open="scene1.visibleLarge" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel">
        <template #title>Large Dialog</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="fullscreen">
    <h4><span lang="zh-CN">全屏</span><span lang="en-US">Fullscreen</span></h4>
    <c-button @click="scene2.handleClick">Open Dialog</c-button>
      <c-dialog v-model:open="scene2.show" @confirm="scene2.handleConfirm" @cancel="scene2.handleCancel" fullscreen>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-dialog>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### No Padding

Example source: src/dialog/__demos__/no-padding.vue

```vue
<template>
  <c-space>
    <c-button @click="handleClick">Open Dialog</c-button>
  </c-space>

  <c-dialog
    v-model:open="show"
    title="no-padding"
    :body-style="{ padding: 0 }"
    @cancel="handleCancel"
    @confirm="handleConfirm"
  >
    <div class="p-24">
      You can customize modal body text by the current situation. This modal
      will be closed immediately once you press the OK button.
    </div>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, ref } from "vue";
export default defineComponent({
  setup() {
    const show = ref(false);

    const handleClick = () => {
      show.value = true;
    };
    const handleConfirm = () => {
      show.value = false;
    };
    const handleCancel = () => {
      show.value = false;
    };

    return {
      show,
      handleClick,
      handleConfirm,
      handleCancel,
    };
  },
});
</script>
```

### Max Height

Example source: src/dialog/__demos__/max-height.vue

```vue
<template>
  <c-button @click="open = true">Open Long Content Dialog</c-button>

  <c-dialog
    v-model:open="open"
    title="Long Content"
    :body-style="{ maxHeight: '50vh', overflowY: 'auto' }"
  >
    <p v-for="item in 12" :key="item">
      {{ item }}. Long dialog content remains scrollable while the title and
      actions stay visible.
    </p>
  </c-dialog>
</template>

<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>
```

## Interaction and customization

### Draggable

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `unmount-on-close` | Unmount after closing | Custom Text, Advanced |
| `draggable` | Draggable | Draggable |
| `confirm-button-text` | Confirm button text | Custom Text |
| `cancel-button-text` | Cancel button text | Custom Text |
| `footer` | Whether to show the footer | Advanced |
| `type` | Status icon: `info`, `success`, `warning` or `error` | Advanced |
<!-- demo-config-notes:end -->


Example source: src/dialog/__demos__/draggable.vue

```vue
<template>
  <c-button @click="handleClick">Open Dialog</c-button>
  <c-dialog v-model:open="show" @confirm="handleConfirm" @cancel="handleCancel" draggable>
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const show = ref(false)

    const handleClick = () => {
      show.value = true
    }
    const handleConfirm = () => {
      show.value = false
    }
    const handleCancel = () => {
      show.value = false
    }

    return {
      show,
      handleClick,
      handleConfirm,
      handleCancel,
    }
  },
})
</script>
```

### Custom Footer

Example source: src/dialog/__demos__/custom-footer.vue

```vue
<template>
  <c-button @click="open = true">Open Custom Footer Dialog</c-button>

  <c-dialog v-model:open="open">
    <template #title>Custom Slots</template>
    Use the footer slot when the actions need different priorities or wording.
    <template #footer="{ close, cancel, confirm }">
      <c-space>
        <c-button variant="text" @click="close">Later</c-button>
        <c-button variant="outline" @click="cancel">Cancel</c-button>
        <c-button status="primary" @click="confirm">Continue</c-button>
      </c-space>
    </template>
  </c-dialog>
</template>

<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>
```

### Custom Text

Example source: src/dialog/__demos__/custom-text.vue

```vue
<template>
  <c-button @click="handleClick">Open Dialog</c-button>
  <c-dialog
    v-model:open="show"
    @confirm="handleConfirm"
    @cancel="handleCancel"
    confirmButtonText="Confirm"
    cancelButtonText="Exit"
    unmountOnClose
  >
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-dialog>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const show = ref(false)

    const handleClick = () => {
      show.value = true
    }
    const handleConfirm = () => {
      show.value = false
    }
    const handleCancel = () => {
      show.value = false
    }

    return {
      show,
      handleClick,
      handleConfirm,
      handleCancel,
    }
  },
})
</script>
```

### Advanced

Example source: src/dialog/__demos__/advanced.vue

```vue
<template>
  <c-space>
    <c-button @click="footerHiddenOpen = true">Hide Footer</c-button>
    <c-button @click="titleHiddenOpen = true">Hide Title</c-button>
    <c-button @click="customBodyOpen = true">Custom Body</c-button>
    <c-button @click="unmountOpen = true">Unmount on Close</c-button>
  </c-space>

  <c-dialog
    v-model:open="footerHiddenOpen"
    :footer="false"
    type="info"
    title="Read Only"
    message="This dialog intentionally has no footer actions."
  />
  <c-dialog
    v-model:open="titleHiddenOpen"
    hide-title
    aria-label="Dialog without a visible title"
    type="warning"
    message="Use aria-label when the visible title is hidden."
  />
  <c-dialog
    v-model:open="customBodyOpen"
    type="info"
    title="Custom Body"
    message="The body supports custom alignment, classes, and inline styles."
    message-align="center"
    body-class="dialog-demo__body--custom"
    :body-style="{
      padding: '16px 20px',
      background: 'rgba(22, 93, 255, 0.08)',
      borderRadius: '8px',
    }"
  />
  <c-dialog
    v-model:open="unmountOpen"
    unmount-on-close
    title="Unmount on Close"
  >
    This content is removed from the DOM after the close transition.
  </c-dialog>
</template>

<script setup lang="ts">
import { ref } from "vue";

const footerHiddenOpen = ref(false);
const titleHiddenOpen = ref(false);
const customBodyOpen = ref(false);
const unmountOpen = ref(false);
</script>

<style scoped>
:deep(.dialog-demo__body--custom) {
  font-weight: 500;
}
</style>
```

## Async actions and closing

### Async

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | Async, Guard Protocol |
| `title` | Title | Async |
| `message` | Message content; the default slot is also supported | Async |
<!-- demo-config-notes:end -->


Example source: src/dialog/__demos__/async.vue

```vue
<template>
  <c-space>
    <c-button @click="asyncOpen = true">Async Close</c-button>
    <c-button @click="loadingOpen = true">Button Loading</c-button>
  </c-space>

  <c-dialog
    v-model:open="asyncOpen"
    title="Async Close"
    message="Every action waits for the asynchronous task to finish."
    :before-close="beforeClose"
  />
  <c-dialog
    v-model:open="loadingOpen"
    title="Button Loading"
    message="The confirm button displays loading while the task is running."
    :before-close="buttonLoadingClose"
  />
</template>

<script setup lang="ts">
import { ref } from "vue";
import type { DialogAction } from "../types";

const asyncOpen = ref(false);
const loadingOpen = ref(false);

function beforeClose({ action: _action }: { action: DialogAction }, done: () => void) {
  window.setTimeout(done, 1000);
}

function buttonLoadingClose(
  { action }: { action: DialogAction },
  done: () => void,

) {
  if (action !== "confirm") {
    done();
    return;
  }

  window.setTimeout(() => {
    done();
  }, 1000);
}
</script>
```

### Api Review

### Guard Protocol

Example source: src/dialog/__demos__/en-US/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DialogBeforeClose } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(false);
const status = ref("");
const check: DialogBeforeClose = (payload, done, { signal }) => {
  status.value = `Waiting: ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-switch v-model="allowed" />
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done callback' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">Open</c-button>
    <c-dialog
      v-model:open="open"
      :before-close="check"
      @guard-error="status = 'Error'"
    >
      <template #default
        ><c-button v-if="false" @click="open = true">Confirm action</c-button
        ><span v-else>Close with beforeClose</span></template
      >
    </c-dialog>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

### `<Dialog>` Props

| Name | Description | Type | Default |
| ------------------------- | -------------------------------------------- | -------------------------------- | ------------ |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| `open` **(v-model)** | Visible state | `boolean` | `-` |
| `default-open` | Initial uncontrolled state | `boolean` | `false` |
| `title` | Title | `string` | `-` |
| `message` | Message content; the default slot is also supported | `string` | `-` |
| `message-align` | Message alignment | `'left' \| 'center' \| 'right'` | `'left'` |
| `type` | Status icon: info, success, warning or error | `string` | `-` |
| `simple` | Compact layout with a centered footer | `boolean` | `false` |
| `width` | Width | `number \| string` | `-` |
| `top` | Top offset; ignored when align-center is enabled | `number \| string` | `-` |
| `title-align` | Title alignment | `'start' \| 'center'` | `'center'` |
| `align-center` | Center vertically and horizontally | `boolean` | `true` |
| `overlay` | Show overlay | `boolean` | `true` |
| `overlay-class` | Overlay class | `string` | `-` |
| `overlay-style` | Overlay style | `CSSProperties` | `-` |
| `overlay-closable` | Request closure on an overlay click | `boolean` | `true` |
| `esc-to-close` | Request closure on Escape | `boolean` | `true` |
| `lock-scroll` | Lock background scrolling while open | `boolean` | `true` |
| `close-on-route-change` | Close on browser history or hash changes | `boolean` | `false` |
| `popup-container` | Teleport target; `false` disables teleport | `string \| HTMLElement \| false` | `'body'` |
| `confirm-button` | Show the confirm button | `boolean` | `true` |
| `cancel-button` | Show the cancel button | `boolean` | `true` |
| `closable` | Show close button | `boolean` | `true` |
| `confirm-button-text` | Confirm button text | `string` | `-` |
| `cancel-button-text` | Cancel button text | `string` | `-` |
| `confirm-button-loading` | Confirm button loading state | `boolean` | `false` |
| `cancel-button-loading` | Cancel button loading state | `boolean` | `false` |
| `confirm-button-disabled` | Disable the confirm button | `boolean` | `false` |
| `cancel-button-disabled` | Disable the cancel button | `boolean` | `false` |
| `confirm-button-props` | Confirm button props | `ButtonProps` | `-` |
| `cancel-button-props` | Cancel button props | `ButtonProps` | `-` |
| `footer` | Show the footer | `boolean` | `true` |
| `dialog-class` | Dialog class | `string \| any[]` | `-` |
| `dialog-style` | Dialog style | `CSSProperties` | `-` |
| `body-class` | Body class | `string \| any[]` | `-` |
| `body-style` | Body style | `StyleValue` | `-` |
| `hide-title` | Hide the title | `boolean` | `false` |
| `unmount-on-close` | Unmount after closing | `boolean` | `false` |
| `draggable` | Allow dragging | `boolean` | `false` |
| `fullscreen` | Fullscreen layout | `boolean` | `false` |
| `overlay-animation-name` | Overlay animation name | `string` | `fade-modal` |
| `dialog-animation-name` | Dialog animation name | `string` | `zoom-modal` |
| `z-index` | Stack level | `number` | `-` |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | `DialogBeforeClose` | — |

### `<Dialog>` Events

| Event | Description | Arguments |
| ------------ | ------------- | --------------- |
| `open` | Opening begins | `-` |
| `opened` | Opening transition completes | `-` |
| `close` | Closing begins | `-` |
| `closed` | Closing transition completes | `-` |
| `confirm` | Accepted confirm action | `Event` |
| `cancel` | Accepted cancel or close action | `Event` |
| `click-overlay` | `MouseEvent` | `MouseEvent` |
| `key-escape` | ESC | `KeyboardEvent` |

### `<Dialog>` Slots

| Slot | Description | Arguments |
| --------- | ---- | ---------------------------- |
| `default` | Content | `-` |
| `title` | Title | `-` |
| `footer` | Footer | `cancel`, `confirm`, `close` |

### DialogConfig

| Name | Description | Type |
| ------------- | ---------------------------------- | -------------------------- |
| `content` | Renderable content; takes priority over message | `RenderContent` |
| `footer` | Footer visibility or custom footer content | `boolean \| RenderContent` |
| `onConfirm` | Confirm callback | `(e?: Event) => void` |
| `onCancel` | Cancel callback | `(e?: Event) => void` |
| `onClickOverlay` | Overlay click callback | `() => void` |
| `onKeyEscape` | Escape callback | `() => void` |

### DialogMethod

| Method | Description | Return value |
| ---------------------------------- | ------------------------------ | -------------------------------------- |
| `Dialog.open(config)` | Open a dialog | `Promise<DialogAction> & DialogReturn` |
| `Dialog.confirm(config)` | Confirmation dialog; defaults to warning | Same as above |
| `Dialog.alert(config)` | Alert dialog without a cancel button | Same as above |
| `Dialog.info(config)` | Information dialog | Same as above |
| `Dialog.success(config)` | Success dialog | Same as above |
| `Dialog.warning(config)` | Warning dialog | Same as above |
| `Dialog.error(config)` | Error dialog | Same as above |
| `Dialog.close()` | Close the latest functional dialog | `void` |
| `Dialog.setDefaultOptions(config)` | Set default programmatic options | `void` |
| `Dialog.resetDefaultOptions()` | Reset default programmatic options | `void` |

### DialogReturn

| Prop | Description |
| ---------------- | -------- |
| `close()` | Close |
| `update(config)` | Update options |

### Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Content, headings and action gaps use logical edges. Portals inherit their source direction. Direction changes preserve close, confirm, cancel and pending-state semantics.

## API details
| Variable | Default |
| --- | --- |
| `--c-dialog-background` | `var(--c-sys-color-surface-raised)` |
| `--c-dialog-overlay-background` | `var(--c-sys-color-scrim)` |
| `--c-dialog-border-color` | `var(--c-sys-color-border-default)` |
| `--c-dialog-border-width` | `1px` |
| `--c-dialog-border-radius` | `var(--c-sys-radius-md)` |
| `--c-dialog-width` | `520px` |
| `--c-dialog-margin-top` | `100px` |
| `--c-dialog-title-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-dialog-title-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-dialog-title-font-weight` | `var(--c-sys-font-weight-medium)` |
| `--c-dialog-title-padding` | `0 var(--c-sys-space-8)` |
| `--c-dialog-title-min-height` | `48px` |
| `--c-dialog-title-justify` | `center` |
| `--c-dialog-content-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-dialog-content-font-size` | `var(--c-sys-font-size-md)` |
| `--c-dialog-content-line-height` | `var(--c-line-height)` |
| `--c-dialog-content-padding` | `28px var(--c-sys-space-8)` |
| `--c-dialog-actions-padding` | `var(--c-sys-space-7) var(--c-sys-space-8)` |
| `--c-dialog-actions-button-gap` | `var(--c-sys-space-6)` |
| `--c-dialog-close-button-size` | `32px` |
| `--c-dialog-close-button-color` | `var(--c-sys-color-content-secondary)` |
| `--c-dialog-close-button-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-dialog-close-button-inset-inline-end` | `var(--c-sys-space-7)` |
| `--c-dialog-status-icon-size` | `18px` |
| `--c-dialog-status-icon-gap` | `var(--c-sys-space-5)` |
| `--c-dialog-status-info-color` | `var(--c-sys-color-content-info)` |
| `--c-dialog-status-success-color` | `var(--c-sys-color-content-success)` |
| `--c-dialog-status-warning-color` | `var(--c-sys-color-content-warning)` |
| `--c-dialog-status-danger-color` | `var(--c-sys-color-content-danger)` |
| `--c-dialog-simple-width` | `400px` |
| `--c-dialog-simple-border-radius` | `var(--c-sys-radius-md)` |
| `--c-dialog-simple-padding` | `28px 32px 32px` |
| `--c-dialog-simple-content-gap` | `28px` |
| `--c-dialog-simple-actions-gap` | `32px` |
| `--c-dialog-fullscreen-width` | `100vw` |
| `--c-dialog-fullscreen-height` | `100vh` |
| `--c-dialog-animation-duration` | `var(--c-sys-motion-duration-slow)` |
| `--c-dialog-animation-easing` | `var(--c-sys-motion-easing-standard)` |


Promise and done share a single completion state: false/done(false) rejects; true/done() allows; a resolved Promise&lt;void&gt; allows. The first completion wins. Errors emit guard-error; cancellation/unmount invalidates late completion. Synchronous void retains the callback protocol and waits for done on these close/confirm guards.


Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

## API

### `<Dialog>` Props

| Parameter | Description | Type | Default |
| ------------------------- | -------------------------------------------- | -------------------------------- | ------------ |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| `open` **(v-model)** | Visible state | `boolean` | `-` |
| `default-open` | Initial uncontrolled state | `boolean` | `false` |
| `title` | Title | `string` | `-` |
| `message` | Message content; the default slot is also supported | `string` | `-` |
| `message-align` | Message alignment | `'left' \| 'center' \| 'right'` | `'left'` |
| `type` | Status icon: `info`, `success`, `warning` or `error` | `string` | `-` |
| `simple` | Compact layout with a centered footer | `boolean` | `false` |
| `width` | Width | `number \| string` | `-` |
| `top` | Top offset; ignored when `align-center` is enabled | `number \| string` | `-` |
| `title-align` | Title alignment | `'start' \| 'center'` | `'center'` |
| `align-center` | Center vertically and horizontally | `boolean` | `true` |
| `overlay` | Show overlay | `boolean` | `true` |
| `overlay-class` | Overlay class | `string` | `-` |
| `overlay-style` | Overlay style | `CSSProperties` | `-` |
| `overlay-closable` | Request closure on an overlay click | `boolean` | `true` |
| `esc-to-close` | Request closure on Escape | `boolean` | `true` |
| `lock-scroll` | Lock background scrolling while open | `boolean` | `true` |
| `close-on-route-change` | Close on browser history or hash changes | `boolean` | `false` |
| `popup-container` | Teleport target; `false` disables teleport | `string \| HTMLElement \| false` | `'body'` |
| `confirm-button` | Show the confirm button | `boolean` | `true` |
| `cancel-button` | Show the cancel button | `boolean` | `true` |
| `closable` | Show close button | `boolean` | `true` |
| `confirm-button-text` | Confirm button text | `string` | `-` |
| `cancel-button-text` | Cancel button text | `string` | `-` |
| `confirm-button-loading` | Confirm button loading state | `boolean` | `false` |
| `cancel-button-loading` | Cancel button loading state | `boolean` | `false` |
| `confirm-button-disabled` | Disable the confirm button | `boolean` | `false` |
| `cancel-button-disabled` | Disable the cancel button | `boolean` | `false` |
| `confirm-button-props` | Confirm button props | `ButtonProps` | `-` |
| `cancel-button-props` | Cancel button props | `ButtonProps` | `-` |
| `footer` | Whether to show the footer | `boolean` | `true` |
| `dialog-class` | Dialog class | `string \| any[]` | `-` |
| `dialog-style` | Dialog style | `CSSProperties` | `-` |
| `body-class` | Body class | `string \| any[]` | `-` |
| `body-style` | Body style | `StyleValue` | `-` |
| `hide-title` | Hide the title | `boolean` | `false` |
| `unmount-on-close` | Unmount after closing | `boolean` | `false` |
| `draggable` | Allow dragging | `boolean` | `false` |
| `fullscreen` | Fullscreen layout | `boolean` | `false` |
| `overlay-animation-name` | Overlay animation name | `string` | `fade-modal` |
| `dialog-animation-name` | Dialog animation name | `string` | `zoom-modal` |
| `z-index` | Stack level | `number` | `-` |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | `DialogBeforeClose` | — |

### `<Dialog>` Events

| Event | Description | Arguments |
| ------------ | ------------- | --------------- |
| `open` | When opened | `-` |
| `opened` | Opening transition completes | `-` |
| `close` | Closing begins | `-` |
| `closed` | Closing transition completes | `-` |
| `confirm` | Accepted confirm action | `Event` |
| `cancel` | Accepted cancel or close action | `Event` |
| `click-overlay` | `MouseEvent` | `MouseEvent` |
| `key-escape` | ESC | `KeyboardEvent` |

The `close` button, overlay, ESC and `close()` use `close` semantics without an additional `cancel` event.

### `<Dialog>` Slots

| Slot | Description | Arguments |
| --------- | ---- | ---------------------------- |
| `default` | Content | `-` |
| `title` | Title | `-` |
| `footer` | Footer | `cancel`, `confirm`, `close` |

Confirm and cancel buttons use Button's `default` status and `text` variant unless `confirmButtonProps` or `cancelButtonProps` overrides them.

### Global methods

Function-based Dialog calls default to simple layout (`simple: true`) with the top-right close button hidden (`closable: false`). Explicit options or global defaults can override both.

#### DialogConfig

Accepts the component props in camelCase, plus:

| Parameter | Description | Type |
| ------------- | ---------------------------------- | -------------------------- |
| `content` | Renderable content; takes priority over `message` | `RenderContent` |
| `footer` | Whether to show a footer, or custom footer content | `boolean \| RenderContent` |
| `onConfirm` | Confirm callback | `(e?: Event) => void` |
| `onCancel` | Cancel callback | `(e?: Event) => void` |
| `onClickOverlay` | Overlay click callback | `() => void` |
| `onKeyEscape` | Escape callback | `() => void` |

#### DialogMethod

| Method | Description | Returns |
| ---------------------------------- | ------------------------------ | -------------------------------------- |
| `Dialog.open(config)` | Open a dialog | `Promise<DialogAction> & DialogReturn` |
| `Dialog.confirm(config)` | Confirmation dialog; defaults to `type: warning` | As above |
| `Dialog.alert(config)` | Alert dialog without a cancel button | As above |
| `Dialog.info(config)` | Information dialog | As above |
| `Dialog.success(config)` | Success dialog | As above |
| `Dialog.warning(config)` | Warning dialog | As above |
| `Dialog.error(config)` | Error dialog | As above |
| `Dialog.close()` | Close the latest functional dialog | `void` |
| `Dialog.setDefaultOptions(config)` | Set default programmatic options | `void` |
| `Dialog.resetDefaultOptions()` | Reset default programmatic options | `void` |

#### DialogReturn

| Prop | Description |
| ---------------- | -------- |
| `close()` | Close |
| `update(config)` | Update options |

After installation, call through `app.config.globalProperties.$dialog`.

### Type definitions

```ts
import type {
  DialogAction,
  DialogConfig,
  DialogMethod,
  DialogReturn,
  DialogService,
  DialogType,
} from "@cedar-design/ui";
```

### Style variables

Dialog public color variables have the same meanings as Maple: `--c-dialog-background` is the raised panel background (`surface-raised`); `--c-dialog-overlay-background` is the scrim; `--c-dialog-title-text-color` and `--c-dialog-content-text-color` are primary content; `--c-dialog-close-button-color` is the secondary action. `--c-dialog-status-{info|success|warning|danger}-color` uses readable content-info/success/warning/danger, not status fills. Business themes should override these component variables; shared themes should override the corresponding system variables. Borders, widths, spacing and layout retain desktop specifications.

#### Complete variable defaults

The backdrop consumes `sys-color-scrim` through the Dialog component variable. Maple no longer uses Popup colors for Dialog. Set a per-instance backdrop variable via `overlay-style`; a variable on the panel (`dialog-style`) does not inherit to its sibling backdrop. Explicit `overlay-style.backgroundColor` wins. Teleported content needs variables on its actual DOM ancestors. Dark themes inherit the same semantic colors; geometry remains platform-specific. Status icons use readable content colors.

Variables are grouped by purpose: background/overlay-background for panel/scrim; border-* for panel/divider borders; title-* for title typography; content-* for body typography; actions-* for actions; close-button-* for the close button; status-* for semantic icons; simple-*/fullscreen-* for mode dimensions; animation-* for enter/leave motion. width/margin-top control ordinary panel layout. Internal drag/position variables are not public customization points.

| Variable | Default |
| --- | --- |
| `--c-dialog-background` | `var(--c-sys-color-surface-raised)` |
| `--c-dialog-overlay-background` | `var(--c-sys-color-scrim)` |
| `--c-dialog-border-color` | `var(--c-sys-color-border-default)` |
| `--c-dialog-border-width` | `1px` |
| `--c-dialog-border-radius` | `var(--c-sys-radius-md)` |
| `--c-dialog-width` | `520px` |
| `--c-dialog-margin-top` | `100px` |
| `--c-dialog-title-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-dialog-title-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-dialog-title-font-weight` | `var(--c-sys-font-weight-medium)` |
| `--c-dialog-title-padding` | `0 var(--c-sys-space-8)` |
| `--c-dialog-title-min-height` | `48px` |
| `--c-dialog-title-justify` | `center` |
| `--c-dialog-content-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-dialog-content-font-size` | `var(--c-sys-font-size-md)` |
| `--c-dialog-content-line-height` | `var(--c-line-height)` |
| `--c-dialog-content-padding` | `28px var(--c-sys-space-8)` |
| `--c-dialog-actions-padding` | `var(--c-sys-space-7) var(--c-sys-space-8)` |
| `--c-dialog-actions-button-gap` | `var(--c-sys-space-6)` |
| `--c-dialog-close-button-size` | `32px` |
| `--c-dialog-close-button-color` | `var(--c-sys-color-content-secondary)` |
| `--c-dialog-close-button-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-dialog-close-button-inset-inline-end` | `var(--c-sys-space-7)` |
| `--c-dialog-status-icon-size` | `18px` |
| `--c-dialog-status-icon-gap` | `var(--c-sys-space-5)` |
| `--c-dialog-status-info-color` | `var(--c-sys-color-content-info)` |
| `--c-dialog-status-success-color` | `var(--c-sys-color-content-success)` |
| `--c-dialog-status-warning-color` | `var(--c-sys-color-content-warning)` |
| `--c-dialog-status-danger-color` | `var(--c-sys-color-content-danger)` |
| `--c-dialog-simple-width` | `400px` |
| `--c-dialog-simple-border-radius` | `var(--c-sys-radius-md)` |
| `--c-dialog-simple-padding` | `28px 32px 32px` |
| `--c-dialog-simple-content-gap` | `28px` |
| `--c-dialog-simple-actions-gap` | `32px` |
| `--c-dialog-fullscreen-width` | `100vw` |
| `--c-dialog-fullscreen-height` | `100vh` |
| `--c-dialog-animation-duration` | `var(--c-sys-motion-duration-slow)` |
| `--c-dialog-animation-easing` | `var(--c-sys-motion-easing-standard)` |

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading.

Service notification callbacks do not control task completion. The selected/closed result is settled independently of callback errors, and closing completion always releases the owned host. Callback errors still propagate through the calling/Vue error path; returned Promises do not control loading or closing.

---

Document: llms/en-US/components/divider.md

<!-- Source: src/divider/README.en-US.md; locale: en-US; page: /en/components/divider/ -->

# Divider

Separate content sections in lists and layouts.

## Basic examples

### Basic Usage

Separate adjacent content sections.

Example source: src/divider/__demos__/basic.vue

```vue
<template>
  <div>
    <p>内容上方 / Before</p>
    <c-divider />
    <p>内容下方 / After</p>
  </div>
</template>
```

## Layout and arrangement

### Vertical Divider

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `orientation` | Horizontal/vertical orientation of the divider itself, default horizontal; does not control text alignment | Vertical Divider |
| `type` | Line style | Vertical Divider |
| `text-align` | Text position along the line; start/end follow logical direction | Vertical Divider |
| `description` | Description text; the default slot takes priority | Vertical Divider |
<!-- demo-config-notes:end -->


Set `orientation="vertical"` in a flex container with available height. Text follows the vertical direction.

Example source: src/divider/__demos__/vertical.vue

```vue
<template>
  <div>
    <div class="vertical-row">
      <span>Before</span>
      <c-divider orientation="vertical" />
      <span>Middle</span>
      <c-divider orientation="vertical" type="dashed" />
      <span>After</span>
    </div>
    <div class="vertical-labels">
      <c-divider orientation="vertical" text-align="start" description="Start" />
      <c-divider orientation="vertical" description="Center" />
      <c-divider orientation="vertical" text-align="end" description="End" />
    </div>
  </div>
</template>

<style scoped>
.vertical-row {
  display: flex;
  align-items: center;
  min-height: 40px;
}
.vertical-labels {
  display: flex;
  height: 160px;
}
</style>
```

## Content and presentation

### Line size, style and color

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `inset` | Inset along the line: left/right horizontally, top/bottom vertically | Line size, style and color |
| `spacing` | Outer spacing across the line: top/bottom horizontally, left/right vertically | Line size, style and color |
| `orientation` | Horizontal/vertical orientation of the divider itself, default horizontal; does not control text alignment | Line size, style and color |
| `type` | Line style | Line size, style and color |
| `thickness` | Line width in px; theme defaults to 1px; hairline takes priority | Line size, style and color |
| `color` | Line color; defaults to the theme border color | Line size, style and color |
<!-- demo-config-notes:end -->


Compare thickness or insets, line style and color. Text and custom content remain separate.

<details>
<summary>Configuration details and limits</summary>

#### Spacing & Inset

Compare five presets, numbers, CSS lengths and asymmetric pairs. The vertical example shows how spacing follows orientation.

#### Line Style

Compare solid, dashed, dotted and double lines using `type`. Use a `thickness` of at least 3px for a visible double line.

#### Color, Thickness & Opacity

Customize the line using `color`, `thickness` and `opacity`. Zero opacity preserves layout; `hairline` takes priority over `thickness`.

</details>

Example source: src/divider/__demos__/line-appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const presets = ['xs', 'sm', 'md', 'lg', 'xl']
return { presets }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size-inset">
    <h4><span lang="zh-CN">间距与缩进</span><span lang="en-US">Spacing &amp; Inset</span></h4>
    <div>
        <div v-for="size in scene1.presets" :key="size">
          <code>inset="{{ size }}" spacing="{{ size }}"</code>
          <c-divider :inset="size" :spacing="size" />
        </div>
        <p>数值 / Number · inset=24, spacing=16</p>
        <c-divider :inset="24" :spacing="16" />
        <p>CSS 长度 / CSS length · inset=2rem</p>
        <c-divider inset="2rem" />
        <p>非对称 / Asymmetric · inset=[8, 32], spacing=[12, 24]</p>
        <c-divider :inset="[8, 32]" :spacing="[12, 24]" />
        <p>竖直 / Vertical · inset=[8, 24], spacing=[12, 20]</p>
        <div class="vertical-preview">
          <span>Before</span>
          <c-divider orientation="vertical" :inset="[8, 24]" :spacing="[12, 20]" />
          <span>After</span>
        </div>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="line-type">
    <h4><span lang="zh-CN">线型</span><span lang="en-US">Line Style</span></h4>
    <div>
        <p>实线 / solid</p>
        <c-divider />
        <p>虚线 / dashed</p>
        <c-divider type="dashed" />
        <p>点线 / dotted</p>
        <c-divider type="dotted" />
        <p>双线 / double · 3px</p>
        <c-divider type="double" :thickness="3" />
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="opacity-color">
    <h4><span lang="zh-CN">颜色、线宽与透明度</span><span lang="en-US">Color, Thickness &amp; Opacity</span></h4>
    <div>
        <p>主题色 / Theme color</p>
        <c-divider color="var(--c-sys-color-action-primary)" />
        <p>线宽 / Thickness · 3px</p>
        <c-divider :thickness="3" />
        <p>半透明 / Half opacity · 0.5</p>
        <c-divider :thickness="3" :opacity="0.5" />
        <p>隐藏线条，保留间距 / Zero opacity preserves spacing</p>
        <c-divider :opacity="0" />
        <p>细线优先 / Hairline overrides thickness</p>
        <c-divider hairline :thickness="4" />
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.vertical-preview {
  display: flex;
  align-items: center;
  height: 96px;
}

}
</style>
```

### With Text

Use `description` and `text-align` to position text at the start, center or end. Toggle RTL to inspect logical start/end alignment.

Example source: src/divider/__demos__/with-text.vue

```vue
<script setup>
import { ref } from 'vue'

const rtl = ref(false)
</script>

<template>
  <div>
    <c-checkbox v-model="rtl">RTL</c-checkbox>
    <div :dir="rtl ? 'rtl' : 'ltr'">
      <c-divider text-align="start" description="起点 / Start" />
      <c-divider description="居中 / Center" />
      <c-divider text-align="end" description="终点 / End" />
    </div>
  </div>
</template>
```

## Customization and slots

### Custom Content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `type` | Line style | Custom Content |
| `description` | Description text; the default slot takes priority | Custom Content |
<!-- demo-config-notes:end -->


The default slot takes priority over `description`. Provide padding for custom content in the caller.

Example source: src/divider/__demos__/custom.vue

```vue
<template>
  <c-divider type="dashed" description="默认插槽优先 / Slot takes priority">
    <span class="divider-label">★ 自定义内容 / Custom content</span>
  </c-divider>
</template>

<style scoped>
.divider-label {
  padding-inline: 8px;
}
</style>
```

## Interaction and control

### Live Properties

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `orientation` | Horizontal/vertical orientation of the divider itself, default horizontal; does not control text alignment | Live Properties |
| `opacity` | Opacity of the entire divider, including text, from 0 to 1; zero preserves layout | Live Properties |
| `hairline` | Scale the theme line width by half; 0.5px with the default theme | Live Properties |
| `thickness` | Line width in px; theme defaults to 1px; hairline takes priority | Live Properties |
| `inset` | Inset along the line: left/right horizontally, top/bottom vertically | Live Properties |
| `spacing` | Outer spacing across the line: top/bottom horizontally, left/right vertically | Live Properties |
<!-- demo-config-notes:end -->


Toggle orientation, default slot text, opacity and hairline to inspect updates and restoration.

Example source: src/divider/__demos__/live-properties.vue

```vue
<script setup>
import { ref } from 'vue'

const vertical = ref(false)
const text = ref(false)
const invisible = ref(false)
const hairline = ref(false)
</script>

<template>
  <section class="divider-live-demo">
    <div class="controls">
      <c-checkbox v-model="vertical">Vertical divider</c-checkbox>
      <c-checkbox v-model="text">Divider text</c-checkbox>
      <c-checkbox v-model="invisible">Zero opacity</c-checkbox>
      <c-checkbox v-model="hairline">Hairline divider</c-checkbox>
    </div>
    <p role="status">Orientation: {{ vertical ? 'vertical' : 'horizontal' }}; opacity: {{ invisible ? 0 : 1 }}</p>
    <div class="preview" :class="{ vertical }">
      <span>Before</span>
      <c-divider
        data-testid="live-divider"
        :orientation="vertical ? 'vertical' : 'horizontal'"
        :opacity="invisible ? 0 : 1"
        :hairline="hairline"
        :thickness="4"
        :inset="[8, 16]"
        :spacing="[12, 20]"
        ><template v-if="text" #default>Section</template></c-divider
      >
      <span>After</span>
    </div>
  </section>
</template>

<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
.controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
.preview {
  display: flex;
  flex-direction: column;
  min-height: 160px;
}
.preview.vertical {
  flex-direction: row;
  align-items: center;
}
</style>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"`. Horizontal text start/end follows reading order; vertical start/end remains top/bottom. Inset controls along-line indentation and spacing controls perpendicular margins. Paired horizontal inset and vertical spacing uses logical start/end. Vertical borders use inline start; hairline, border type and aria-orientation retain their meaning. Direction changes preserve content nodes.

### Content height and minimum thickness

Explicit thickness accepts finite numbers greater than or equal to 1. hairline still takes priority, using half the theme width. Values below 1 (including zero and negative values), and non-finite values, are ignored and use the theme width; development builds warn.

Multiline descriptions and custom content occupy their full height, including spacing=0. Subsequent content stays below the divider.

Example source: src/divider/__demos__/content-flow.vue

```vue
<template>
  <section class="divider-flow-demo">
    <h4>1px：最小显式线宽 / Minimum explicit width</h4>
    <div class="flow-sample">
      <c-divider
        data-min-line
        :thickness="1"
        :spacing="0"
        description="内容仍正常占位 / Content stays in normal flow"
      />
      <p>后续正文 / Following content</p>
    </div>
    <h4>4px：多行文字 / Multiline content</h4>
    <div class="flow-sample">
      <c-divider
        data-multiline
        :thickness="4"
        :spacing="0"
        description="分区标题支持换行，并为后续内容保留完整空间 / A wrapping section title reserves its full height"
      />
      <p>后续正文 / Following content</p>
    </div>
    <h4>默认插槽 / Custom content</h4>
    <div class="flow-sample">
      <c-divider data-custom-content :spacing="0"
        ><span class="flow-content"
          >第一行 / First line<br />第二行 / Second line</span
        ></c-divider
      >
      <p>后续正文 / Following content</p>
    </div>
    <p>
      thickness ≥ 1；hairline 优先，使用主题线宽的一半。hairline takes priority
      and halves the theme width.
    </p>
  </section>
</template>
<style scoped>
.flow-sample {
  max-width: 280px;
}
.flow-sample p {
  margin: 0;
}
.flow-content {
  padding: 12px 0;
}
</style>
```

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `orientation` | Horizontal/vertical orientation of the divider itself, default horizontal; does not control text alignment | `horizontal` \| `vertical` | `horizontal` |
| `type` | Line style | `solid` \| `dashed` \| `dotted` \| `double` | `solid` |
| `text-align` | Text position along the line; start/end follow logical direction | `start` \| `center` \| `end` | `center` |
| `description` | Description text; the default slot takes priority | `string` | — |
| `inset` | Inset along the line: left/right horizontally, top/bottom vertically | `DividerSize` | — |
| `spacing` | Outer spacing across the line: top/bottom horizontally, left/right vertically | `DividerSize` | `md` |
| `thickness` | Line width in px; theme defaults to 1px; hairline takes priority | `number` | — |
| `hairline` | Scale the theme line width by half; 0.5px with the default theme | `boolean` | `false` |
| `color` | Line color; defaults to the theme border color | `string` | — |
| `opacity` | Opacity of the entire divider, including text, from 0 to 1; zero preserves layout | `number` | — |

### Spacing values

`DividerSize = number | string | [number | string] | [number | string, number | string]`

`inset` controls the ends of the line; `spacing` controls the outer gap between the line and adjacent content. Both accept presets `xs`, `sm`, `md`, `lg`, `xl`, a number in px, a CSS length, or an array. A scalar or single-item array applies to both ends; `[start, end]` sets each end separately. Array entries are lengths, not preset names.

| Direction | inset array order | spacing array order |
| --- | --- | --- |
| horizontal | Inline start/end inset; right/left in RTL | Top/bottom margin |
| vertical | Top/bottom inset | Inline start/end margin; right/left in RTL |

`inset` has no `inset` by default; `spacing` defaults to the platform’s `md` `spacing`. Presets use platform theme tokens, so pixel values may differ.


Development builds diagnose invalid orientation, text-align, type, size structure, thickness and opacity. Invalid enums use their defaults; invalid inset is omitted, invalid spacing uses md, and invalid opacity is omitted. Opacity must be finite and within [0,1]. Size arrays contain one or two lengths, without preset names inside arrays. Finite negative margins and CSS var/calc expressions remain supported; the browser parses CSS expressions.

### Slots

| Slot | Description |
| --- | --- |
| `default` | Custom divider content; overrides description |

## Type definitions

```ts
import type { DividerProps, DividerInstance, DividerSize, DividerSizePreset, DividerOrientation, DividerTextAlign, DividerType } from '@cedar-design/ui'
```

### Style variables

| Variable | Default |
| --- | --- |
| `--c-divider-color` | `var(--c-sys-color-border-default)` |
| `--c-divider-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-divider-border-width` | `1px` |
| `--c-divider-text-padding` | `16px` |
| `--c-divider-text-align-inset` | `24px` |
| `--c-divider-orientation-vertical-inset-xs` | `2px` |
| `--c-divider-orientation-horizontal-inset-xs` | `12px` |
| `--c-divider-orientation-vertical-spacing-xs` | `4px` |
| `--c-divider-orientation-horizontal-spacing-xs` | `8px` |
| `--c-divider-orientation-vertical-inset-sm` | `4px` |
| `--c-divider-orientation-horizontal-inset-sm` | `16px` |
| `--c-divider-orientation-vertical-spacing-sm` | `8px` |
| `--c-divider-orientation-horizontal-spacing-sm` | `12px` |
| `--c-divider-orientation-vertical-inset-md` | `6px` |
| `--c-divider-orientation-horizontal-inset-md` | `24px` |
| `--c-divider-orientation-vertical-spacing-md` | `12px` |
| `--c-divider-orientation-horizontal-spacing-md` | `16px` |
| `--c-divider-orientation-vertical-inset-lg` | `8px` |
| `--c-divider-orientation-horizontal-inset-lg` | `32px` |
| `--c-divider-orientation-vertical-spacing-lg` | `16px` |
| `--c-divider-orientation-horizontal-spacing-lg` | `24px` |
| `--c-divider-orientation-vertical-inset-xl` | `12px` |
| `--c-divider-orientation-horizontal-inset-xl` | `40px` |
| `--c-divider-orientation-vertical-spacing-xl` | `24px` |
| `--c-divider-orientation-horizontal-spacing-xl` | `32px` |

Presets read the active platform theme. Text spacing is 16px on desktop and 8px on mobile.

---

Document: llms/en-US/components/drawer.md

<!-- Source: src/drawer/README.en-US.md; locale: en-US; page: /en/components/drawer/ -->

# Drawer

A side panel with declarative and programmatic APIs and cancellable before-close operations.

## Basic examples

### Basic

Example source: src/drawer/__demos__/basic.vue

```vue
<template>
  <c-button status="primary" @click="handleClick">Open Drawer</c-button>
  <c-drawer v-model:open="visible" :width="340" @confirm="handleConfirm" @cancel="handleCancel" unmount-on-close>
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
</script>
```

## Sizing and positioning

### Drawer size and placement

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `unmount-on-close` | Unmount content after the closing transition | Drawer size and placement |
| `placement` | Side of the containing area where the drawer appears, default right. It is not anchored to a button and does not perform popup collision flipping | Drawer size and placement |
| `popup-container` | Portal container | Popup Container |
<!-- demo-config-notes:end -->


Open each drawer separately to compare placement and occupied space. Nesting, containers and guards remain separate.

Example source: src/drawer/__demos__/position-size-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const visibleSmall = ref(false)

const visibleMedium = ref(false)

const visibleLarge = ref(false)


const handleClickSmall = () => {
  visibleSmall.value = true
}

const handleClickMedium = () => {
  visibleMedium.value = true
}

const handleClickLarge = () => {
  visibleLarge.value = true
}

const handleConfirm = () => {
  visibleSmall.value = false
  visibleMedium.value = false
  visibleLarge.value = false
}

const handleCancel = () => {
  visibleSmall.value = false
  visibleMedium.value = false
  visibleLarge.value = false
}
return { visibleSmall, visibleMedium, visibleLarge, handleClickSmall, handleClickMedium, handleClickLarge, handleConfirm, handleCancel }
})())

const scene2 = demoProxyRefs((() => {

const visible = ref(false)

const position = ref('right')


const handleClick = () => {
  visible.value = true
}

const handleConfirm = () => {
  visible.value = false
}

const handleCancel = () => {
  visible.value = false
}
return { visible, position, handleClick, handleConfirm, handleCancel }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">自定义宽度</span><span lang="en-US">Size</span></h4>
    <c-space>
        <c-button status="primary" @click="scene1.handleClickSmall">sm Drawer</c-button>
        <c-button status="primary" @click="scene1.handleClickMedium">md Drawer</c-button>
        <c-button status="primary" @click="scene1.handleClickLarge">lg Drawer</c-button>
      </c-space>
      <c-drawer v-model:open="scene1.visibleSmall" :width="280" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel" unmount-on-close>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
      <c-drawer v-model:open="scene1.visibleMedium" :width="420" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel" unmount-on-close>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
      <c-drawer v-model:open="scene1.visibleLarge" :width="640" @confirm="scene1.handleConfirm" @cancel="scene1.handleCancel" unmount-on-close>
        <template #title>Title</template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="location">
    <h4><span lang="zh-CN">抽屉位置</span><span lang="en-US">Location</span></h4>
    <c-radio-group v-model="scene2.position">
        <c-radio value="top">Top</c-radio>
        <c-radio value="right">Right</c-radio>
        <c-radio value="bottom">Bottom</c-radio>
        <c-radio value="left">Left</c-radio>
      </c-radio-group>
      <div :style="{
      marginTop: '20px'
    }">
        <c-button status="primary" @click="scene2.handleClick">Open Drawer</c-button>
      </div>
      <c-drawer
        :width="340"
        :height="340"
        v-model:open="scene2.visible"
        :placement="scene2.position"
        @confirm="scene2.handleConfirm"
        @cancel="scene2.handleCancel"
        unmountOnClose
      >
        <template #title> Title </template>
        <div>
          You can customize modal body text by the current situation. This modal will be closed immediately once you press
          the OK button.
        </div>
      </c-drawer>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Popup Container

Example source: src/drawer/__demos__/popup-container.vue

```vue
<template>
  <div>
    <div
      id="parentNode"
      style="
        width: 100%;
        height: 300px;
        background-color: var(--c-color-bg-white);
        position: relative;
        overflow: hidden;
        line-height: 300px;
        text-align: center;
      "
    >
      <c-button status="primary" @click="handleClick">Open Drawer</c-button>
    </div>
  </div>
  <c-drawer v-model:open="visible" popup-container="#parentNode" @confirm="handleConfirm" @cancel="handleCancel">
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
</script>
```

## Content and nesting

### Nest Drawer

Example source: src/drawer/__demos__/nest-drawer.vue

```vue
<template>
  <c-button status="primary" @click="handleClick">Open Drawer</c-button>
  <c-drawer v-model:open="visible" :width="500" @confirm="handleConfirm" @cancel="handleCancel" unmount-on-close>
    <template #title>Title</template>
    <div :style="{ marginBottom: '20px' }">
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
    <c-button status="primary" @click="handleNestedClick">Open Nested Drawer</c-button>
  </c-drawer>
  <c-drawer v-model:open="nestedVisible" @confirm="handleNestedConfirm" @cancel="handleNestedCancel" unmount-on-close>
    <template #title>Title</template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)
const nestedVisible = ref(false)

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
const handleNestedClick = () => {
  nestedVisible.value = true
}
const handleNestedConfirm = () => {
  nestedVisible.value = false
}
const handleNestedCancel = () => {
  nestedVisible.value = false
}
</script>
```

### Custom Node

Example source: src/drawer/__demos__/custom-node.vue

```vue
<template>
  <c-checkbox-group v-model="custom" :options="['hide header', 'hide footer', 'hide cancel']" />
  <div :style="{ marginTop: '20px' }">
    <c-button status="primary" @click="handleClick">Open Drawer</c-button>
  </div>
  <c-drawer
    :width="340"
    :header="!custom.includes('hide header')"
    :footer="!custom.includes('hide footer')"
    :cancel-button="!custom.includes('hide cancel')"
    v-model:open="visible"
    @confirm="handleConfirm"
    @cancel="handleCancel"
    unmountOnClose
  >
    <template #header>
      <span>Header and title</span>
    </template>
    <div>
      You can customize modal body text by the current situation. This modal will be closed immediately once you press
      the OK button.
    </div>
  </c-drawer>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const visible = ref(false)
const custom = ref([])

const handleClick = () => {
  visible.value = true
}
const handleConfirm = () => {
  visible.value = false
}
const handleCancel = () => {
  visible.value = false
}
</script>
```

### Function Call

Example source: src/drawer/__demos__/function-call.vue

```vue
<template>
  <c-button status="primary" @click="handleClick">Open Drawer</c-button>
</template>

<script lang="ts" setup>
import { Drawer } from '@cedar-design/ui'

const handleClick = () => {
  Drawer.open({
    title: 'Info Title',
    content: 'This is an info message',
    width: 340,
  })
}
</script>
```

### Api Review

## Closing and async control

### Guard Protocol

Example source: src/drawer/__demos__/en-US/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DrawerBeforeClose } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(true);
const status = ref("");
const check: DrawerBeforeClose = (payload, done, { signal }) => {
  status.value = `Waiting: ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-form-item layout="vertical" label="Allow closing"><c-switch v-model="allowed" aria-label="Allow closing" /></c-form-item>
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done callback' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">Open</c-button>
    <c-drawer
      v-model:open="open"
      :before-close="check"
      @guard-error="status = 'Error'"
    >
      <p>The guard waits briefly before closing. Turn off the switch to reject once, then enable it here and retry.</p>
      <c-form-item layout="vertical" label="Allow closing"><c-switch v-model="allowed" aria-label="Allow closing inside drawer" /></c-form-item>
      <c-button @click="allowed = true; open = false">Allow and close</c-button>
      <p role="status">{{ status }}</p>
    </c-drawer>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| open **(v-model)** | Controlled visibility | `boolean` | - |
| default-open | Initial uncontrolled visibility | `boolean` | `false` |
| placement | Side of the containing area where the drawer appears, default right. It is not anchored to a button and does not perform popup collision flipping | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` |
| title | Title | `string` | - |
| overlay | Show the overlay | `boolean` | `true` |
| overlay-class / overlay-style | Overlay class and style | `string / CSSProperties` | - |
| overlay-closable | Request closure on overlay click | `boolean` | `true` |
| closable | Show the close button | `boolean` | `true` |
| confirm-button-text / cancel-button-text | Action button text | `string` | - |
| confirm-button-loading / cancel-button-loading | Action button loading state | `boolean` | `false` |
| confirm-button-disabled / cancel-button-disabled | Action button disabled state | `boolean` | `false` |
| confirm-button-props / cancel-button-props | Action button props | `ButtonProps` | - |
| unmount-on-close | Unmount content after the closing transition | `boolean` | `false` |
| width / height | Width for left/right placement; height for top/bottom placement | `number \| string` | `250` |
| popup-container | Portal container | `string \| HTMLElement \| false` | `'body'` |
| drawer-class / drawer-style | Panel class and style | `string \| any[] / CSSProperties` | - |
| body-class / body-style | Body class and style | `string \| any[] / StyleValue` | - |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | `DrawerBeforeClose` | — |
| esc-to-close | Request closure on Escape | `boolean` | `true` |
| lock-scroll | Lock scrolling on the host | `boolean` | `true` |
| close-on-route-change | Request closure on route changes | `boolean` | `false` |
| z-index | Custom z-index | `number` | Automatically allocated |
| header / footer / cancel-button | Show the corresponding region | `boolean` | `true` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:open | Request a visibility update | `boolean` |
| confirm / cancel | Accepted confirm or cancel action | `Event` |
| open / close | Opening or closing begins | - |
| opened / closed | Opening or closing transition completes | - |
| click-overlay | Click the topmost overlay | `MouseEvent` |
| key-escape | Escape reaches the topmost drawer | `KeyboardEvent` |

### CSS

| Variable | Default |
| --- | --- |
| `--c-drawer-header-height` | `var(--c-size-12)` |
| `--c-drawer-footer-button-margin-left` | `var(--c-spacing-6)` |
| `--c-drawer-header-font-size` | `var(--c-font-size-title-1)` |
| `--c-drawer-padding-horizontal` | `var(--c-spacing-7)` |
| `--c-drawer-footer-padding-vertical` | `var(--c-spacing-7)` |
| `--c-drawer-content-padding-vertical` | `var(--c-spacing-6)` |
| `--c-drawer-header-font-weight` | `var(--c-font-weight-500)` |
| `--c-drawer-border-color` | `var(--c-sys-color-border-default)` |
| `--c-drawer-border-width` | `var(--c-border-width-1)` |
| `--c-drawer-header-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-drawer-content-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-drawer-bg` | `var(--c-sys-color-surface-raised)` |
| `--c-drawer-overlay-bg` | `var(--c-sys-color-scrim)` |
| `--c-drawer-line-height` | `var(--c-line-height)` |
| `--c-drawer-z-index` | `var(--c-z-index-drawer)` |
| `--c-drawer-close-icon-font-size` | `var(--c-size-3)` |
| `--c-drawer-close-btn-margin-left` | `var(--c-spacing-4)` |
| `--c-drawer-transition-duration` | `var(--c-transition-duration-3)` |
| `--c-drawer-transition-timing-function` | `var(--c-transition-timing-function-standard)` |


Promise and done share a single completion state: false/done(false) rejects; true/done() allows; a resolved Promise&lt;void&gt; allows. The first completion wins. Errors emit guard-error; cancellation/unmount invalidates late completion. Synchronous void retains the callback protocol and waits for done on these close/confirm guards.


Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Drawer placement=left/right remains physical, including entry and exit motion. Headings, content and footer actions inherit reading direction. Direction changes do not submit or clear content.

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| open **(v-model)** | Controlled visibility | `boolean` | - |
| default-open | Initial uncontrolled visibility | `boolean` | `false` |
| placement | Side of the containing area where the drawer appears, default right. It is not anchored to a button and does not perform popup collision flipping | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` |
| title | Title | `string` | - |
| overlay | Show the overlay | `boolean` | `true` |
| overlay-class / overlay-style | Overlay class and style | `string / CSSProperties` | - |
| overlay-closable | Request closure on overlay click | `boolean` | `true` |
| closable | Show the close button | `boolean` | `true` |
| confirm-button-text / cancel-button-text | Action button text | `string` | - |
| confirm-button-loading / cancel-button-loading | Action button loading state | `boolean` | `false` |
| confirm-button-disabled / cancel-button-disabled | Action button disabled state | `boolean` | `false` |
| confirm-button-props / cancel-button-props | Action button props | `ButtonProps` | - |
| unmount-on-close | Unmount content after the closing transition | `boolean` | `false` |
| width / height | Width for left/right placement; height for top/bottom placement | `number \| string` | `250` |
| popup-container | Portal container | `string \| HTMLElement \| false` | `'body'` |
| drawer-class / drawer-style | Panel class and style | `string \| any[] / CSSProperties` | - |
| body-class / body-style | Body class and style | `string \| any[] / StyleValue` | - |
| `before-close` | Return a boolean/Promise or call done; the first completion wins | `DrawerBeforeClose` | — |
| esc-to-close | Request closure on Escape | `boolean` | `true` |
| lock-scroll | Lock scrolling on the host | `boolean` | `true` |
| close-on-route-change | Request closure on route changes | `boolean` | `false` |
| z-index | Custom z-index | `number` | Automatically distributed |
| header / footer / cancel-button | Show the corresponding region | `boolean` | `true` |


### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:open | Request a visibility update | `boolean` |
| confirm / cancel | Accepted confirm or cancel action | `Event` |
| open / close | Opening or closing begins | - |
| opened / closed | Opening or closing transition completes | - |
| click-overlay | Click the topmost overlay | `MouseEvent` |
| key-escape | Escape reaches the topmost drawer | `KeyboardEvent` |

### Slots

`default`, `header`, `title`, `footer`. The `footer` slot receives `confirm`, `cancel` and `close` methods.

### Imperative calls

`Drawer.open(config)` uses camelCase options such as `cancelButtonText`, `beforeClose` and `closeOnRouteChange`. Notifications use `onConfirm`, `onCancel`, `onOpen`, `onOpened`, `onClose`, `onClosed`, `onClickOverlay` and `onKeyEscape`.

```ts
import type { DrawerAction, DrawerConfig, DrawerProps } from '@cedar-design/ui'
```

## CSS variables and color semantics

Built-in fade and four-direction slide disable transitions and initial displacement under prefers-reduced-motion: reduce. Component styles handle this without global fallbacks. Default durations remain unchanged; business-defined animations require separate handling. Compiled-CSS checks do not substitute for testing live OS preference changes.

Panel bg uses surface-raised; overlay-bg uses sys-color-scrim; header-text-color/content-text-color use content-primary, with the close button inheriting header-text-color; border-color uses border-default. Drawer keeps its existing geometry, motion and stacking defaults. Drawer is a Cedar component; Maple does not define empty same-name variables.

overlay-style sets instance scrim variables; drawer-style sets panel variables. These sibling nodes do not inherit variables from one another. Set global system theme variables on a real common ancestor. Explicit background props take precedence over variable consumption. The unused close-icon-right variable is removed; title layout and close-btn-margin-left position the close button, without an ineffective compatibility alias.

| Variable | Default |
| --- | --- |
| `--c-drawer-header-height` | `var(--c-size-12)` |
| `--c-drawer-footer-button-margin-left` | `var(--c-spacing-6)` |
| `--c-drawer-header-font-size` | `var(--c-font-size-title-1)` |
| `--c-drawer-padding-horizontal` | `var(--c-spacing-7)` |
| `--c-drawer-footer-padding-vertical` | `var(--c-spacing-7)` |
| `--c-drawer-content-padding-vertical` | `var(--c-spacing-6)` |
| `--c-drawer-header-font-weight` | `var(--c-font-weight-500)` |
| `--c-drawer-border-color` | `var(--c-sys-color-border-default)` |
| `--c-drawer-border-width` | `var(--c-border-width-1)` |
| `--c-drawer-header-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-drawer-content-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-drawer-bg` | `var(--c-sys-color-surface-raised)` |
| `--c-drawer-overlay-bg` | `var(--c-sys-color-scrim)` |
| `--c-drawer-line-height` | `var(--c-line-height)` |
| `--c-drawer-z-index` | `var(--c-z-index-drawer)` |
| `--c-drawer-close-icon-font-size` | `var(--c-size-3)` |
| `--c-drawer-close-btn-margin-left` | `var(--c-spacing-4)` |
| `--c-drawer-transition-duration` | `var(--c-transition-duration-3)` |
| `--c-drawer-transition-timing-function` | `var(--c-transition-timing-function-standard)` |

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading.

---

Document: llms/en-US/components/ellipsis.md

<!-- Source: src/ellipsis/README.en-US.md; locale: en-US; page: /en/components/ellipsis/ -->

# Ellipsis

Single-line or multi-line truncation with optional expansion and Tooltip.

## Basic examples

### Single line

Example source: src/ellipsis/__demos__/basic.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## Content and presentation

### Multiple lines

Example source: src/ellipsis/__demos__/multiline.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :line-clamp="2"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## Customization and slots

### Custom tooltip

Example source: src/ellipsis/__demos__/custom-tooltip.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :tooltip="{ status: 'primary', trigger: ['hover', 'focus', 'click'], content: '独立的提示内容，不会重复拼接正文' }"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## Interaction and control

### Interactive expansion

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `line-clamp` | Positive line count; omitted or invalid means single line | Interactive expansion, Controlled expansion |
| `expand-trigger` | Enable click / Enter / Space toggling | Interactive expansion, Controlled expansion |
| `tooltip` | Tooltip configuration; false disables it | Interactive expansion, Controlled expansion |
| `expand` | Controlled expansion | Controlled expansion |
<!-- demo-config-notes:end -->


Example source: src/ellipsis/__demos__/expand.vue

```vue
<template>
  <div class="ellipsis-demo">
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :line-clamp="2"
      expand-trigger="click"
      :tooltip="false"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
    <p>点击文本，或聚焦后按 Enter / Space 展开与收起。</p>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

### Controlled expansion

Example source: src/ellipsis/__demos__/controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const expanded = ref(false)
</script>

<template>
  <div class="ellipsis-demo">
    <c-button @click="expanded = !expanded">外部切换: {{ expanded }}</c-button>
    <c-ellipsis
      style="width: 240px; max-width: 100%"
      :line-clamp="2"
      expand-trigger="click"
      :tooltip="false"
      v-model:expand="expanded"
    >
      这是一段较长的说明文字，用于展示有限宽度内的省略效果。点击或使用键盘可以展开查看完整内容，再次操作可以收起。容器宽度改变时，文本会根据新的空间重新排版。
    </c-ellipsis>
  </div>
</template>

<style scoped>
.ellipsis-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.ellipsis-demo p { margin: 0; }
</style>
```

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `expand` | Controlled expansion | `boolean` | `undefined` |
| `default-expand` | Initial uncontrolled expansion | `boolean` | `false` |
| `expand-trigger` | Enable click / Enter / Space toggling | `'click'` | `—` |
| `line-clamp` | Positive line count; omitted or invalid means single line | `number \| string` | `—` |
| `tooltip` | Tooltip configuration; false disables it | `boolean \| TooltipProps` | `true` |

Providing `expand` makes the component request updates from its parent rather than changing controlled state. When omitted, internal state is used, initialized once by `default-expand`. Tooltip follows its own width and trigger defaults; display does not depend on measured overflow. Touch callers can include `click` in `tooltip.trigger` explicitly. External class/style/width apply directly to the text node.

### Events and slots

- `update:expand(expand: boolean)`: the new state requested by user interaction; external updates do not emit it.
- `default`: body text.
- `tooltip-content`: tooltip content. Without it, tooltip.content takes precedence, then body text; content is not concatenated twice.
- Keyboard: expandable text supports Enter / Space; tooltip-enabled text is focusable with Tab. No public instance methods.

### Types

```ts
import type { EllipsisProps, EllipsisInstance, EllipsisExpandTrigger } from '@cedar-design/ui'
```

### Style variables

| Token | Default |
| --- | --- |
| `--c-ellipsis-focus-color` | `var(--c-sys-color-content-brand)` |
| `--c-ellipsis-focus-width` | `2px` |
| `--c-ellipsis-focus-offset` | `2px` |

---

Document: llms/en-US/components/empty.md

<!-- Source: src/empty/README.en-US.md; locale: en-US; page: /en/components/empty/ -->

# Empty

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `description="暂无数据"`.

Example source: src/empty/__demos__/basic.vue

```vue
<template>
  <c-empty description="暂无数据" />
</template>
```

## Appearance and states

### Size

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `image-size` | Image/icon size | Size |
| `description` | Description; falls back to i18n | Size |
<!-- demo-config-notes:end -->


Preview configuration: `:image-size="size"`, `:description="image-size: ${size}"`.

Example source: src/empty/__demos__/size.vue

```vue
<template>
  <c-space direction="column">
    <c-empty v-for="size in sizes" :key="size" :image-size="size" :description="`image-size: ${size}`" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    const sizes = ['xs', 'sm', 'md', 'lg', 'xl']
    return { sizes }
  },
})
</script>
```

## Content and presentation

### Empty-state image and actions

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `description` | Description; falls back to i18n | Empty-state image and actions, Show |
| `image-url` | Custom image URL | Empty-state image and actions |
| `alt` | Image alternative text | Empty-state image and actions |
| `show-icon` | Whether to show the icon | Show |
| `show-description` | Whether to show the description | Show |
<!-- demo-config-notes:end -->


Compare custom artwork and extra actions to distinguish content replacement from supplemental controls.

Example source: src/empty/__demos__/content-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const attempts = ref(0)
return { attempts }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="extra">
    <h4><span lang="zh-CN">操作按钮</span><span lang="en-US">extra</span></h4>
    <c-empty :description="scene1.attempts ? 'No data. Local refresh completed.' : 'No data, please reload'">
        <template #extra>
          <c-button status="primary" @click="scene1.attempts++">Reload</c-button>
          <p aria-live="polite">Local refresh attempts: {{ scene1.attempts }}</p>
        </template>
      </c-empty>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="user-define">
    <h4><span lang="zh-CN">自定义图片和文案</span><span lang="en-US">user define</span></h4>
    <c-space direction="column">
        <c-empty>
          <template #image>
            <c-icon-exclamation-circle-fill />
          </template>
          No data, please reload!!
        </c-empty>
        <c-empty image-url="/cat.jpg" alt="空状态图片" description="自定义图片和文案" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Show

Preview configuration: `data-demo-empty`, `description="Dynamic empty state"`, `:show-icon="showIcon"`, `:show-description="showDescription"`.

Example source: src/empty/__demos__/show.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const showIcon = ref(true)
const showDescription = ref(true)
</script>

<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-button @click="showIcon = !showIcon">Toggle icon</c-button>
      <c-button @click="showDescription = !showDescription">Toggle description</c-button>
    </c-space>
    <c-empty data-demo-empty description="Dynamic empty state" :show-icon="showIcon" :show-description="showDescription" />
  </c-space>
</template>
```

## API

### `<Empty>` Props

| Prop | Description | Type | Default |
| ------------------ | ---------------------------- | -------------------------------------------------------- | ------- |
| description | Description; falls back to i18n | `string` | - |
| image-url | Custom image URL | `string` | - |
| alt | Image alternative text | `string` | `''` |
| image-size | Image/icon size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number \| string` | `'md'` |
| show-icon | Whether to show the icon | `boolean` | `true` |
| show-description | Whether to show the description | `boolean` | `true` |

### `<Empty>` Events

| Event | Description | Arguments |
| ------ | -------- | --------------------- |
| click | Click callback | `(ev: MouseEvent)` |

### `<Empty>` Slots

| Slot | Description | Arguments |
| ------- | --------- | ---- |
| image | Image/icon | - |
| default | Description content | - |
| extra | Extra actions | - |

### Type definitions

The component exports the following types

```ts
import type { EmptyImageSize, EmptyProps } from '@cedar-design/ui'
```

ConfigProvider's `empty` slot can replace Empty content when no custom content is supplied; it is not a public Empty prop.

### Style variables

| Variable | Default | Purpose |
| --- | --- | --- |
| `--c-empty-description-color` | `var(--c-sys-color-content-tertiary)` | Low-emphasis empty-state description |
| `--c-empty-icon-color` | `var(--c-sys-color-content-decorative)` | Decorative nontext icon; not for text users need to read |
| `--c-empty-padding` | `var(--c-spacing-5) 0` | Container spacing |
| `--c-empty-image-margin-bottom` | `var(--c-spacing-2)` | Icon-to-description gap |
| `--c-empty-description-font-size` | `var(--c-font-size-body-3)` | Description font size |
| `--c-empty-description-line-height` | `var(--c-line-height)` | Description line height |
| `--c-empty-extra-margin-top` | `var(--c-spacing-5)` | Gap above additional actions |
| `--c-empty-size-xs/sm/md/lg/xl` | `var(--c-size-15/20/25/35/45)` | Default icon/image size presets |

Descriptions are text and must meet text contrast requirements; decorative icons may be weaker. Custom images/slots may have their own colors and are not forcibly recolored by `icon-color`. Desktop/mobile maintain their own dimensions and spacing while keeping variable responsibilities consistent.

---

Document: llms/en-US/components/field-decorator.md

<!-- Source: src/field-decorator/README.en-US.md; locale: en-US; page: /en/components/field-decorator/ -->

# Field Decorator

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

Focused inputs do not draw an additional outer outline. Existing variant borders, underlines or backgrounds provide focus feedback. This applies to consumers including Input, Textarea, Date and Time.

Input, textarea and numeric-input carets use `currentColor`, matching the current input text. Error state does not override caret color separately.

`--c-field-caret-color` defaults to `currentColor` and controls Input, InputNumber and Textarea carets without changing text color.

## Basic examples

### Control Sizes

Preview configuration: `aria-label="Comparison size"`, `:value="item"`, `aria-label="Comparison variant"`, `:size="size"`.

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

## Loading and waiting

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

 Example source: src/field-decorator/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const busy = ref(true)
const mode = ref<'default' | 'line'>('line')
const text = ref('加载时仍可编辑')
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space><c-switch v-model="busy" />加载状态</c-space>
    <c-radio-group v-model="mode" :options="['default', 'line']" variant="button" aria-label="字段加载布局" />
    <c-form layout="vertical">
      <c-form-item label="文本"><c-input v-model="text" :loading="busy" :loading-mode="mode" /></c-form-item>
      <c-form-item label="多行文本"><c-textarea v-model="text" :loading="busy" :loading-mode="mode" /></c-form-item>
      <c-form-item label="选择"><c-select edit-mode="direct" :options="[{ label: '选项', value: 'a' }]" :loading="busy" :loading-mode="mode" /></c-form-item>
      <c-form-item label="日期"><c-date edit-mode="direct" :loading="busy" :loading-mode="mode" /></c-form-item>
    </c-form>
    <p>加载展示由同一个 FieldDecorator 实现，不隐式禁用输入；需要禁止操作时单独设置 disabled 或 readonly。</p>
  </c-space>
</template>
```

### Loading tokens

| Token | Default |
| --- | --- |
| `--c-field-loading-line-size` | `2px` |
| `--c-field-loading-duration` | `1s` |
| `--c-field-loading-color` | `var(--c-field-focus-color)` |

## Props

The outline notch uses `fieldset / legend`, not a background mask. It starts aligned with the content column and reserves `hint-space` on both sides. CSS `max()/calc()` in `padding-inline-start` must be emitted verbatim by Less, preventing different Less versions from prematurely evaluating it as `0px`. `check:input` checks source parity and both libraries’ Less output.

| Prop | Type | Default / meaning |
| --- | --- | --- |
| `tag` | `'div' \| 'span'` | `div`; wrapper element |
| `value` | `unknown` | Checks only whether content is empty |
| `id` | `string` | Native control id associated with the floating label |
| `title` | `string` | Native title tooltip |
| `size` | `ComponentSize` | `md`; implements all five sizes |
| `variant` | `'outline' \| 'filled' \| 'standard'` | `outline` |
| `placeholder` | `string` | Floating label text |
| `hint` | `boolean` | Cedar false / Maple true |
| `hint-center` | `boolean` | `true`; use false for multiline controls |
| `line` | `boolean` | `true`; whether to show a border or underline |
| `focused` | `boolean` | Consumer-supplied focus state |
| `composing` | `boolean` | Keep the label floated during IME composition |
| `disabled` / `readonly` / `error` | `boolean` | Provided by the consumer after merging Form / Group state |
| `clearable` | `boolean` | `false`; whether clearing is allowed |
| `text-color` / `focus-color` / `blur-color` | `string` | Custom text, focused and unfocused colors |
| `cursor` | `string` | Custom caret |

## Slots and events

`default` contains a native input, tags or display content. `prefix` / `suffix` contain adornments. `clear-icon` receives `clear(event?)`; a custom button should call it. Clearing does not bubble to open the selection panel.

`clear(event)` asks the consumer to update the value; `mousedown(event)` lets the consumer manage focus. The wrapper does not mutate the model itself.

Style semantics use `--c-field-*` / `--mp-field-*`, declared in each library's `style/token.less`. Implementations are not shared across libraries. Consumers must not draw a second border.

## Error and disabled border variables

Prefix these suffixes with `--c-field-` / `--mp-field-`: `variant-outline-border-color-error` controls outline error borders; `variant-standard-line-color-error` controls standard error underlines; `variant-standard-line-color-disabled` controls standard disabled underlines and defaults to system border-subtle. Disabled overrides error, hover and focus. All three support local overrides. `field-error-color` still controls error text. Internal variables are not business API; unused legacy declarations are removed without aliases.

Changing `tag` rebinds size observation to the current root and content elements. KeepAlive deactivation releases observation and queued measurement; frames from an earlier activation cannot update the current layout.

---

Document: llms/en-US/components/filter-form.md

<!-- Source: src/filter-form/README.en-US.md; locale: en-US; page: /en/components/filter-form/ -->

# Filter Form

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `v-model:collapsed="collapsed"`, `:fields="fields"`, `:rules="rules"`.

Example source: src/filter-form/__demos__/basic.vue

```vue
<template>
  <c-filter-form
    v-model="filter"
    v-model:collapsed="collapsed"
    :fields="fields"
    :rules="rules"
  >
    <template #actions>
      <c-button variant="outline" :elevation="false" @click="reset">重置</c-button>
      <c-button status="primary" :elevation="false" @click="search">搜索</c-button>
    </template>
  </c-filter-form>
  <pre class="demo-filter-json">{{ filter }}</pre>
  <p role="status">{{ result }}</p>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import {
  Cascader,
  DateRange,
  Input,
  Select,
  type FilterFormField,
} from '@cedar-design/ui'

const collapsed = ref(true)
const result = ref('尚未搜索')
const filter = ref<Record<string, unknown>>({
  region: undefined,
  status: undefined,
  keyword: '',
  timeRange: undefined,
})

const options = {
  status: [
    { label: '待处理', value: 'pending' },
    { label: '进行中', value: 'doing' },
    { label: '已完成', value: 'done' },
  ],
  owner: [
    { label: '张三', value: 'zhang' },
    { label: '李四', value: 'li' },
  ],
}

const rules = {
  keyword: [{ maxLength: 50, message: '最多 50 个字符' }],
}

const fields: FilterFormField[] = [
  {
    component: Cascader,
    field: 'region',
    label: '地区',
    props: {
      clearable: true,
      placeholder: '请选择地区',
      pathMode: true,
      variant: 'outline',
      options: [
        {
          value: 'beijing',
          label: '北京',
          children: [
            { value: 'chaoyang', label: '朝阳' },
            { value: 'haidian', label: '海淀' },
          ],
        },
        {
          value: 'shanghai',
          label: '上海',
          children: [{ value: 'huangpu', label: '黄浦' }],
        },
      ],
    },
  },
  {
    component: Select,
    field: 'status',
    label: '状态',
    props: { variant: 'outline', clearable: true, placeholder: '全部', options: options.status },
  },
  {
    component: Select,
    field: 'owner',
    label: '负责人',
    props: { variant: 'outline', clearable: true, placeholder: '全部', options: options.owner },
  },
  {
    component: Input,
    field: 'keyword',
    label: '关键词',
    autoEmitChange: false,
    props: { variant: 'outline', clearable: true, placeholder: '回车或失焦触发' },
  },
  {
    component: DateRange,
    field: 'timeRange',
    label: '时间范围',
    gridItemProps: { span: 2 },
    props: { variant: 'outline', valueFormat: 'timestamp', clearable: true, showTime: true },
  },
]

function search() {
  result.value = `搜索条件：${JSON.stringify(filter.value)}`
}

function reset() {
  result.value = '已重置'
  filter.value = {
    region: undefined,
    status: undefined,
    keyword: '',
    timeRange: undefined,
  }
}
</script>

<style scoped>
.demo-filter-json {
  margin-top: 16px;
  padding: 12px 16px;
  border-radius: 4px;
  background: var(--c-sys-color-surface-muted);
  color: var(--c-sys-color-content-secondary);
  font-size: 12px;
  line-height: 1.5;
  white-space: pre-wrap;
  word-break: break-all;
}
</style>
```

## Content and presentation

### Registered Fields

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `fields` | Filter-item schema | Registered Fields |
| `field-map` | Optional field-component registry | Registered Fields |
| `collapsible` | Whether expanding/collapsing is enabled | Registered Fields |
<!-- demo-config-notes:end -->


Preview configuration: `:fields="fields"`, `:field-map="fieldMap"`, `:collapsible="false"`.

Example source: src/filter-form/__demos__/registered-fields.vue

```vue
<template>
  <c-filter-form v-model="filter" :fields="fields" :field-map="fieldMap" :collapsible="false" />
  <pre>{{ filter }}</pre>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { Input, Select, type FilterFormField, type FilterFormFieldMap } from '@cedar-design/ui'

const filter = ref<Record<string, unknown>>({ keyword: '', status: undefined })
const fieldMap: FilterFormFieldMap = {
  input: Input,
  select: { component: Select, defaultProps: { clearable: true, placeholder: '全部' } },
}
const fields: FilterFormField[] = [
  { field: 'keyword', label: '关键词', component: 'input', props: { clearable: true } },
  {
    field: 'status',
    label: '状态',
    component: 'select',
    props: { options: [{ label: '启用', value: 'enabled' }, { label: '停用', value: 'disabled' }] },
  },
]
</script>
```

## Async and dynamic data

### Async Options

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `fields` | Filter-item schema | Async Options |
| `collapsible` | Whether expanding/collapsing is enabled | Async Options |
<!-- demo-config-notes:end -->


Preview configuration: `:fields="fields"`, `:collapsed="false"`, `:collapsible="false"`.

Example source: src/filter-form/__demos__/async-options.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-alert>
      异步加载选项后，通过 computed 更新字段的 props.options。
    </c-alert>
    <c-filter-form
      v-model="filter"
      :fields="fields"
      :collapsed="false"
      :collapsible="false"
    >
      <template #actions>
        <c-space>
          <c-button @click="reset">重置</c-button>
          <c-button status="primary" @click="search">搜索</c-button>
        </c-space>
      </template>
    </c-filter-form>
  </c-space>
  <p role="status">{{ result }}</p>
</template>

<script lang="ts" setup>
import { computed, onMounted, onUnmounted, ref } from 'vue'
import {
  Input,
  Select,
  type FilterFormField,
} from '@cedar-design/ui'

const filter = ref<Record<string, unknown>>({
  category: undefined,
  tag: undefined,
  name: '',
})

const options = ref<Record<string, unknown>>({
  category: [],
  tag: [],
})

const fields = computed<FilterFormField[]>(() => [
  {
    component: Select,
    field: 'category',
    label: '分类',
    props: { clearable: true, placeholder: '请选择', options: options.value.category },
  },
  {
    component: Select,
    field: 'tag',
    label: '标签',
    props: { clearable: true, multiple: true, placeholder: '请选择', options: options.value.tag },
  },
  {
    component: Input,
    field: 'name',
    label: '名称',
    props: { clearable: true },
  },
])

let timer: ReturnType<typeof setTimeout>
onUnmounted(() => clearTimeout(timer))

onMounted(() => {
  timer = setTimeout(() => {
    options.value = {
      category: [
        { label: '组件', value: 'component' },
        { label: '工具', value: 'tool' },
      ],
      tag: [
        { label: '推荐', value: 'hot' },
        { label: '新品', value: 'new' },
      ],
    }
  }, 800)
})

const result = ref('尚未搜索')
function search() {
  result.value = `搜索条件：${JSON.stringify(filter.value)}`
}

function reset() {
  filter.value = {
    category: undefined,
    tag: undefined,
    name: '',
  }
}
</script>
```

## API

### Value and default value

Use ordinary `v-model`. `modelValue` is the filter-fields object. `defaultValue` initializes uncontrolled state once; later changes do not reset it. Explicit binding takes precedence, and initialization emits no `update:modelValue`.

### FilterForm Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| model-value **(v-model)** | Form value | `Record<string, unknown>` | `{}` |
| fields | Filter-item schema | `FilterFormField[]` | `[]` |
| field-map | Optional field-component registry | `FilterFormFieldMap` | `{}` |
| rules | Forwarded Form validation rules | object | - |
| collapsed **(v-model)** | Whether to collapse extra items | boolean | `true` |
| collapsible | Whether expanding/collapsing is enabled | boolean | `true` |
| cols | Responsive column count | number \| object | `{ xs:1, sm:2, md:3, lg:3, xl:4, xxl:5 }` |
| grid-props | Other Grid props | object | - |
| change-debounce | Change debounce interval in milliseconds | number | `500` |

### FilterFormField

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| component | Vue component or a key in `fieldMap` | `string \| Component` | - |
| field | Form field path | string | - |
| label | Label | string | - |
| visible | Whether to render | boolean | `true` |
| autoEmitChange | Whether input emits change while editing | boolean | `true` |
| props | Props forwarded to the field component | object | - |
| gridItemProps | GridItem props | object | - |
| formItemProps | FormItem props | object | - |

### FilterFormFieldRegistration

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| component | Field component | Component | - |
| defaultProps | Default props | object | - |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:model-value | v-model | `(value) => void` |
| update:collapsed | Collapsed state changes | `(collapsed) => void` |
| change | Debounced field-value changes | `(value, field) => void` |

### Slots

| Slot | Description |
| --- | --- |
| actions | Action area for search/reset, on the same row as the expand/collapse control |

### Methods

| Method | Description |
| --- | --- |
| formRef | Internal Form instance |

## Style variables

| Variable | Default |
| --- | --- |
| `--c-filter-form-border-radius` | `var(--c-border-radius-md)` |
| `--c-filter-form-background-color` | `var(--c-sys-color-surface-default)` |
| `--c-filter-form-padding` | `var(--c-sys-space-7)`（20px） |
| `--c-filter-form-border-color` | `var(--c-sys-color-border-subtle)` |
| `--c-filter-form-border-width` | `1px` |
| `--c-filter-form-action-offset` | `calc(1em * var(--c-form-line-height) + var(--c-form-vertical-label-margin-bottom))` |
| `--c-filter-form-item-margin-bottom` | `0px`; Grid controls row spacing |
| `--c-filter-form-actions-gap` | `var(--c-sys-space-5)`（12px） |
| `--c-filter-form-collapse-gap` | `4px` |
| `--c-filter-form-collapse-color` | `var(--c-color-text-2)` |
| `--c-filter-form-collapse-hover-color` | `var(--c-sys-color-content-brand)` |
| `--c-filter-form-focus-width` | `2px` |
| `--c-filter-form-focus-offset` | `3px` |

Consumption verified on 2026-10-16: real Less compilation and mounted DOM confirm these 13 variables feed the container, FormItem, action-area and collapse-button rules. The static style entry also imports Form styles. Multi-column action `padding-top` consumes action-offset; stacked single-column mode overrides it to `0`. Root derived aliases do not necessarily recompute after locally overriding Form dependencies; adjust alignment by overriding `--c-filter-form-action-offset` on the actual FilterForm root.

## Types

```ts
import type {
  FilterFormProps,
  FilterFormField,
  FilterFormFieldMap,
  FilterFormFieldRegistration,
} from '@cedar-design/ui'
```

Grid column spacing is controlled by `grid-props.colGap` in numeric px. There is no same-name CSS override, ensuring numerical Grid measurements match actual spacing.

Changing changeDebounce reschedules a pending snapshot with the new delay;0 publishes immediately. Enter cancels its pending duplicate. Model resets invalidate stale snapshots while an accepted matching update:modelValue echo retains its change notification. Deactivation/unmount cancel pending work; reactivation accepts new input.

---

Document: llms/en-US/components/form.md

<!-- Source: src/form/README.en-US.md; locale: en-US; page: /en/components/form/ -->

# Form

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Reading direction

Form and FormItem accept start/end/left/center/right for content-align and start/end/left/right for label-align. Content defaults to start and labels to end: default LTR placement stays the same while RTL follows reading order. Explicit left/right remain physical. Item overrides and explicit label-column styles retain precedence. Direction changes preserve values, validation and disabled/readonly state.

## Basic examples

### Basic usage

- `model`: Form data object

Example source: src/form/__demos__/basic.vue

```vue
<template>
  <c-form ref="refForm" :model="form" @submit="handleSubmit">
    <c-form-item field="name" label="Username" required>
      <c-select v-model="form.name">
        <c-optgroup label="Group-1">
          <c-option>Beijing</c-option>
          <c-option>Shanghai</c-option>
        </c-optgroup>
        <c-option>Guangzhou</c-option>
        <c-option disabled>Disabled</c-option>
      </c-select>
    </c-form-item>
    <c-form-item>
      <c-button html-type="submit">Submit</c-button>
    </c-form-item>
  </c-form>
  {{ form.name }}
</template>
<script setup lang="ts">
import { reactive, ref } from "vue";
import type { FormInstance } from "../index";

const refForm = ref<FormInstance>();
const form = reactive({ name: "", post: "", isRead: false });
const handleSubmit = (data: any) => refForm.value?.resetFields(data);
</script>
```

## Form appearance and layout

### Disabled

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration      | Purpose                                                                       | Related examples                           |
| ------------------ | ----------------------------------------------------------------------------- | ------------------------------------------ |
| `layout`           | The layout of the form, including horizontal, vertical, and multi-column      | Layout, Decoration, Label width strategies |
| `model`            | Form data object                                                              | Decoration, Label width strategies         |
| `disabled`         | Whether to disable the form                                                   | Disabled                                   |
| `label-align`      | Label alignment                                                               | Label width strategies                     |
| `auto-label-width` | Automatically measure label widths; only effective with `layout="horizontal"` | Label width strategies                     |
| `label-col-flex`   | Label-column flex; numbers are flex ratios, unit-bearing strings are widths   | Label width strategies                     |

<!-- demo-config-notes:end -->

- `disabled`: Whether to disable the form

Example source: src/form/__demos__/disabled.vue

```vue
<template>
  <c-form :style="{ width: '600px' }" disabled>
    <c-form-item field="name" label="Username">
      <c-input placeholder="please enter your username..." />
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### Layout

`edit-mode` describes editing behavior: `direct` always shows the control; `click` and `dblclick` activate the existing editor overlay near the field. `readPretty` is an independent boolean. FormItem and fields inherit the mode when omitted. The legacy field `presentation` prop has been removed; use `edit-mode` to configure editing behavior. Replace `presentation="inline"` with `edit-mode="direct"`; `layout="inline"` is unchanged.

Combine `layout`, `content-align` with `direct / click / dblclick` editing and the independent `readPretty` boolean to compare label, value and wrapped-text alignment. Notes can override the form layout, and values survive every switch. Click or double-click a value to edit in a popover; readPretty displays saved text.

Example source: src/form/__demos__/en-US/layout.vue

```vue
<script setup lang="ts">
import Comparison from "../layout.vue";
</script>

<template><Comparison english /></template>
```

### Decoration

- `model`: Form data object
- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/decoration.vue

```vue
<script setup lang="ts">
import { reactive } from 'vue'
const model = reactive({ name: '', notes: '' })
</script>

<template>
  <c-form :model="model" layout="vertical">
    <c-form-item field="name" label="公开名称" required show-colon tooltip="名称将展示在个人主页。" :label-attrs="{ for: 'decorated-name' }">
      <c-input id="decorated-name" v-model="model.name" placeholder="输入公开名称" />
    </c-form-item>
    <c-form-item field="notes" label="备注" label-component="div" :content-flex="false" content-class="decoration-grid">
      <c-input v-model="model.notes" placeholder="支持自定义内容布局" />
      <small>content-flex=false 后由业务自行布局。</small>
    </c-form-item>
  </c-form>
</template>

<style scoped>
.decoration-grid { display: grid; gap: 8px; }
</style>
```

### Extra

Preview configuration: `type="text"`, `placeholder="请输入"`.

Example source: src/form/__demos__/extra.vue

```vue
<template>
  <c-form>
    <c-form-item field="name" label="Username" required>
      <c-input type="text" placeholder="请输入" />
      <template #extra>
        <div>UserName</div>
      </template>
    </c-form-item>
    <c-form-item field="post" label="Postname" required>
      <c-input type="text" placeholder="请输入" />
      <template #extra>
        <div>PostName</div>
      </template>
      <template #help>
        <div>Custom valitae message</div>
      </template>
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    return {}
  },
})
</script>
```

### Label width strategies

Enter values, then switch between measured labels, responsive columns and fixed widths: all three strategies retain the same form model. Edit the longest label or hide the contact field to observe remeasurement. Below 576px, the responsive strategy stacks labels above controls; fixed widths use 6rem with an 8rem contact-field override.

Example source: src/form/__demos__/en-US/label-width-comparison.vue

```vue
<script setup lang="ts">
import Comparison from '../label-width-comparison.vue'
</script>
<template><Comparison english /></template>
```

## Fields and data model

### Nested Data

- `model`: Form data object

Example source: src/form/__demos__/nested-data.vue

```vue
<template>
  <c-form :model="form" :style="{ width: '600px' }">
    <c-form-item
      label="Username"
      :content-flex="false"
      :merge-props="false"
      extra="Show error message together"
    >
      <c-row :gutter="8">
        <c-col :span="12">
          <c-form-item
            field="together.firstname"
            validate-trigger="input"
            :rules="[{ required: true, message: 'firstname is required' }]"
            no-style
          >
            <c-input
              v-model="form.together.firstname"
              placeholder="please enter your firstname..."
            />
          </c-form-item>
        </c-col>
        <c-col :span="12">
          <c-form-item
            field="together.lastname"
            validate-trigger="input"
            :rules="[{ required: true, message: 'lastname is required' }]"
            no-style
          >
            <c-input
              v-model="form.together.lastname"
              placeholder="please enter your lastname..."
            />
          </c-form-item>
        </c-col>
      </c-row>
    </c-form-item>
    <c-form-item label="Username" :content-flex="false" :merge-props="false">
      <c-row :gutter="8">
        <c-col :span="12">
          <c-form-item
            field="separate.firstname"
            validate-trigger="input"
            extra="Show error message separate"
            :rules="[{ required: true, message: 'firstname is required' }]"
            hide-label
          >
            <c-input
              v-model="form.separate.firstname"
              placeholder="please enter your firstname..."
            />
          </c-form-item>
        </c-col>
        <c-col :span="12">
          <c-form-item
            field="separate.lastname"
            validate-trigger="input"
            :rules="[{ required: true, message: 'lastname is required' }]"
            hide-label
          >
            <c-input
              v-model="form.separate.lastname"
              placeholder="please enter your lastname..."
            />
          </c-form-item>
        </c-col>
      </c-row>
    </c-form-item>
    <c-form-item label="Posts" :content-flex="false" :merge-props="false">
      <c-space direction="column" align="stretch">
        <c-form-item field="posts.post1" label="Post1">
          <c-input
            v-model="form.posts.post1"
            placeholder="please enter your post..."
          />
        </c-form-item>
        <c-form-item field="posts.post2" label="Post2">
          <c-input
            v-model="form.posts.post2"
            placeholder="please enter your post..."
          />
        </c-form-item>
      </c-space>
    </c-form-item>
    <c-form-item field="isRead">
      <c-checkbox v-model="form.isRead"> I have read the manual </c-checkbox>
    </c-form-item>
  </c-form>
  {{ form }}
</template>
<script lang="ts">
import { reactive, ref, defineComponent } from "vue";
export default defineComponent({
  setup() {
    const form = reactive({
      together: {
        firstname: "",
        lastname: "",
      },
      separate: {
        firstname: "",
        lastname: "",
      },
      posts: {
        post1: "",
        post2: "",
      },
      isRead: false,
    });

    return {
      form,
    };
  },
});
</script>
```

### Field Components

- `model`: Form data object

Example source: src/form/__demos__/field-components.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  name: "表单输入示例",
  notes: "每个字段都继承上方的展示与触发方式",
  count: 3,
  code: "123456",
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="name" label="单行文本"
        ><c-input v-model="model.name"
      /></c-form-item>
      <c-form-item field="notes" label="多行文本"
        ><c-textarea v-model="model.notes"
      /></c-form-item>
      <c-form-item field="count" label="数量"
        ><c-input-number v-model="model.count" :min="0" :max="100"
      /></c-form-item>
      <c-form-item field="code" label="验证码"
        ><c-verification-code v-model="model.code" :length="6"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Choice

- `model`: Form data object

Example source: src/form/__demos__/field-choice.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const choices = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops" },
];
const model = ref({
  enabled: true,
  agreed: true,
  teams: ["dev", "design"],
  role: "dev",
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="enabled" label="启用"
        ><c-switch v-model="model.enabled"
      /></c-form-item>
      <c-form-item field="agreed" label="确认状态"
        ><c-checkbox v-model="model.agreed">已阅读说明</c-checkbox></c-form-item
      >
      <c-form-item field="teams" label="协作部门"
        ><c-checkbox-group v-model="model.teams" :options="choices"
      /></c-form-item>
      <c-form-item field="role" label="所属部门"
        ><c-radio-group v-model="model.role" :options="choices"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Selection

- `model`: Form data object

Example source: src/form/__demos__/field-selection.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref, watch } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const devices = [
  {
    isGroup: true,
    label: "常用设备",
    options: [
      { value: "laptop", label: "笔记本" },
      { value: "phone", label: "手机" },
      { value: "tablet", label: "平板" },
    ],
  },
  {
    isGroup: true,
    label: "其他设备",
    options: [
      { value: "desktop", label: "台式工作站" },
      { value: "watch", label: "智能手表（暂不可选）", disabled: true },
    ],
  },
];
const people = [
  { value: "lin", label: "林晓 · 研发" },
  { value: "chen", label: "陈晨 · 设计" },
  { value: "zhou", label: "周宁 · 运营" },
];
const suggestions = [
  {
    isGroup: true,
    label: "技术团队",
    options: [
      { value: "研发" },
      { value: "研发平台" },
      { value: "研发基础设施" },
    ],
  },
  {
    isGroup: true,
    label: "协作团队",
    options: [
      { value: "设计" },
      { value: "运营" },
      { value: "归档团队", disabled: true },
    ],
  },
];
const model = ref({
  device: "laptop",
  devices: ["laptop", "phone"],
  keyword: "研发",
  person: "lin",
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="device" label="单选设备"
        ><c-select v-model="model.device" :options="devices" filterable
      /></c-form-item>
      <c-form-item field="devices" label="多选设备"
        ><c-select
          v-model="model.devices"
          :options="devices"
          multiple
          filterable
          :limit="3"
      /></c-form-item>
      <c-form-item field="keyword" label="自动补全"
        ><c-auto-complete
          v-model="model.keyword"
          :options="suggestions"
          clearable
          placeholder="输入或选择团队"
      /></c-form-item>
      <c-form-item field="person" label="人员"
        ><c-people-select
          v-model="model.person"
          :label="people.find((item) => item.value === model.person)?.label"
          :options="people"
          clearable
          placeholder="搜索人员"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Tree

- `model`: Form data object

Example source: src/form/__demos__/field-tree.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const regions = [
  {
    label: "华东",
    value: "east",
    children: [
      { label: "上海", value: "shanghai" },
      {
        label: "浙江",
        value: "zhejiang",
        children: [
          { label: "杭州", value: "hangzhou" },
          { label: "宁波", value: "ningbo" },
        ],
      },
    ],
  },
  {
    label: "华北",
    value: "north",
    children: [
      { label: "北京", value: "beijing" },
      { label: "天津", value: "tianjin" },
    ],
  },
  { label: "华南（暂不可选）", value: "south", disabled: true },
];
const treeOptions = [
  {
    value: "east",
    label: "华东",
    children: [
      { value: "shanghai", label: "上海" },
      {
        value: "zhejiang",
        label: "浙江",
        children: [
          { value: "hangzhou", label: "杭州" },
          { value: "ningbo", label: "宁波" },
        ],
      },
    ],
  },
  {
    value: "north",
    label: "华北",
    children: [
      { value: "beijing", label: "北京" },
      { value: "tianjin", label: "天津", disabled: true },
    ],
  },
];
const model = ref({
  regions: ["shanghai", "hangzhou"],
  region: "shanghai",
  tree: "shanghai",
  trees: ["shanghai", "hangzhou"],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="region" label="地区"
        ><c-cascader v-model="model.region" :options="regions" filterable
      /></c-form-item>
      <c-form-item field="regions" label="多选地区"
        ><c-cascader
          v-model="model.regions"
          :options="regions"
          multiple
          filterable
          show-path-label
      /></c-form-item>
      <c-form-item field="tree" label="树选择"
        ><c-tree-select
          v-model="model.tree"
          :data="treeOptions"
          :filter-tree-node="
            (query, node) => String(node.label).includes(query)
          "
          filterable
      /></c-form-item>
      <c-form-item field="trees" label="多选树节点"
        ><c-tree-select
          v-model="model.trees"
          :data="treeOptions"
          multiple
          tree-checkable
          :filter-tree-node="
            (query, node) => String(node.label).includes(query)
          "
          filterable
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Date

- `model`: Form data object

Example source: src/form/__demos__/field-date.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  datetime: "2026-10-20 09:30:00",
  dateTimes: ["2026-10-20 09:30:00", "2026-10-22 18:00:00"],
  day: "2026-10-19",
  days: ["2026-10-19", "2026-10-22"],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="day" label="日期"
        ><c-date v-model="model.day" value-format="YYYY-MM-DD"
      /></c-form-item>
      <c-form-item field="days" label="日期范围"
        ><c-date-range v-model="model.days" value-format="YYYY-MM-DD"
      /></c-form-item>
      <c-form-item field="datetime" label="日期时间"
        ><c-date v-model="model.datetime" show-time
      /></c-form-item>
      <c-form-item field="dateTimes" label="日期时间范围"
        ><c-date-range v-model="model.dateTimes" show-time
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Time

- `model`: Form data object

Example source: src/form/__demos__/field-time.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  time: "09:30",
  times: ["09:30", "18:00"],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="time" label="时间"
        ><c-time v-model="model.time" format="HH:mm"
      /></c-form-item>
      <c-form-item field="times" label="时间范围"
        ><c-time-range v-model="model.times" format="HH:mm"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Rating

- `model`: Form data object

Example source: src/form/__demos__/field-rating.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  progress: 40,
  score: 4,
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="progress" label="进度"
        ><c-slider v-model="model.progress"
      /></c-form-item>
      <c-form-item field="score" label="评分"
        ><c-rate v-model="model.score"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Upload

- `model`: Form data object

Example source: src/form/__demos__/field-upload.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const model = ref({
  attachments: [],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="attachments" label="附件"
        ><c-upload v-model="model.attachments" :auto-upload="false"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

### Field Specialized

- `model`: Form data object

Example source: src/form/__demos__/field-specialized.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
import { ref } from "vue";
const editMode = ref("direct");
const presentations = ["direct", "click", "dblclick"].map((value) => ({
  value,
  label: value,
}));
const choices = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops" },
];
const model = ref({
  mention: "@设计 请确认",
  color: "#36b5ac",
  tags: ["Vue", "TypeScript"],
  transferred: [{ value: "dev", label: "研发" }],
});
</script>

<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="字段展示方式">
      <c-radio-group
        v-model="editMode"
        aria-label="字段展示方式"
        :options="presentations"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form :model="model" :edit-mode="editMode">
      <c-form-item field="mention" label="提及"
        ><c-mention v-model="model.mention" :options="['研发', '设计', '运营']"
      /></c-form-item>
      <c-form-item field="color" label="颜色"
        ><c-color v-model="model.color"
      /></c-form-item>
      <c-form-item field="tags" label="标签"
        ><c-input-tag v-model="model.tags"
      /></c-form-item>
      <c-form-item field="transferred" label="穿梭选择"
        ><c-transfer v-model="model.transferred" :data="choices"
      /></c-form-item>
    </c-form>
    <ModelOutput aria-label="当前模型">{{
      JSON.stringify(model, null, 2)
    }}</ModelOutput>
  </c-space>
</template>
```

## Validation and submission

### Validate

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                  | Related examples                     |
| ------------- | ------------------------------------------------------------------------ | ------------------------------------ |
| `model`       | Form data object                                                         | Validate, Cross Field, Clear Trigger |
| `layout`      | The layout of the form, including horizontal, vertical, and multi-column | Clear Trigger                        |

<!-- demo-config-notes:end -->

- `model`: Form data object

Example source: src/form/__demos__/validate.vue

```vue
<template>
  <c-form ref="formRef" :model="form" :style="{ width: '600px' }" @submit="handleSubmit">
    <c-form-item
      field="name"
      label="Username"
      :rules="[
        { required: true, message: 'name is required' },
        { minLength: 5, message: 'must be greater than 5 characters' },
      ]"
      :validate-trigger="['change', 'input']"
    >
      <c-input v-model="form.name" placeholder="please enter your username..." />
    </c-form-item>
    <c-form-item
      field="age"
      label="Age"
      :rules="[
        { required: true, message: 'age is required' },
        { type: 'number', max: 200, message: 'age is max than 200' },
      ]"
    >
      <c-input v-model="form.age" placeholder="please enter your age..." />
    </c-form-item>
    <c-form-item field="date" label="date" :rules="[{ required: true, message: 'age is required' }]">
      <c-date-picker v-model="form.date" placeholder="please enter date..." />
    </c-form-item>
    <c-form-item field="section" label="Section" :rules="[{ match: /section one/, message: 'must select one' }]">
      <c-select v-model="form.section" placeholder="Please select ..." clearable>
        <c-option value="section one">Section One</c-option>
        <c-option value="section two">Section Two</c-option>
        <c-option value="section three">Section Three</c-option>
      </c-select>
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent, reactive } from 'vue'
export default defineComponent({
  setup() {
    const handleSubmit = (data: any) => {
      console.log(data)
    }

    const form = reactive({
      size: 'md',
      name: '',
      age: undefined,
      section: '',
      province: 'haidian',
      options: [],
      date: '',
      time: '',
      radio: 'radio one',
      slider: 5,
      score: 5,
      switch: false,
      multiSelect: ['section one'],
      treeSelect: '',
    })
    const options = [
      {
        value: 'beijing',
        label: 'Beijing',
        children: [
          {
            value: 'chaoyang',
            label: 'ChaoYang',
            children: [
              {
                value: 'datunli',
                label: 'Datunli',
              },
            ],
          },
          {
            value: 'haidian',
            label: 'Haidian',
          },
          {
            value: 'dongcheng',
            label: 'Dongcheng',
          },
          {
            value: 'xicheng',
            label: 'XiCheng',
          },
        ],
      },
      {
        value: 'shanghai',
        label: 'Shanghai',
        children: [
          {
            value: 'shanghaishi',
            label: 'Shanghai',
            children: [
              {
                value: 'huangpu',
                label: 'Huangpu',
              },
            ],
          },
        ],
      },
    ]

    return {
      form,
      options,
      handleSubmit,
    }
  },
})
</script>
```

### Cross Field

- `model`: Form data object

Example source: src/form/__demos__/cross-field.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import {
  onBeforeUnmount,
  onDeactivated,
  reactive,
  ref,
  shallowRef,
  useId,
} from "vue";

const formRef = ref();
const id = useId();
const model = reactive({ source: "", confirmation: "" });
const result = ref("尚未提交");
const submissions = ref(0);
const snapshot = ref("");
const message = "两次代码须相同且不能为空";
const sourceRules = [{ required: true, message: "请输入源代码" }];
const paused = ref(false);
const pending = shallowRef([]);
let epoch = 0;
function complete() {
  const [resolve, ...rest] = pending.value;
  pending.value = rest;
  resolve?.();
}
function cleanup() {
  epoch++;
  const tasks = pending.value;
  pending.value = [];
  tasks.forEach((resolve) => resolve());
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
const confirmationRules = [
  {
    validator: async (value, callback) => {
      if (paused.value)
        await new Promise((resolve) => {
          pending.value = [...pending.value, resolve];
        });
      if (!value || value !== model.source) callback(message);
    },
  },
];
function submitted({ errors, values }) {
  submissions.value++;
  result.value = errors ? "未通过" : "通过";
  snapshot.value = JSON.stringify(values);
}
async function validateConfirmation() {
  const current = ++epoch;
  const errors = await formRef.value?.validateField("confirmation");
  if (current === epoch) result.value = errors ? "确认值未通过" : "确认值通过";
}
function reset() {
  cleanup();
  result.value = "已重置";
  snapshot.value = "";
}
</script>

<template>
  <section class="cross-field-form-demo">
    <p>
      仅使用本地合成代码。校验时确认值比较当前源代码；修改源代码不自动复验依赖字段。
    </p>
    <c-form ref="formRef" :model="model" @submit="submitted" @reset="reset">
      <c-form-item
        field="source"
        label="源代码"
        :label-attrs="{ for: id + '-source' }"
        :rules="sourceRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-source'" v-model="model.source" />
      </c-form-item>
      <c-form-item
        field="confirmation"
        label="确认代码"
        :label-attrs="{ for: id + '-confirmation' }"
        :rules="confirmationRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-confirmation'" v-model="model.confirmation" />
      </c-form-item>
      <c-space wrap>
        <c-button html-type="submit">提交代码</c-button>
        <c-button @click="validateConfirmation">只校验确认值</c-button>
        <c-button html-type="reset">重置代码</c-button>
      </c-space>
    </c-form>
    <p role="status">结果：{{ result }}；提交次数：{{ submissions }}</p>
    <c-button
      html-type="button"
      :aria-pressed="paused"
      @click="paused = !paused"
      >暂停跨字段校验</c-button
    >
    <c-button html-type="button" :disabled="!pending.length" @click="complete"
      >返回跨字段结果</c-button
    >
    <p class="cross-field-pending">等待：{{ pending.length }}</p>
    <ModelOutput>模型：{{ model }}</ModelOutput>
    <ModelOutput>上次提交值：{{ snapshot || "-" }}</ModelOutput>
  </section>
</template>
```

### Clear Trigger

- `model`: Form data object
- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/clear-trigger.vue

```vue
<script setup lang="ts">
import { reactive, ref } from 'vue'

const model = reactive({ keyword: 'Cedar' })
const formRef = ref()
</script>

<template>
  <c-form ref="formRef" :model="model" layout="vertical" style="max-width: 360px">
    <c-form-item field="keyword" label="关键词" :rules="[{ required: true, message: '请输入关键词' }]" validate-trigger="clear">
      <c-input v-model="model.keyword" clearable placeholder="清空后立即校验" />
    </c-form-item>
    <c-button @click="formRef?.resetFields()">重置</c-button>
  </c-form>
</template>
```

### Empty markers and required validation

The API uses -1 for no selection. Validate the initial value to see a required error, choose a department and validate successfully, then clear to -1 and validate again. Form provides recognition settings; the field defines clear output. Custom validators still receive the original value.

Example source: src/form/__demos__/en-US/empty-values-validation.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ department: -1 as number | null | undefined });
const form = ref();
const result = ref("Not validated");
const options = [
  { value: 1, label: "Engineering" },
  { value: 2, label: "Product" },
];
async function validate() {
  const errors = await form.value.validate();
  result.value = errors ? "Required error" : "Valid";
}
</script>
<template>
  <c-space direction="column">
    <p>
      Validate the initial -1, then select a department and validate again.
      Clearing restores -1.
    </p>
    <c-form
      ref="form"
      :model="model"
      layout="vertical"
      :empty-values="[null, undefined, -1]"
    >
      <c-form-item field="department" label="Department" required>
        <c-select
          v-model="model.department"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-button @click="validate">Validate</c-button>
    <p role="status">{{ result }}</p>
    <p>
      Current model: <output>{{ String(model.department) }}</output>
    </p>
  </c-space>
</template>
```

### Feedback

Preview configuration: `placeholder="please enter your username..."`.

Example source: src/form/__demos__/feedback.vue

```vue
<template>
  <c-form :style="{ width: '600px' }">
    <c-form-item field="name" label="Username" validate-status="success" feedback>
      <c-input placeholder="please enter your username..." />
    </c-form-item>
  </c-form>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

## Field presentation and interaction

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                                                                                                            | Related examples                                         |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `layout`          | The layout of the form, including horizontal, vertical, and multi-column                                                           | State Lab, Presentation Status, Platform Presentation    |
| `model`           | Form data object                                                                                                                   | Field Presentation, Platform Presentation, Scroll Assign |
| `disabled`        | Whether to disable the form                                                                                                        | State Lab                                                |
| `readonly`        | Whether form controls are readonly                                                                                                 | State Lab                                                |
| `scroll-to-error` | After failed validation, scroll to the first (start) or last (end) invalid field in document order; this is not viewport alignment | Scroll Assign                                            |

<!-- demo-config-notes:end -->

- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/state-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
import type { FormItemValidateStatus } from "@cedar-design/ui";
const status = ref<FormItemValidateStatus>("warning");
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-form layout="vertical" v-bind="__demoState">
      <c-form-item
        label="展示状态"
        feedback
        :validate-status="status"
        help="显式状态只控制外观，不改变实际校验结果。"
      >
        <c-input placeholder="切换上方状态" />
      </c-form-item>
    </c-form>
  </c-space>
</template>
<style scoped>
.status-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
</style>
```

### Field Presentation

- `model`: Form data object

Example source: src/form/__demos__/field-presentation.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import { computed, ref } from "vue";

const editMode = ref("direct");
const readPretty = ref(false);

const options = ref([
  { value: 1, label: "研发设备" },
  { value: 2, label: "设计设备" },
  { value: 3, label: "运营设备" },
]);
const form = ref({
  name: "默认可直接编辑",
  deviceIds: [2],
  note: "此项始终直接编辑",
  summary: "只读展示",
});
const status = ref("");

const modeOptions = ["direct", "click", "dblclick"].map((value) => ({
  label: value,
  value,
}));
const committed = computed(() => JSON.stringify(form.value));
const presentationHint = computed(() =>
  readPretty.value
    ? "只展示已保存的值；下方“单项覆盖 direct”通过 readPretty=false 保持可编辑。"
    : editMode.value === "direct"
      ? "直接编辑，即时更新下方模型；选择设备无需额外确认。"
      : "按展示方式进入编辑；确认才更新下方模型，取消不保存本次修改。",
);
</script>
<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="Form 展示方式">
      <c-radio-group
        aria-label="Form 展示方式"
        v-model="editMode"
        :options="modeOptions"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-space wrap>
      <c-checkbox v-model="readPretty">纯阅读 readPretty</c-checkbox>
    </c-space>
    <p>
      {{ presentationHint }}<br />设备 4 已停用，最多选择 3
      个设备；可切换本地搜索与模拟远程搜索。
    </p>
    <c-form
      :model="form"
      :edit-mode="editMode"
      :read-pretty="readPretty"
      @submit-success="status = '表单已提交'"
      @submit-failed="status = '请完成当前编辑或修正校验错误'"
    >
      <c-form-item
        field="name"
        label="名称"
        :rules="[{ required: true, message: '名称不能为空' }]"
      >
        <c-input v-model="form.name" placeholder="请输入名称" clearable />
      </c-form-item>
      <c-form-item
        field="deviceIds"
        label="设备"
        :rules="[{ type: 'array', required: true, message: '请选择设备' }]"
      >
        <c-select
          v-model="form.deviceIds"
          :options="options"
          multiple
          filterable
          :limit="3"
          placeholder="搜索设备"
        />
      </c-form-item>
      <c-form-item
        field="note"
        label="单项覆盖 direct"
        edit-mode="direct"
        :read-pretty="false"
      >
        <c-input v-model="form.note" />
      </c-form-item>
      <c-form-item field="summary" label="固定 readPretty" read-pretty>
        <c-input v-model="form.summary" />
      </c-form-item>
      <c-button html-type="submit">提交表单</c-button>
    </c-form>
    <ModelOutput role="status">当前模型：{{ committed }}</ModelOutput>
    <p v-if="status" role="status">{{ status }}</p>
  </c-space>
</template>
```

### Reading placeholders and inheritance

Initially in reading mode, Name inherits Form’s default “-”, Code uses the FormItem override, Nickname uses the field override, and Quantity remains 0. Changing Form text only affects inheriting fields. Toggling reading/editing does not rewrite the model. Precedence is Field > FormItem > Form; custom read slots win.

Example source: src/form/__demos__/en-US/empty-text.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const reading = ref(true);
const emptyText = ref("-");
const model = reactive({
  name: null as string | null,
  code: null as string | null,
  nickname: null as string | null,
  quantity: 0 as number | null | undefined,
});
</script>
<template>
  <c-space direction="column">
    <p>
      Initially, reading mode shows “-” for Name, overrides for Code and
      Nickname, and the valid number 0 for Quantity.
    </p>
    <c-space wrap>
      <c-button @click="reading = !reading">Toggle reading/editing</c-button>
      <c-button @click="emptyText = 'No data'">Use “No data”</c-button>
      <c-button @click="emptyText = '-'">Use default “-”</c-button>
    </c-space>
    <c-form
      :model="model"
      layout="vertical"
      :read-pretty="reading"
      :empty-text="emptyText"
    >
      <c-form-item field="name" label="Name: inherits Form"
        ><c-input v-model="model.name"
      /></c-form-item>
      <c-form-item
        field="code"
        label="Code: FormItem override"
        empty-text="Unassigned"
        ><c-input v-model="model.code"
      /></c-form-item>
      <c-form-item
        field="nickname"
        label="Nickname: field override"
        empty-text="Unassigned"
        ><c-input v-model="model.nickname" empty-text="Anonymous"
      /></c-form-item>
      <c-form-item field="quantity" label="Quantity"
        ><c-input-number v-model="model.quantity"
      /></c-form-item>
    </c-form>
    <p>
      Current model: <output>{{ JSON.stringify(model) }}</output>
    </p>
  </c-space>
</template>
```

### Presentation Status

- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/presentation-status.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { FormItemValidateStatus } from '@cedar-design/ui'
const status = ref<FormItemValidateStatus>('warning')
const statuses: FormItemValidateStatus[] = ['success', 'warning', 'error', 'validating']
</script>

<template>
  <div class="status-demo">
    <c-space wrap>
      <c-button v-for="item in statuses" :key="item" @click="status = item">{{ item }}</c-button>
    </c-space>
    <c-form layout="vertical">
      <c-form-item label="展示状态" feedback :validate-status="status" help="显式状态只控制外观，不改变实际校验结果。">
        <c-input placeholder="切换上方状态" />
      </c-form-item>
    </c-form>
  </div>
</template>

<style scoped>
.status-demo { display: flex; flex-direction: column; gap: 16px; }
</style>
```

### Platform Presentation

- `model`: Form data object
- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/platform-presentation.vue

```vue
<script setup>
import { computed, ref } from "vue";
const initialModel = () => ({
  title: "设备巡检",
  department: "design",
  date: undefined,
  time: undefined,
});
const model = ref(initialModel());
const departments = [
  { value: "dev", label: "研发部" },
  { value: "design", label: "设计部" },
  { value: "ops", label: "运营部" },
];
const committed = computed(() =>
  JSON.stringify({
    title: model.value.title,
    department: model.value.department,
    date: model.value.date ?? null,
    time: model.value.time ?? null,
  }),
);
function reset() {
  model.value = initialModel();
}
</script>
<template>
  <c-space direction="column" class="platform-presentation-demo">
    <p>桌面字段在当前位置展开面板；选择后观察已提交模型。</p>
    <c-form :model="model" layout="vertical">
      <c-form-item label="任务名称" field="title"
        ><c-input
          v-model="model.title"
          edit-mode="direct"
          placeholder="输入任务名称"
      /></c-form-item>
      <c-form-item label="负责部门" field="department"
        ><c-select
          v-model="model.department"
          :options="departments"
          edit-mode="direct"
          placeholder="选择部门"
      /></c-form-item>
      <c-form-item label="执行日期" field="date"
        ><c-date v-model="model.date" edit-mode="direct" placeholder="选择日期"
      /></c-form-item>
      <c-form-item label="执行时间" field="time"
        ><c-time v-model="model.time" edit-mode="direct" placeholder="选择时间"
      /></c-form-item>
    </c-form>
    <div class="platform-presentation-demo__model">
      <strong>已提交模型</strong
      ><output aria-label="已提交模型" role="status">{{ committed }}</output>
    </div>
    <c-button @click="reset">重置本例</c-button>
  </c-space>
</template>
<style scoped>
.platform-presentation-demo {
  width: 100%;
  min-width: 0;
}
.platform-presentation-demo__model {
  width: 100%;
  padding: 12px;
  border-radius: 8px;
  background: var(--c-color-fill-1);
  color: var(--c-color-text-1);
}
.platform-presentation-demo__model output {
  display: block;
  margin-top: 8px;
  overflow-wrap: anywhere;
  font-size: 12px;
}
</style>
```

### Field Panel Actions

Preview configuration: `default-value="2026-10-20 09:30:00"`, `show-time`, `:disable-confirm="false"`.

Example source: src/form/__demos__/field-panel-actions.vue

```vue
<template>
  <c-space direction="column" :size="16">
    <c-date-picker
      default-value="2026-10-20 09:30:00"
      show-time
      :disable-confirm="false"
    />
    <c-date-picker
      default-value="2026-10-20 09:30:00"
      show-time
      :disable-confirm="false"
    >
      <template #actions="{ selectNow, nowDisabled, confirm, disabled }">
        <c-button variant="text" :disabled="nowDisabled" @click="selectNow"
          >此刻</c-button
        >
        <c-button :disabled="disabled" @click="confirm">完成</c-button>
      </template>
    </c-date-picker>
  </c-space>
</template>
```

### Scroll Assign

- `model`: Form data object
- `scroll-to-error`: Scroll to the first (start) or last (end) invalid field; omitted disables scrolling

Example source: src/form/__demos__/scroll-assign.vue

```vue
<template>
  <c-space>
    <c-button @click="formRef && formRef.validate()">Submit</c-button>
    <c-button @click="formRef && formRef.resetFields()">Reset</c-button>
    <c-button @click="formRef && formRef.scrollToField('name19')">Scroll to the last field</c-button>
  </c-space>
  <c-form
    ref="formRef"
    style="width: 500px; height: 300px; margin-top: 20px; padding-right: 16px; overflow: auto"
    :model="form"
    scroll-to-error="start"
  >
    <template v-for="(fieldName, index) in fieldNames" :key="index">
      <c-form-item :field="fieldName" :label="'user' + index" :rules="[{ required: true, message: 'Name is required' }]">
        <c-input v-model="form[fieldName]" />
      </c-form-item>
    </template>
  </c-form>
</template>
<script lang="ts">
import { reactive, ref, defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const formRef = ref<FormInstance>()
    const fieldCount = 20
    const fieldNames = Array.from({ length: fieldCount }, (_, index) => `name${index}`)
    const form = reactive(
      Object.fromEntries(fieldNames.map((fieldName, index) => [fieldName, index === 7 ? '' : index.toString()])),
    )

    return {
      form,
      formRef,
      fieldCount,
      fieldNames,
    }
  },
})
</script>
```

## Dynamic and async fields

### Dynamic Form

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                            | Related examples                                |
| ------------- | ---------------------------------- | ----------------------------------------------- |
| `model`       | Form data object                   | Dynamic Form, Async Validate Form, Async Fields |
| `disabled`    | Whether to disable the form        | Presentation State, Async Race                  |
| `readonly`    | Whether form controls are readonly | Presentation State, Async Race                  |
| `rules`       | Form item validation rules         | Presentation State                              |

<!-- demo-config-notes:end -->

- `model`: Form data object

Example source: src/form/__demos__/dynamic-form.vue

```vue
<template>
  <c-form :model="form" :style="{ width: '600px' }">
    <c-form-item field="name" label="Username">
      <c-input v-model="form.name" placeholder="please enter your username..." />
    </c-form-item>
    <c-form-item
      v-for="(post, index) of form.posts"
      :field="`posts[${index}].value`"
      :label="`Post-${index}`"
      :key="index"
    >
      <c-input v-model="post.value" placeholder="please enter your post..." />
      <c-button @click="handleDelete(index)" :style="{ marginLeft: '10px' }">Delete</c-button>
    </c-form-item>
  </c-form>
  <div>
    <c-button @click="handleAdd">Add Post</c-button>
  </div>
  {{ form }}
</template>
<script lang="ts">
import { reactive, defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const form = reactive({
      name: '',
      posts: [{ value: '' }],
    })
    const handleAdd = () => {
      form.posts.push({
        value: '',
      })
    }
    const handleDelete = (index) => {
      form.posts.splice(index, 1)
    }

    return {
      form,
      handleAdd,
      handleDelete,
    }
  },
})
</script>
```

### Async Validate Form

- `model`: Form data object

Example source: src/form/__demos__/async-validate-form.vue

```vue
<template>
  <section class="async-form-demo" @submit.capture="beginSubmit">
    <p>本地模拟异步校验：用户名只能是 admin，延迟 600ms，不访问外部接口。</p>
    <c-form
      ref="formRef"
      :model="form"
      @submit="handleSubmit"
      @reset="handleReset"
    >
      <c-form-item
        field="name"
        label="用户名"
        :label-attrs="{ for: `${demoId}-name` }"
        :rules="rules"
        feedback
      >
        <c-input
          :id="`${demoId}-name`"
          v-model="form.name"
          placeholder="请输入 admin"
        />
      </c-form-item>
      <c-form-item
        field="post"
        label="岗位"
        :label-attrs="{ for: `${demoId}-post` }"
      >
        <c-input
          :id="`${demoId}-post`"
          v-model="form.post"
          placeholder="请输入岗位"
        />
      </c-form-item>
      <c-form-item field="isRead">
        <c-checkbox v-model="form.isRead">已阅读说明</c-checkbox>
      </c-form-item>
      <c-form-item>
        <c-space>
          <c-button html-type="submit" status="primary" :loading="submitting"
            >提交</c-button
          >
          <c-button html-type="reset">重置</c-button>
          <c-button @click="setStatus">模拟服务端错误</c-button>
        </c-space>
      </c-form-item>
    </c-form>
    <p role="status">提交结果：{{ result }}；活动校验：{{ pendingCount }}</p>
    <ModelOutput>{{ form }}</ModelOutput>
  </section>
</template>

<script setup lang="ts">
import ModelOutput from '../__demo-utils__/ModelOutput.vue'

import { onBeforeUnmount, onDeactivated, reactive, ref, useId } from "vue";
import type { FormInstance, FieldRule } from "@cedar-design/ui";

const formRef = ref<FormInstance>();
const demoId = useId();
const form = reactive({ name: "", post: "", isRead: false });
const result = ref("尚未提交");
const submitting = ref(false);
const pendingCount = ref(0);
const pending = new Map<ReturnType<typeof setTimeout>, () => void>();
let generation = 0;
let submittedGeneration = -1;
const rules: FieldRule[] = [
  {
    validator: (value, callback) =>
      new Promise<void>((resolve) => {
        const current = generation;
        const timer = setTimeout(() => {
          pending.delete(timer);
          pendingCount.value = pending.size;
          if (current === generation && value !== "admin")
            callback("用户名必须是 admin");
          resolve();
        }, 600);
        pending.set(timer, resolve);
        pendingCount.value = pending.size;
      }),
  },
];

function beginSubmit() {
  submittedGeneration = generation;
  submitting.value = true;
  result.value = "校验中";
}
function cancelPending() {
  generation++;
  pending.forEach((resolve, timer) => {
    clearTimeout(timer);
    resolve();
  });
  pending.clear();
  pendingCount.value = 0;
  submitting.value = false;
}
function handleSubmit({ errors }: { errors?: unknown }) {
  if (submittedGeneration !== generation) return;
  submitting.value = false;
  result.value = errors ? "未通过" : "通过";
}
function handleReset() {
  cancelPending();
  result.value = "已重置";
}
function setStatus() {
  formRef.value?.setFields({
    name: { status: "error", message: "模拟服务端用户名错误" },
    post: { status: "error", message: "模拟服务端岗位错误" },
  });
  result.value = "服务端错误已展示";
}
onBeforeUnmount(cancelPending);
onDeactivated(cancelPending);
</script>
```

### Async Fields

- `model`: Form data object

Example source: src/form/__demos__/async-fields.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import {
  onBeforeUnmount,
  onDeactivated,
  reactive,
  ref,
  shallowRef,
  useId,
} from "vue";
const formRef = ref();
const id = useId();
const model = reactive({ name: "", code: "" });
const pending = shallowRef([]);
const submissions = ref(0);
const submittedResult = ref("-");
function submitted({ errors }) {
  submissions.value++;
  submittedResult.value = errors ? "未通过" : "通过";
}
const result = ref("尚未校验");
let run = 0;
function request(field, value) {
  return new Promise((resolve) => {
    pending.value = [...pending.value, { field, value, resolve }];
  });
}
function rules(field) {
  return [
    {
      validator: async (value, callback) => {
        const answer = await request(field, value);
        if (answer !== true) callback(answer);
      },
    },
  ];
}
const nameRules = rules("name");
const codeRules = rules("code");
async function validate() {
  const current = ++run;
  result.value = "校验中";
  const errors = await formRef.value?.validate();
  if (current === run) result.value = errors ? "未通过" : "通过";
}
function complete(field, latest = false) {
  const tasks = pending.value.filter((item) => item.field === field);
  const task = latest ? tasks.at(-1) : tasks[0];
  if (!task) return;
  pending.value = pending.value.filter((item) => item !== task);
  task.resolve(
    task.value === (field === "name" ? "admin" : "1234")
      ? true
      : field === "name"
        ? "用户名必须是 admin"
        : "代码必须是 1234",
  );
}
function reset() {
  run++;
  formRef.value?.resetFields();
  result.value = "已重置";
}
function clear() {
  run++;
  formRef.value?.clearValidate();
  result.value = "已清空";
}
function serverError() {
  run++;
  formRef.value?.setFields({
    name: { status: "error", message: "模拟服务端拒绝" },
  });
  result.value = "服务端错误";
}
function cleanup() {
  run++;
  const tasks = pending.value;
  pending.value = [];
  tasks.forEach((task) => task.resolve(true));
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
</script>
<template>
  <section class="async-fields-form-demo">
    <p>
      两个独立本地 Promise 规则分别接受 admin 和
      1234；手动返回各字段，不访问网络。
    </p>
    <c-form ref="formRef" :model="model" @submit="submitted">
      <c-form-item
        field="name"
        label="用户名"
        :label-attrs="{ for: id + '-name' }"
        :rules="nameRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-name'" v-model="model.name" />
      </c-form-item>
      <c-form-item
        field="code"
        label="代码"
        :label-attrs="{ for: id + '-code' }"
        :rules="codeRules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="id + '-code'" v-model="model.code" />
      </c-form-item>
      <c-button html-type="submit">原生异步提交</c-button>
    </c-form>
    <c-button html-type="button" @click="clear">清空校验</c-button>
    <c-button html-type="button" @click="serverError">写入服务端错误</c-button>
    <p class="async-submit-status">
      原生提交：{{ submissions }}；结果：{{ submittedResult }}
    </p>
    <c-space wrap>
      <c-button @click="validate">校验两个字段</c-button>
      <c-button
        :disabled="!pending.some((item) => item.field === 'name')"
        @click="complete('name')"
        >返回用户名结果</c-button
      >
      <c-button
        :disabled="!pending.some((item) => item.field === 'code')"
        @click="complete('code')"
        >返回代码结果</c-button
      >
      <c-button
        :disabled="!pending.some((item) => item.field === 'name')"
        @click="complete('name', true)"
        >返回最新用户名结果</c-button
      >
      <c-button
        :disabled="!pending.some((item) => item.field === 'code')"
        @click="complete('code', true)"
        >返回最新代码结果</c-button
      >
      <c-button @click="reset">重置两个字段</c-button>
    </c-space>
    <p role="status">
      结果：{{ result }}；用户名等待：{{
        pending.filter((item) => item.field === "name").length
      }}；代码等待：{{ pending.filter((item) => item.field === "code").length }}
    </p>
    <ModelOutput>{{ model }}</ModelOutput>
  </section>
</template>
```

### Presentation State

- `model`: Form data object
- `disabled`: Whether to disable the form
- `readonly`: Whether form controls are readonly
- `rules`: Form item validation rules

Example source: src/form/__demos__/presentation-state.vue

```vue
<script setup>
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import { computed, onBeforeUnmount, ref, shallowRef } from "vue";

const form = ref();
const editMode = ref("dblclick");
const disabled = ref(false);
const readonly = ref(false);
const model = ref({ title: "原名称", note: "原备注", department: "dev" });

const choices = [
  { value: "dev", label: "研发" },
  { value: "design", label: "设计" },
];

const check = (predicate) => [
  {
    validator: (value, callback) => {
      const result = predicate(value);
      callback(result === true ? undefined : result);
    },
  },
];
const rules = { title: check((value) => Boolean(value) || "名称必填") };

const scenario = ref("success");
const scenarios = [
  { value: "success", label: "保存成功" },
  { value: "failure", label: "保存失败，保留草稿" },
  { value: "reset", label: "等待期间重置表单" },
  { value: "disabled", label: "等待期间设为禁用" },
  { value: "readonly", label: "等待期间设为只读" },
];
const pending = shallowRef();
const result = ref("尚未保存");
const current = computed(() => JSON.stringify(model.value));
function save(value, { signal }) {
  return new Promise((resolve, reject) => {
    const timer = { id: undefined };
    let settled = false;
    const task = {
      value,
      finish(error, aborted = false) {
        if (settled) return;
        settled = true;
        clearTimeout(timer.id);
        signal.removeEventListener("abort", abort);
        if (pending.value === task) pending.value = undefined;
        result.value = aborted
          ? "保存已取消，旧结果不会提交"
          : error
            ? "保存失败，保留草稿"
            : "保存成功";
        if (error) reject(new Error("模拟保存失败，请重试"));
        else resolve(aborted ? false : undefined);
      },
    };
    const abort = () => task.finish(false, true);
    if (signal.aborted) {
      abort();
      return;
    }
    signal.addEventListener("abort", abort, { once: true });
    pending.value = task;
    result.value = "模拟保存中（1.2 秒）";
    timer.id = setTimeout(() => {
      if (scenario.value === "reset") form.value.resetFields();
      else if (scenario.value === "disabled") disabled.value = true;
      else if (scenario.value === "readonly") readonly.value = true;
      else task.finish(scenario.value === "failure");
    }, 1200);
  });
}
onBeforeUnmount(() => pending.value?.finish(false, true));
</script>
<template>
  <c-space direction="column" align="stretch" :size="16">
    <c-form-item layout="vertical" size="sm" label="异步保存场景">
      <c-radio-group
        v-model="scenario"
        aria-label="异步保存场景"
        :options="scenarios"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-checkbox v-model="disabled">禁用状态示例</c-checkbox>
    <c-checkbox v-model="readonly">只读状态示例</c-checkbox>
    <p>
      编辑名称、备注或部门并保存，模拟等待 1.2
      秒。选择保存结果，或在等待时禁用、只读、重置，观察草稿是否提交。
    </p>
    <c-form
      ref="form"
      :model="model"
      :edit-mode="editMode"
      :disabled="disabled"
      :readonly="readonly"
      :rules="rules"
    >
      <c-form-item field="title" label="事务名称"
        ><c-input v-model="model.title" :before-commit="save"
      /></c-form-item>
      <c-form-item field="note" label="事务备注"
        ><c-textarea v-model="model.note" :before-commit="save"
      /></c-form-item>
      <c-form-item field="department" label="事务部门"
        ><c-select
          v-model="model.department"
          :options="choices"
          filterable
          :before-commit="save"
      /></c-form-item>
    </c-form>
    <c-space>
      <c-button @click="form.resetFields()">重置状态示例</c-button>
    </c-space>
    <p role="status" aria-label="事务保存状态">{{ result }}</p>
    <ModelOutput aria-label="事务当前模型">{{ current }}</ModelOutput>
  </c-space>
</template>
```

### Async Race

- `model`: Form data object
- `disabled`: Whether to disable the form
- `readonly`: Whether form controls are readonly

Example source: src/form/__demos__/async-race.vue

```vue
<template>
  <section class="async-race-form-demo">
    <p>本地异步规则只接受 admin；手动返回最早或最新结果，不访问网络。</p>
    <c-form
      ref="formRef"
      :model="model"
      :disabled="disabled"
      :readonly="readonly"
    >
      <c-form-item
        v-if="mounted"
        field="name"
        label="用户名"
        :label-attrs="{ for: demoId }"
        :rules="rules"
        :validate-trigger="[]"
        feedback
      >
        <c-input :id="demoId" v-model="model.name" placeholder="请输入 admin" />
      </c-form-item>
    </c-form>
    <div class="async-race-controls">
      <c-checkbox v-model="disabled"> Disable async form</c-checkbox>
      <c-checkbox v-model="readonly"> Readonly async form</c-checkbox>
      <c-checkbox v-model="mounted"> Mount async field</c-checkbox>
    </div>
    <c-space wrap>
      <c-button :disabled="!mounted" @click="validate">校验字段</c-button>
      <c-button :disabled="!mounted" @click="validateAll">校验整表</c-button>
      <c-button :disabled="!pending.length" @click="complete(false)"
        >返回最早结果</c-button
      >
      <c-button :disabled="!pending.length" @click="complete(true)"
        >返回最新结果</c-button
      >
      <c-button :disabled="!mounted" @click="serverError"
        >写入服务端错误</c-button
      >
      <c-button @click="clear">清空校验</c-button>
      <c-button @click="reset">重置</c-button>
    </c-space>
    <p role="status">校验结果：{{ result }}；等待结果：{{ pending.length }}</p>
    <p>本次校验值：{{ checkedValue || "空" }}</p>
    <ModelOutput>{{ model }}</ModelOutput>
  </section>
</template>
<script setup lang="ts">
import ModelOutput from "../__demo-utils__/ModelOutput.vue";

import {
  onBeforeUnmount,
  onDeactivated,
  reactive,
  ref,
  shallowRef,
  useId,
} from "vue";
import type { FormInstance, FieldRule } from "@cedar-design/ui";

interface Pending {
  value: unknown;
  resolve: (result: true | string) => void;
}
const demoId = useId();
const disabled = ref(false);
const readonly = ref(false);
const mounted = ref(true);
const formRef = ref<FormInstance>();
const model = reactive({ name: "" });
const pending = shallowRef<Pending[]>([]);
const result = ref("尚未校验");
const checkedValue = ref("");
let run = 0;

function request(value: unknown) {
  return new Promise<true | string>((resolve) => {
    pending.value = [...pending.value, { value, resolve }];
  });
}
const rules: FieldRule[] = [
  {
    validator: async (value, callback) => {
      const answer = await request(value);
      if (answer !== true) callback(answer);
    },
  },
];

function validate() {
  return validateScope(false);
}
function validateAll() {
  return validateScope(true);
}
async function validateScope(all: boolean) {
  const current = ++run;
  checkedValue.value = model.name;
  result.value = "校验中";
  const errors = await (all
    ? formRef.value?.validate()
    : formRef.value?.validateField("name"));
  if (current === run) result.value = errors ? "未通过" : "通过";
}
function complete(latest: boolean) {
  const task = latest ? pending.value.at(-1) : pending.value[0];
  if (!task) return;
  pending.value = pending.value.filter((item) => item !== task);
  task.resolve(task.value === "admin" ? true : "用户名必须是 admin");
}
function clear() {
  run++;
  formRef.value?.clearValidate();
  result.value = "已清空";
}
function serverError() {
  run++;
  formRef.value?.setFields({
    name: { status: "error", message: "模拟服务端拒绝" },
  });
  result.value = "服务端错误";
}
function reset() {
  run++;
  formRef.value?.resetFields();
  checkedValue.value = "";
  result.value = "已重置";
}
function cleanup() {
  run++;
  result.value = "已取消";
  const tasks = pending.value;
  pending.value = [];
  tasks.forEach((task) => task.resolve(true));
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
</script>

<style scoped>
.async-race-controls {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
.async-race-controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
</style>
```

### Field Range Boundaries

- `model`: Form data object

Example source: src/form/__demos__/field-range-boundaries.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import ModelOutput from "../__demo-utils__/ModelOutput.vue";
const model = ref<{
  days: [string, string];
  months: [string, string];
  years: [string, string];
}>({
  days: ["2026-12-29", "2027-01-03"],
  months: ["2026-11", "2027-02"],
  years: ["2098", "2102"],
});
const disabledDay = (date: Date) =>
  date.getFullYear() === 2027 && date.getMonth() === 0 && date.getDate() === 1;
const disabledMonth = (date: Date) =>
  date.getFullYear() === 2026 && date.getMonth() === 11;
const disabledYear = (date: Date) => date.getFullYear() === 2100;
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form :model="model">
      <c-form-item field="days" label="跨月日期"
        ><c-date-range
          v-model="model.days"
          value-format="YYYY-MM-DD"
          :disabled-date="disabledDay"
      /></c-form-item>
      <c-form-item field="months" label="跨年月份"
        ><c-date-range
          v-model="model.months"
          type="month"
          value-format="YYYY-MM"
          :disabled-date="disabledMonth"
      /></c-form-item>
      <c-form-item field="years" label="跨页年份"
        ><c-date-range
          v-model="model.years"
          type="year"
          value-format="YYYY"
          :disabled-date="disabledYear"
      /></c-form-item>
    </c-form>
    <ModelOutput>{{ JSON.stringify(model, null, 2) }}</ModelOutput>
  </c-space>
</template>
```

## Business workflows

### Task Workflow

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                  | Related examples |
| ------------- | ------------------------------------------------------------------------ | ---------------- |
| `model`       | Form data object                                                         | Task Workflow    |
| `layout`      | The layout of the form, including horizontal, vertical, and multi-column | Task Workflow    |

<!-- demo-config-notes:end -->

- `model`: Form data object
- `layout`: The layout of the form, including horizontal, vertical, and multi-column

Example source: src/form/__demos__/task-workflow.vue

```vue
<script setup>
import { computed, onBeforeUnmount, onDeactivated, ref } from "vue";
const fresh = () => ({ title: "", department: "ops", priority: "normal" });
const draft = ref(fresh());
const saved = ref(null);
const stage = ref("edit");
const message = ref("填写任务后进入确认；也可以直接提交空表单查看校验。");
const busy = ref(false);
const failNext = ref(false);
const formRef = ref();
const rules = [{ required: true, whitespace: true, message: "请输入任务名称" }];
const departments = [
  { value: "ops", label: "运营部" },
  { value: "dev", label: "研发部" },
  { value: "design", label: "设计部" },
];
const priorities = [
  { value: "normal", label: "普通" },
  { value: "urgent", label: "紧急" },
];
const departmentLabel = computed(
  () =>
    departments.find((item) => item.value === draft.value.department)?.label,
);
let timer;
let epoch = 0;
function cancelPending() {
  epoch++;
  clearTimeout(timer);
  busy.value = false;
}
onBeforeUnmount(cancelPending);
onDeactivated(cancelPending);
function review({ errors }) {
  if (errors) {
    message.value = "请补全必填项，任务尚未提交。";
    return;
  }
  stage.value = "review";
  message.value = "核对信息后确认提交；返回修改不会改变上次提交记录。";
}
function submit() {
  if (busy.value) return;
  const current = ++epoch;
  const snapshot = { ...draft.value };
  const shouldFail = failNext.value;
  failNext.value = false;
  busy.value = true;
  message.value = "正在本地模拟保存…";
  timer = setTimeout(() => {
    if (current !== epoch) return;
    busy.value = false;
    if (shouldFail) {
      message.value = "保存失败：草稿已保留，请点击“重试提交”。";
      return;
    }
    saved.value = snapshot;
    stage.value = "done";
    message.value = "提交成功，已生成任务记录。";
  }, 500);
}
function reset() {
  cancelPending();
  draft.value = fresh();
  saved.value = null;
  stage.value = "edit";
  failNext.value = false;
  message.value = "已重置，可以重新演示。";
  formRef.value?.clearValidate();
}
function fill() {
  draft.value = {
    title: "展厅设备巡检",
    department: "ops",
    priority: "urgent",
  };
  formRef.value?.clearValidate();
}
</script>
<template>
  <section class="workflow-demo" aria-label="巡检任务完整流程">
    <ol class="workflow-demo__steps" aria-label="任务流程">
      <li :aria-current="stage === 'edit' ? 'step' : undefined">
        01 填写与校验
      </li>
      <li :aria-current="stage === 'review' ? 'step' : undefined">
        02 核对与提交
      </li>
      <li :aria-current="stage === 'done' ? 'step' : undefined">
        03 结果与记录
      </li>
    </ol>
    <c-form
      v-if="stage === 'edit'"
      ref="formRef"
      :model="draft"
      layout="vertical"
      @submit="review"
    >
      <c-form-item label="任务名称" field="title" :rules="rules" feedback
        ><c-input
          v-model="draft.title"
          edit-mode="direct"
          placeholder="例如：展厅设备巡检"
      /></c-form-item>
      <c-form-item label="执行部门" field="department"
        ><c-select
          v-model="draft.department"
          :options="departments"
          edit-mode="direct"
      /></c-form-item>
      <c-form-item label="任务优先级" field="priority"
        ><c-select
          v-model="draft.priority"
          :options="priorities"
          edit-mode="direct"
      /></c-form-item>
      <c-space wrap
        ><c-button html-type="submit" status="primary">校验并预览</c-button
        ><c-button @click="fill">填入演示数据</c-button></c-space
      >
    </c-form>
    <div v-else-if="stage === 'review'">
      <h4>确认巡检任务</h4>
      <dl>
        <dt>任务</dt>
        <dd>{{ draft.title }}</dd>
        <dt>部门</dt>
        <dd>{{ departmentLabel }}</dd>
        <dt>优先级</dt>
        <dd>{{ draft.priority === "urgent" ? "紧急" : "普通" }}</dd>
      </dl>
      <c-checkbox v-model="failNext" :disabled="busy"
        >模拟下一次保存失败（本地）</c-checkbox
      >
      <c-space wrap
        ><c-button
          status="primary"
          :loading="busy"
          :disabled="busy"
          @click="submit"
          >{{
            message.includes("保存失败") ? "重试提交" : "确认提交"
          }}</c-button
        ><c-button :disabled="busy" @click="stage = 'edit'"
          >返回修改</c-button
        ></c-space
      >
    </div>
    <div v-else>
      <h4>任务已创建</h4>
      <p>
        {{ saved.title }} ·
        {{ saved.priority === "urgent" ? "紧急处理" : "普通处理" }}
      </p>
      <c-button @click="stage = 'edit'">继续编辑</c-button>
    </div>
    <p role="status" aria-live="polite">{{ message }}</p>
    <c-collapse>
      <c-collapse-item title="查看已提交记录" name="saved">
        <pre>{{
          saved
            ? JSON.stringify(saved, null, 2)
            : "尚无记录；校验失败、返回修改或保存失败都不会创建记录。"
        }}</pre>
      </c-collapse-item>
    </c-collapse>
    <c-button @click="reset">重新演示</c-button>
    <small
      >本例使用本地模拟保存，不访问业务服务。校验、确认、保存与失败恢复由业务流程组合。</small
    >
  </section>
</template>
<style scoped>
.workflow-demo {
  width: 100%;
  min-width: 0;
}
.workflow-demo__steps {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  list-style: none;
  padding: 0;
}
.workflow-demo__steps li {
  padding: 8px 12px;
  border-radius: 8px;
  background: var(--c-color-fill-1);
}
.workflow-demo__steps [aria-current] {
  color: var(--c-color-primary);
  font-weight: 700;
}
.workflow-demo dl {
  display: grid;
  grid-template-columns: 80px 1fr;
  gap: 8px;
}
.workflow-demo dd {
  margin: 0;
  overflow-wrap: anywhere;
}
.workflow-demo pre {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
}
.workflow-demo small {
  display: block;
  margin-top: 12px;
  color: var(--c-color-text-2);
}
</style>
```

## API

### Empty values and reading placeholders

Form / FormItem provide empty recognition through `empty-values`; each field defines clear output with its own `empty-value`. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### `<Form>` Props

| Parameter         | Description                                                                                                                                    | Type                                       |        Default        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | :-------------------: |
| model             | Form data object                                                                                                                               | `object`                                   |         `{}`          |
| layout            | The layout of the form, including horizontal, vertical, and multi-column                                                                       | `'horizontal' \| 'vertical' \| 'inline'`   |    `'horizontal'`     |
| size              | The size of the form                                                                                                                           | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`     |        `'md'`         |
| label-col-flex    | Label-column flex; numbers are flex ratios, unit-bearing strings are widths                                                                    | `number \| string`                         |          `-`          |
| label-col-style   | Per-instance label column style                                                                                                                | `CSSProperties`                            |          `-`          |
| wrapper-col-style | Per-instance control column style                                                                                                              | `CSSProperties`                            |          `-`          |
| label-col-props   | Label layout options; same parameters as the col component                                                                                     | `object`                                   | `span: 5, offset: 0`  |
| wrapper-col-props | Form-control layout options; same parameters as the col component                                                                              | `object`                                   | `span: 19, offset: 0` |
| label-align       | Label alignment                                                                                                                                | `'start' \| 'end' \| 'left' \| 'right'`                        |       `'end'`       |
| `content-align`   | Content alignment shared by direct fields, editor triggers and readPretty output; independent of label-align                                   | `'start' \| 'end' \| 'left' \| 'center' \| 'right'`            |       `'start'`        |
| `read-pretty`     | Independent reading toggle. When true, displays the saved value; when false, restores the current edit-mode. FormItem inherits Form when unset | `boolean`                                  |          `-`          |
| `edit-mode`       | Shared editing mode for form fields; when unset, preserves each field default                                                                  | `'direct' \| 'click' \| 'dblclick'`        |          `-`          |
| disabled          | Whether to disable the form                                                                                                                    | `boolean`                                  |          `-`          |
| readonly          | Whether form controls are readonly                                                                                                             | `boolean`                                  |          `-`          |
| rules             | Form item validation rules                                                                                                                     | `Record<string, FieldRule \| FieldRule[]>` |          `-`          |
| auto-label-width  | Automatically measure label widths; only effective with `layout="horizontal"`                                                                  | `boolean`                                  |        `false`        |
| id                | Prefix for form-control ids                                                                                                                    | `string`                                   |          `-`          |
| scroll-to-error   | After failed validation, scroll to the first (start) or last (end) invalid field in document order; this is not viewport alignment             | `'start' \| 'end'`                         |     Do not scroll     |

### `<Form>` Events

| Event          | Description                                                            | Arguments                                                                                                 |
| -------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| submit         | Triggered when the form is submitted                                   | data: `{values: Record<string, any>; errors: Record<string, ValidatedError> \| undefined}`<br>ev: `Event` |
| submit-success | Emitted when validation succeeds                                       | values: `Record<string, any>`<br>ev: `Event`                                                              |
| submit-failed  | Emitted when validation fails                                          | data: `{values: Record<string, any>; errors: Record<string, ValidatedError>}`<br>ev: `Event`              |
| reset          | Emitted on native reset; also resets field values and validation state | ev: `Event`                                                                                               |

### `<form>` Methods

| Method        | Description                     | Arguments                                                                                                | Returns                                              |
| ------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| validate      | Validate all form data          | callback: `(errors: undefined \| Record<string, ValidatedError>) => void`                                | Promise<undefined \| Record<string, ValidatedError>> |
| validateField | Validate selected form fields   | field: `string \| string[]`<br>callback: `(errors: undefined \| Record<string, ValidatedError>) => void` | Promise<undefined \| Record<string, ValidatedError>> |
| resetFields   | Reset form data                 | field: `string \| string[]`                                                                              | -                                                    |
| clearValidate | Clear validation state          | field: `string \| string[]`                                                                              | -                                                    |
| setFields     | Set form-item values and states | data: `Record<string, FieldData>`                                                                        | -                                                    |
| scrollToField | Scroll to a form item           | `field: string`                                                                                          | `-`                                                  |

### `<FormItem>` Props

Layout, label/content columns, styles, alignment and flex inherit from Form when omitted; explicit values override them.

| Parameter         | Description                                                                                                                                    | Type                                                  |       Default       |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | :-----------------: |
| field             | Field path in the data object; required for data fields                                                                                        | `string`                                              |        `''`         |
| label             | Label text                                                                                                                                     | `string`                                              |         `-`         |
| tooltip           | Hint content                                                                                                                                   | `string`                                              |         `-`         |
| show-colon        | Whether to show a colon                                                                                                                        | `boolean`                                             |       `false`       |
| no-style          | Whether to remove styling                                                                                                                      | `boolean`                                             |       `false`       |
| disabled          | Whether disabled                                                                                                                               | `boolean`                                             |         `-`         |
| readonly          | Readonly state; inherits from Form when omitted                                                                                                | `boolean`                                             |         `-`         |
| help              | Help text                                                                                                                                      | `string`                                              |         `-`         |
| extra             | Extra text                                                                                                                                     | `string`                                              |         `-`         |
| required          | Whether a value is required                                                                                                                    | `boolean`                                             |       `false`       |
| asterisk-position | Logical start/end position of the required asterisk within the field label, default start; not the form or popup position                      | `'start' \| 'end'`                                    |      `'start'`      |
| rules             | Field validation rules; take precedence over Form rules                                                                                        | `FieldRule \| FieldRule[]`                            |         `-`         |
| validate-status   | Validation state                                                                                                                               | `'success' \| 'warning' \| 'error' \| 'validating'`   |         `-`         |
| validate-trigger  | Events that trigger validation; `clear` is emitted only by a control `clear` action and is distinct from `change`                              | `'change' \| 'input' \| 'focus' \| 'blur' \| 'clear'` |     `'change'`      |
| size              | Control size; inherits from Form when omitted. Form layout still controls label appearance                                                     | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`                |         `-`         |
| layout            | Form-item layout; inherits from Form when omitted                                                                                              | `'horizontal' \| 'vertical' \| 'inline'`              |         `-`         |
| label-align       | Label alignment; inherits from Form when omitted                                                                                               | `'start' \| 'end' \| 'left' \| 'right'`                                   |         `-`         |
| `content-align`   | Content alignment shared by direct fields, editor triggers and readPretty output; independent of label-align                                   | `'start' \| 'end' \| 'left' \| 'center' \| 'right'`                       | `-` (inherits Form) |
| `read-pretty`     | Independent reading toggle. When true, displays the saved value; when false, restores the current edit-mode. FormItem inherits Form when unset | `boolean`                                             |         `-`         |
| `edit-mode`       | Editing mode; inherits Form when unset and may be overridden by individual fields                                                              | `'direct' \| 'click' \| 'dblclick'`                   |         `-`         |
| label-col-props   | Label layout options; same parameters as the col component                                                                                     | `object`                                              |         `-`         |
| wrapper-col-props | Form-control layout options; same parameters as the col component                                                                              | `object`                                              |         `-`         |
| hide-label        | Hide label                                                                                                                                     | `boolean`                                             |       `false`       |
| hide-asterisk     | Whether to hide the required marker                                                                                                            | `boolean`                                             |       `false`       |
| label-col-style   | Style for the label layout component                                                                                                           | `object`                                              |         `-`         |
| wrapper-col-style | Style for the control layout component                                                                                                         | `object`                                              |         `-`         |
| row-props         | Form-item layout options; same parameters as the row component                                                                                 | `object`                                              |         `-`         |
| row-class         | Class for the form-item layout component                                                                                                       | `string\|array\|object`                               |         `-`         |
| content-class     | Class for the control wrapper                                                                                                                  | `string\|array\|object`                               |         `-`         |
| content-flex      | Whether the content wrapper uses flex layout                                                                                                   | `boolean`                                             |       `true`        |
| label-col-flex    | Sets flex on the label `Col` component; the control `Col` flex is then set to `auto`                                                           | `number\|string`                                      |         `-`         |
| feedback          | Whether to show control feedback icons                                                                                                         | `boolean`                                             |       `false`       |
| label-component   | Element used to render the form-item label                                                                                                     | `string`                                              |      `'label'`      |
| label-attrs       | Native label attributes; for targets the actual control id                                                                                     | `object`                                              |         `-`         |

### `<FormItem>` Slots

| Slot  |  Description  | Arguments |
| ----- | :-----------: | --------- |
| label |     Label     | -         |
| help  | Help content  | -         |
| extra | Extra content | -         |

## Type

### FieldRule

| Parameter | Description                                       | Type                                                                                                        | Default |
| --------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | :-----: |
| type      | Validated value type; defaults to `'string'`      | `'string'    \| 'number'    \| 'boolean'    \| 'array'    \| 'object'    \| 'email'    \| 'url'    \| 'ip'` |   `-`   |
| required  | Whether the value is required                     | `boolean`                                                                                                   | `false` |
| message   | Message displayed on validation failure           | `string`                                                                                                    |   `-`   |
| length    | Required length for string/array values           | `number`                                                                                                    |   `-`   |
| maxLength | Maximum string length                             | `number`                                                                                                    |   `-`   |
| minLength | Minimum string length                             | `number`                                                                                                    |   `-`   |
| match     | Pattern matching for strings                      | `RegExp`                                                                                                    |   `-`   |
| uppercase | Uppercase string validation                       | `boolean`                                                                                                   | `false` |
| lowercase | Lowercase string validation                       | `boolean`                                                                                                   | `false` |
| min       | Minimum numeric value                             | `number`                                                                                                    |   `-`   |
| max       | Maximum numeric value                             | `number`                                                                                                    |   `-`   |
| equal     | Numeric-value validation                          | `number`                                                                                                    |   `-`   |
| positive  | Positive-number validation                        | `boolean`                                                                                                   | `false` |
| negative  | Negative-number validation                        | `boolean`                                                                                                   | `false` |
| true      | Whether a boolean is `true`                       | `boolean`                                                                                                   | `false` |
| false     | Whether a boolean is `false`                      | `boolean`                                                                                                   | `false` |
| includes  | Whether an array contains the specified value     | `any[]`                                                                                                     |   `-`   |
| deepEqual | Whether array elements are equal                  | `any`                                                                                                       |   `-`   |
| empty     | Whether an object is empty                        | `boolean`                                                                                                   | `false` |
| hasKeys   | Whether an object contains the specified property | `string[]`                                                                                                  |   `-`   |
| validator | Custom validation rule                            | `(    value: FieldValue \| undefined,    callback: (error?: string) => void  ) => void`                     |   `-`   |

### FieldData

| Parameter | Description         | Type             | Default |
| --------- | ------------------- | ---------------- | :-----: |
| value     | Field value         | `any`            |   `-`   |
| status    | Field state         | `ValidateStatus` |   `-`   |
| message   | Field error message | `string`         |   `-`   |

### ValidatedError

| Parameter       | Description                              | Type      | Default |
| --------------- | ---------------------------------------- | --------- | :-----: |
| label           | Label text                               | `string`  |   `-`   |
| field           | Field name                               | `string`  |   `-`   |
| value           | Field value                              | `any`     |   `-`   |
| type            | Field type                               | `string`  |   `-`   |
| isRequiredError | Whether this is a `required`-field error | `boolean` | `false` |
| message         | Error message                            | `string`  |   `-`   |

### FormItemEventHandler

| Parameter | Description | Type                   | Default |
| --------- | ----------- | ---------------------- | :-----: |
| onChange  | onChange    | `(ev?: Event) => void` |   `-`   |
| onInput   | onInput     | `(ev?: Event) => void` |   `-`   |
| onFocus   | onFocus     | `(ev?: Event) => void` |   `-`   |
| onBlur    | onBlur      | `(ev?: Event) => void` |   `-`   |

### useFormItem

```ts
const useFormItem = (data: {
  size?: Ref<Size | undefined>;
  disabled?: Ref<boolean>;
  error?: Ref<boolean>;
}) => {
  mergedSize: Ref<Size>;
  mergedDisabled: Ref<boolean>;
  mergedError: Ref<boolean>;
  feedback: Ref<string>;
  eventHandlers: Ref<FormItemEventHandler>;
};
```

## Type definitions

The component exports the following types

```ts
import type { FormProps } from "@cedar-design/ui";
```

### Five density levels and item spacing

xs/sm/md/lg/xl select geometry through size classes. Item bottom spacing and reserved validation-message height both use size-*-item-margin-bottom. Inline layout uses inline-item-margin-bottom; error/help do not add item bottom spacing again.

| Variable                              | Default                     |
| ------------------------------------- | --------------------------- |
| `--c-form-size-xl-height`             | `var(--c-size-xl)`          |
| `--c-form-size-xl-label-font-size`    | `var(--c-sys-font-size-lg)` |
| `--c-form-size-xl-item-margin-bottom` | `var(--c-spacing-8)`        |

### edit-mode inheritance

Form supports `direct / click / dblclick`. When unset, each field retains its own default; FormItem and fields inherit explicitly configured ancestor values, and an explicit field value takes precedence. readPretty controls reading independently of readonly/disabled. Submitting the form fails while a confirmation editor remains unfinished, preserving its draft; reset cancels editing. Existing default slots and v-model are unchanged, and no editor slot is required.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

---

Document: llms/en-US/components/grid.md

<!-- Source: src/grid/README.en-US.md; locale: en-US; page: /en/components/grid/ -->

# Grid

CSS Grid columns, spans, gaps, collapse and suffix items. Use Row / Col for 24-column Flex layouts.

> **Choosing a layout**
>
> - Grid + GridItem: Use for form columns and card grids with consistent column widths, spans, responsive column counts, or collapsed rows and suffix items.
> - Row + Col: Use for 24-column Flex layouts that need horizontal/vertical alignment, wrapping control, fixed and flexible widths together, or responsive ordering. Row controls the row; Col controls width, offset and order.
> - Space: Use for simple groups of buttons, tags or text that only need spacing, direction and alignment. Use native Flex for more flexible width allocation.

## Basic examples

### Columns, spans and offsets

Example source: src/grid/__demos__/basic.vue

```vue
<template><div>
  <c-grid :cols="4" :col-gap="12" :row-gap="12"><c-grid-item v-for="i in 8" :key="i" class="cell">{{ i }}</c-grid-item></c-grid>
  <c-grid :cols="4" :col-gap="12" :row-gap="12"><c-grid-item :span="2" class="cell">span 2</c-grid-item><c-grid-item :offset="1" class="cell soft">offset 1</c-grid-item><c-grid-item :span="4" class="cell">span 4</c-grid-item></c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## Layout and arrangement

### Responsive columns, gaps and spans

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `cols` | Columns per row, minimum 1 | Responsive columns, gaps and spans |
| `col-gap` | Column gap in px | Responsive columns, gaps and spans |
| `row-gap` | Row gap in px | Responsive columns, gaps and spans |
<!-- demo-config-notes:end -->


Example source: src/grid/__demos__/responsive.vue

```vue
<template><div>
  <p>xs: 1 column · sm: 2 columns · md: 4 columns</p>
  <c-grid :cols="{ xs: 1, sm: 2, md: 4 }" :col-gap="{ xs: 8, md: 16 }" :row-gap="{ xs: 8, md: 16 }">
    <c-grid-item :span="{ xs: 1, md: 2 }" class="cell">Responsive span</c-grid-item><c-grid-item v-for="i in 6" :key="i" class="cell soft">{{ i }}</c-grid-item>
  </c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## Customization and slots

### Collapsed rows and suffix slot

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `cols` | Columns per row, minimum 1 | Collapsed rows and suffix slot |
| `col-gap` | Column gap in px | Collapsed rows and suffix slot |
| `row-gap` | Row gap in px | Collapsed rows and suffix slot |
| `collapsed` | Collapse overflowing rows | Collapsed rows and suffix slot |
| `collapsed-rows` | Visible rows while collapsed, minimum 1 | Collapsed rows and suffix slot |
<!-- demo-config-notes:end -->


Example source: src/grid/__demos__/collapse.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const collapsed = ref(true)
const rows = ref(1)
</script>
<template><div>
  <div class="controls"><c-switch v-model="collapsed" aria-label="Collapsed" />Collapsed<c-radio-group v-model="rows"><c-radio :value="1">1 row</c-radio><c-radio :value="2">2 rows</c-radio></c-radio-group></div>
  <c-grid :cols="4" :col-gap="12" :row-gap="12" :collapsed="collapsed" :collapsed-rows="rows">
    <c-grid-item v-for="i in 9" :key="i" class="cell">{{ i }}</c-grid-item>
    <c-grid-item suffix v-slot="{ overflow }"><c-button block variant="outline" @click="collapsed = !collapsed">{{ overflow ? 'More' : 'Less' }}</c-button></c-grid-item>
  </c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## Interaction and control

### Insert, remove and reorder

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `cols` | Columns per row, minimum 1 | Insert, remove and reorder |
| `col-gap` | Column gap in px | Insert, remove and reorder |
| `row-gap` | Row gap in px | Insert, remove and reorder |
| `collapsed` | Collapse overflowing rows | Insert, remove and reorder |
<!-- demo-config-notes:end -->


Example source: src/grid/__demos__/dynamic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const items = ref([1, 2, 3, 4, 5])
let next = 6
</script>
<template><div>
  <div class="controls"><c-button @click="items.unshift(next++)">Insert first</c-button><c-button :disabled="!items.length" @click="items.shift()">Remove first</c-button><c-button @click="items.reverse()">Reverse</c-button></div>
  <c-grid :cols="3" :col-gap="12" :row-gap="12" collapsed><c-grid-item v-for="i in items" :key="i" class="cell">{{ i }}</c-grid-item><c-grid-item suffix v-slot="{ overflow }" class="cell soft">{{ overflow ? '…' : 'End' }}</c-grid-item></c-grid>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

<!-- same-source-api:start -->

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| cols | Columns per row, minimum 1 | `number / ResponsiveValue` | `24` |
| row-gap | Row gap in px | `number / ResponsiveValue` | `0` |
| col-gap | Column gap in px | `number / ResponsiveValue` | `0` |
| collapsed | Collapse overflowing rows | `boolean` | `false` |
| collapsed-rows | Visible rows while collapsed, minimum 1 | `number` | `1` |

### Events

| Event | Description |
| --- | --- |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| cols | Columns per row, minimum 1 | `number / ResponsiveValue` | `24` |
| row-gap | Row gap in px | `number / ResponsiveValue` | `0` |
| col-gap | Column gap in px | `number / ResponsiveValue` | `0` |
| collapsed | Collapse overflowing rows | `boolean` | `false` |
| collapsed-rows | Visible rows while collapsed, minimum 1 | `number` | `1` |

### Events

| Event | Description |
| --- | --- |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

## Responsiveness and accessibility

Breakpoints use the browser viewport: xs is the base; sm ≥576, md ≥768, lg ≥992, xl ≥1200 and xxl ≥1600px. Configured values resolve downward from the largest matching breakpoint. SSR starts with xs and responds to the viewport after mounting. Grid collapsing and dynamic ordering are calculated after mounting. These layout containers add no keyboard shortcuts; callers supply content semantics and focusable elements. There are no public methods or dedicated theme tokens.

## GridItem

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| span | Grid span | number / ResponsiveValue | 1 |
| offset | Empty tracks before the item | number / ResponsiveValue | 0 |
| suffix | Suffix at the end of the row | boolean | false |

The default slot receives `{ overflow: boolean }`, indicating whether collapsing hides content. No custom events or public methods.

## Imports

Grid contains only Grid.Item. Row and Col are independent components with their own source, styles, navigation, documentation and demos. Grid.Row/Grid.Col, Row/Col re-exports from Grid and GridRowInstance/GridColInstance are removed. Import them from the library root or separate row/col entries. Installing Grid no longer registers Row/Col automatically.

---

Document: llms/en-US/components/hover.md

<!-- Source: src/hover/README.en-US.md; locale: en-US; page: /en/components/hover/ -->

# Hover

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:hovering="hovering"`, `:focusing="focusing"`.

Example source: src/hover/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { Hover, useHoverOverlay } from '@cedar-design/ui'
import '@cedar-design/ui/hover/style'

const vHover = Hover
const { hovering, handleHovering } = useHoverOverlay()
const focusing = ref(false)
</script>

<template>
  <c-space direction="column">
    <c-button v-hover="handleHovering" class="hover-example-target" @focus="focusing = true" @blur="focusing = false">
      将鼠标移入，或用 Tab 聚焦
      <c-hover-overlay :hovering="hovering" :focusing="focusing" />
    </c-button>
    <span role="status">悬停：{{ hovering ? '是' : '否' }}；焦点：{{ focusing ? '是' : '否' }}</span>
  </c-space>
</template>

<style scoped>
.hover-example-target { position: relative; }
</style>
```

## API

### Directives

| Usage | Description |
| --- | --- |
| `v-hover="callback"` | Notifies `(hovering: boolean) => void` on mouse enter and leave |
| `v-hover="styleObject"` | Applies styles on mouse enter and restores them on leave |
| `v-hover:desktop` / `v-hover:mobile` | Enabled according to the directive's platform detection; this does not imply real touchscreen hover support |

### HoverOverlay Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| hovering | boolean | false | Hover decoration state |
| focusing | boolean | false | Focus decoration state |

`useHoverOverlay()` returns `hovering` and `handleHovering` for connection to directive callbacks. The overlay is absolutely positioned, so its host must establish a positioning context. For independent use, import `@cedar-design/ui/hover/style`.

---

Document: llms/en-US/components/icon.md

<!-- Source: src/icon/README.en-US.md; locale: en-US; page: /en/components/icon/ -->

# Icon

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic Usage

- `size`: Controls the component size.
- `color`: Overrides the color.

Example source: src/icon/__demos__/basic-usage.vue

```vue
<script setup lang="ts">
import { IconCheckCircleFill } from "@cedar-design/icons-vue";
</script>
<template>
  <div class="icon-demo-row">
    <div>
      <p>Resolver 自动按需导入</p>
      <c-icon size="40" color="red"><c-icon-check-circle-fill /></c-icon>
    </div>
    <div>
      <p>手动按需导入</p>
      <c-icon size="40" color="red"><IconCheckCircleFill /></c-icon>
    </div>
  </div>
</template>
<style scoped>
.icon-demo-row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 32px;
}
p {
  margin: 0 0 12px;
  font-size: 14px;
}
</style>
```

## Appearance and states

### Icon size and color

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | `inherit` | Icon size and color |
| `color` | Icon color | Icon size and color |
<!-- demo-config-notes:end -->


Compare size and color independently of rotation, animation and click handling.

Example source: src/icon/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">图标尺寸</span><span lang="en-US">size</span></h4>
    <c-space wrap align="center" :size="24">
        <c-icon size="20"><c-icon-check-circle /></c-icon>
        <c-icon size="28"><c-icon-check-circle /></c-icon>
        <c-icon size="36"><c-icon-check-circle /></c-icon>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="color">
    <h4><span lang="zh-CN">图标颜色</span><span lang="en-US">color</span></h4>
    <c-space wrap :size="24">
        <c-icon size="28" color="rgb(var(--c-primary-6))"
          ><c-icon-check-circle
        /></c-icon>
        <c-icon size="28" color="rgb(var(--c-success-6))"
          ><c-icon-check-circle
        /></c-icon>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Content and presentation

### Rotate Spin

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | `inherit` | Rotate Spin |
| `rotate` | Rotation angle | Rotate Spin |
| `spin` | Whether to rotate continuously | Rotate Spin |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.

Example source: src/icon/__demos__/rotate-spin.vue

```vue
<template>
  <c-space wrap align="center" :size="32">
    <div class="demo-item">
      <c-icon size="32" :rotate="90"><c-icon-arrow-right /></c-icon>
      <span>rotate="90"</span>
    </div>
    <div class="demo-item">
      <c-icon size="32" spin><c-icon-refresh /></c-icon>
      <span>spin</span>
    </div>
    <div class="demo-item">
      <c-icon-refresh :size="32" :rotate="45" spin />
      <span>独立 SVG：rotate + spin</span>
    </div>
  </c-space>
</template>
<style scoped>
.demo-item {
  display: inline-flex;
  align-items: center;
  gap: 8px;
}
</style>
```

### Catalog

Preview configuration: `clearable`, `placeholder="搜索图标名称"`.

Example source: src/icon/__demos__/catalog.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
import { iconNames } from "@cedar-design/icons-vue";
import * as CedarIcons from "@cedar-design/icons-vue";
import { Message } from "../../message";

const keyword = ref("");
const filteredIcons = computed(() =>
  keyword.value
    ? iconNames.filter((name) =>
        name.includes(keyword.value.trim().toLowerCase()),
      )
    : iconNames,
);

const groupRules = [
  [
    "方向",
    /(^|-)(arrow|caret|chevron|left|right|up|down|expand|shrink|swap|rotate|fullscreen|backward|forward)(-|$)/,
  ],
  [
    "状态与反馈",
    /(^|-)(alert|check|close|error|exclamation|info|question|success|warning|empty|stop)(-|$)/,
  ],
  [
    "编辑",
    /(^|-)(align|attachment|bold|brush|copy|delete|edit|eraser|filter|font|formula|italic|link|list|paste|quote|redo|scissor|sort|underline|undo|zoom)(-|$)/,
  ],
  ["文件", /(^|-)(archive|book|bookmark|drive|file|folder|save|storage)(-|$)/],
  [
    "媒体",
    /(^|-)(camera|image|live|music|mute|pause|play|record|skip|sound|video|voice)(-|$)/,
  ],
  [
    "通信与用户",
    /(^|-)(email|message|notification|phone|send|share|subscribe|user|robot)(-|$)/,
  ],
  [
    "品牌",
    /(alipay|bytedance|codepen|facebook|github|gitlab|google|lark|qq|tiktok|twitter|wechat|weibo|xigua)/,
  ],
  ["天气", /(^|-)weather-|(^|-)sun(-|$)|(^|-)moon(-|$)/],
  ["商业", /(^|-)(barcode|cart|gift|shopping|tag)(-|$)/],
] as const;

const iconGroups = computed(() => {
  const groups = new Map<string, string[]>();
  for (const name of filteredIcons.value) {
    const label = groupRules.find(([, rule]) => rule.test(name))?.[0] ?? "通用";
    if (!groups.has(label)) groups.set(label, []);
    groups.get(label)?.push(name);
  }
  return [...groupRules.map(([label]) => label), "通用"].flatMap((label) => {
    const names = groups.get(label);
    return names?.length ? [[label, names.sort()] as const] : [];
  });
});

function pascalCase(name: string) {
  return name
    .split("-")
    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
    .join("");
}

function resolveIcon(name: string) {
  return CedarIcons[`Icon${pascalCase(name)}` as keyof typeof CedarIcons];
}

async function copyIcon(name: string) {
  const markup = `<c-icon-${name} />`;
  try {
    await navigator.clipboard.writeText(markup);
    Message.success(`已复制 ${markup}`);
  } catch {
    Message.error("复制失败，请检查浏览器剪贴板权限");
  }
}
</script>

<template>
  <c-input v-model="keyword" clearable placeholder="搜索图标名称">
    <template #prefix><c-icon-search /></template>
  </c-input>
  <section v-for="[group, names] in iconGroups" :key="group" class="icon-group">
    <h3>
      {{ group }} <small>{{ names.length }}</small>
    </h3>
    <div class="icon-catalog">
      <c-button
        v-for="name in names"
        :key="name"
        class="icon-card"
        variant="outline"
        @click="copyIcon(name)"
      >
        <span class="icon-card-content">
          <component :is="resolveIcon(name)" :size="40" />
          <span class="icon-name">{{ name }}</span>
        </span>
      </c-button>
    </div>
  </section>
</template>

<style scoped>
.icon-catalog {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(min(100%, 168px), 1fr));
  gap: 16px;
  margin-top: 12px;
}

.icon-group {
  margin-top: 24px;
}
.icon-group h3 {
  margin: 0;
  font-size: 16px;
}
.icon-group small {
  margin-left: 6px;
  color: var(--color-text-3);
  font-weight: normal;
}

.icon-card {
  min-height: 132px;
  height: auto;
  justify-content: center;
  font: inherit;
  line-height: 1.5;
  display: flex;
  min-width: 0;
  flex-direction: column;
  align-items: center;
  gap: 12px;
  padding: 20px 14px;
  color: var(--color-text-1);
  background: var(--color-bg-2);
  border: 1px solid var(--color-border-2);
  border-radius: 8px;
  cursor: pointer;
}

.icon-card:hover {
  color: rgb(var(--c-primary-6));
  border-color: rgb(var(--c-primary-6));
}
.icon-card-content {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 12px;
}
.icon-name {
  width: 100%;
  text-align: center;
  font-size: 13px;
  overflow-wrap: anywhere;
  white-space: normal;
}
</style>
```

## Customization and slots

### Custom

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | `inherit` | Custom |
| `color` | Icon color | Custom |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.
- `color`: Overrides the color.

Example source: src/icon/__demos__/custom.vue

```vue
<template>
  <c-icon size="40" color="currentColor">
    <svg
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      role="img"
      aria-label="自定义菱形图标"
    >
      <path d="M12 2 22 12 12 22 2 12Z" />
      <path d="M8 12h8M12 8v8" />
    </svg>
  </c-icon>
</template>
```

### IconPark custom projects

You can use the **SVG Symbol JS** or **Web Component JS** generated by an IconPark custom project directly. Exporting individual SVG files or generating a Vue component for every icon is optional. These are SVG resource mechanisms, separate from loading text fonts with `@font-face`.

The public `@icon-park/vue-next` component package and your custom project's JS are separate resource sources. Installing the public package does not automatically include your team's uploaded or maintained icons.

| Approach | Resource source | Rendering | Loading unit |
| --- | --- | --- | --- |
| SVG Symbol JS | Custom project script | `svg` / `use` in the default slot | The icon collection in that file |
| Web Component JS | Custom project script | A custom element in the default slot | Depends on the generated implementation; do not assume individual icon loading |
| Individual SVG Vue components | Local files or a component package | Vue components in the default slot | Imported modules, subject to build configuration |

SVG Symbol is a suitable starting point: it reuses the Icon container without configuring Vue custom element recognition.

**Current API:** `CIcon` does not have a `symbol` prop and does not download, register or inject IconPark resources. The examples below use the existing default slot. `name` only resolves icon components registered in the current Vue application; it does not resolve Symbol IDs or Web Component icon names. Default slot content takes precedence over `name`.

#### SVG Symbol: load the project script

Copy the **SVG Symbol** script URL from your custom project and load it once in the application's HTML entry, such as `index.html` in a Vite application:

```html
<!-- Example path: replace with your project URL or a locally deployed copy -->
<script src="/icons/project-symbol.js" defer></script>
```

After execution, the script should inject an SVG collection containing `symbol` nodes into the page. The application owns the resource URL and decides whether to use a remote URL or a deployed static file. The component library does not embed business project URLs. Load the script type you chose; using the same collection does not require loading both script variants.

#### SVG Symbol: reference an icon

Suppose the script injects `<symbol id="project-home" viewBox="0 0 48 48">`. You can render it as follows. Paths and IDs in these examples are placeholders; use the values in your generated output.

```vue
<script setup lang="ts">
import { Icon as CIcon } from '@cedar-design/ui'
import '@cedar-design/ui/icon/style'
</script>

<template>
  <c-icon :size="24" color="#1677ff">
    <svg width="1em" height="1em" aria-hidden="true">
      <use href="#project-home" />
    </svg>
  </c-icon>
</template>
```

`href` uses the complete Symbol ID with a leading `#`. Display names, the library's `name` prop and IconPark icon names may differ from the Symbol ID. Do not invent or strip prefixes; inspect `symbol[id]` in developer tools. This references resources injected into the current page: do not use `href="project.js#project-home"`.

`size` sets the container's font size, and the inner SVG follows it through `1em`. `rotate` and `spin` affect the entire container. Without an explicit `size`, normal Icon size inheritance applies. Preserve the generated Symbol's `viewBox` to avoid clipping or incorrect scaling.

#### An application wrapper for shorter usage

Create an application component named `ProjectIcon.vue` if you want to pass an ID as a prop. This requires neither a library API change nor a generated Vue file for each icon:

```vue
<script setup lang="ts">
import { Icon as CIcon } from '@cedar-design/ui'
import '@cedar-design/ui/icon/style'

defineProps<{ symbol: string }>()
</script>

<template>
  <c-icon>
    <svg width="1em" height="1em" aria-hidden="true">
      <use :href="`#${symbol}`" />
    </svg>
  </c-icon>
</template>
```

Use it in the application:

```vue
<script setup lang="ts">
import ProjectIcon from './ProjectIcon.vue'
</script>

<template>
  <ProjectIcon symbol="project-home" :size="24" color="#1677ff" />
</template>
```

Here, `symbol` belongs to the application wrapper and excludes `#`. Undeclared attributes such as `size`, `color`, `rotate` and `spin` fall through to the single `CIcon` root. Forward `$attrs` explicitly if you add multiple roots or disable `inheritAttrs`. The existing `transition` prop only animates `CIcon`'s `name` changes; it does not animate Symbol reference changes inside the slot.

#### Web Component: script and compiler configuration

Alternatively, load your project's **Web Component JS** and place its registered element in the slot. The following assumes the generated element is named `iconpark-icon` and uses a `name` attribute. Confirm element names, attributes and theme support against your project's generated usage instructions.

```html
<!-- Application HTML entry; use the Web Component variant here -->
<script src="/icons/project-web-component.js" defer></script>
```

Configure the build that compiles Vue SFCs containing this tag to recognize the custom element. For Vite:

```ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: (tag) => tag === 'iconpark-icon',
        },
      },
    }),
  ],
})
```

Merge this into the existing Vue plugin configuration instead of adding a duplicate plugin. `isCustomElement` is a compile-time setting; setting only `app.config.compilerOptions` does not replace this configuration when using a build tool. Configure the library build when the tag is wrapped inside library source, or the application build when application source uses the tag directly.

```vue
<template>
  <c-icon :size="24" color="#1677ff">
    <iconpark-icon name="project-home" size="1em"></iconpark-icon>
  </c-icon>
</template>
```

This example uses the application's existing `c-icon` import or registration. The outer `CIcon` does not automatically forward theme, stroke width or other attributes to slot content. Set supported attributes directly on the custom element. If it uses Shadow DOM, external `.c-icon svg` rules cannot directly style its inner SVG; use the element's supported attributes, inherited styles or CSS variables.

#### Size, color and multicolor icons

| Setting | Behavior and limitations |
| --- | --- |
| `size` | Symbol examples inherit through `1em`; check the Web Component's own sizing API |
| `color` | Works only when the graphic uses `currentColor` or supports corresponding inheritance |
| Fixed `fill` / `stroke` | Colors embedded in the graphic are not automatically overridden by the container's `color` |
| Multicolor icons | Preserve their colors; avoid forcing a single `fill` or `stroke` across all paths |
| Themes and stroke width | Depend on generated output; public Vue icon package props do not automatically apply to project scripts |

#### On-demand loading and bundle size

Importing components on demand and loading icon resources are independent. Slot usage does not make `CIcon` depend on the entire IconPark package, and existing Resolver imports still work. The Resolver does not load resources based on a `use` ID.

A Symbol script that injects a collection loads that entire file. If it contains 200 icons and a page references three, all 200 are still downloaded and injected. `href="#project-home"` selects a graphic; it does not request an individual icon. A static script is outside the application's module tree-shaking analysis, and string IDs do not automatically remove unused Symbols.

| Goal | Approach |
| --- | --- |
| Small collection reused across pages | Load once at application entry and reuse the browser cache by file version |
| Large collection with distinct business modules | Split resources into shared and module collections; load each when its route or module needs it |
| Render the page before loading icons | Manage loading, failure and placeholder states in the application; show icons when resources are ready |
| Require individual icons to participate in tree shaking | Use separate SVG modules or Vue components and verify package exports and actual build output |

Remote JS is outside the library's npm package but still contributes to application download size. Updating the project requires updating generated resources and their cache versions. The component library's build size alone does not describe page cost.

#### Loading order, SSR and accessibility

- Make static resources available when icons are needed. For dynamic loading, wait for successful script execution. For Web Components, `customElements.whenDefined('iconpark-icon')` can additionally wait for registration; it neither downloads the script nor automatically settles on a resource loading failure.
- Load each resource once per application instead of inserting a script on every component mount. Keep Symbol IDs unique across collections to avoid conflicting references.
- Do not execute scripts requiring `window`, `document` or `customElements` on the server. Use HTML scripts or client lifecycle loading. When rendering conditionally, keep server and initial client placeholders consistent. Icons remain invisible until their resources exist; strict first-paint requirements need server-inlined Symbols or individual SVGs.
- Use `aria-hidden="true"` for decorative SVGs. Give standalone informative SVGs `role="img"` and an accessible name. Give icon-only buttons an `aria-label` on the button itself.

#### Troubleshooting

| Symptom | Check |
| --- | --- |
| Blank icon | Successful script execution, correct script variant, exact ID and nonzero container size |
| `Failed to resolve component: iconpark-icon` | Compile-time `isCustomElement` configuration for the source containing the tag |
| Color does not change | Fixed graphic colors or the Web Component's supported color interface |
| Size does not follow `CIcon` | Inner SVG / element sizing through `1em` and any fixed pixel dimensions |
| Old icon after a project update | Current script version and browser / CDN caching |
| Works locally but fails after deployment | Resource base paths, network requests, CSP `script-src` and script execution errors |
| Wrong icon with multiple collections | Symbol ID collisions, duplicate scripts and the unique IDs in actual output |

References: [Vue and Web Components](https://vuejs.org/guide/extras/web-components), [SVG use element](https://developer.mozilla.org/en-US/docs/Web/SVG/Reference/Element/use).

## Interaction and control

### Click

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | `inherit` | Click, Dynamic Name |
| `color` | Icon color | Click |
| `name` | Explicitly registered icon name | Dynamic Name |
| `transition` | Name-change animation duration in ms | Dynamic Name |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.
- `color`: Overrides the color.

Example source: src/icon/__demos__/click.vue

```vue
<script setup lang="ts">
import { Message } from "@cedar-design/ui";
</script>
<template>
  <c-button
    variant="text"
    round
    aria-label="确认操作"
    @click="Message.success('点击成功')"
  >
    <template #icon><c-icon-check-circle /></template>
  </c-button>
</template>
```

### Dynamic Name

- `size`: Controls the component size.

Example source: src/icon/__demos__/dynamic-name.vue

```vue
<script setup lang="ts">
import { getCurrentInstance, ref } from "vue";
import {
  IconArrowLeft,
  IconArrowRight,
  IconCheckCircle,
  IconInfoCircle,
  IconRefresh,
  IconSearch,
} from "@cedar-design/icons-vue";
const iconName = ref("arrow-left");
const app = getCurrentInstance()?.appContext.app;
const icons = {
  IconArrowLeft,
  IconArrowRight,
  IconCheckCircle,
  IconInfoCircle,
  IconRefresh,
  IconSearch,
};
for (const [name, component] of Object.entries(icons)) {
  if (app && !app.component(name)) {
    app.component(name, component);
  }
}
function toggle() {
  iconName.value =
    iconName.value === "arrow-left" ? "arrow-right" : "arrow-left";
}
</script>
<template>
  <p>
    name 是已注册图标的名称。本例提供
    arrow-left、arrow-right、check-circle、info-circle、refresh、search；默认插槽存在时优先显示插槽内容。
  </p>
  <div class="icon-name-demo">
    <c-space wrap align="center" :size="24">
      <c-button @click="toggle">切换图标</c-button>
      <c-icon :name="iconName" :size="32" :transition="300" />
    </c-space>
  </div>
</template>
```

## Lifecycle and edge cases

### Lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `name` | Explicitly registered icon name | Lifecycle |
| `transition` | Name-change animation duration in ms | Lifecycle |
| `size` | `inherit` | Lifecycle |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.

Example source: src/icon/__demos__/lifecycle.vue

```vue
<script setup lang="ts">
import { computed, getCurrentInstance, KeepAlive, ref } from "vue";
import { IconArrowLeft, IconArrowRight } from "@cedar-design/icons-vue";

const language = ref("zh-CN");
const english = computed(() => language.value === "en-US");

const active = ref(true),
  iconName = ref("arrow-left"),
  duration = ref(300);
const app = getCurrentInstance()?.appContext.app;
if (app && !app.component("IconArrowLeft")) {
  app.component("IconArrowLeft", IconArrowLeft);
}
if (app && !app.component("IconArrowRight")) {
  app.component("IconArrowRight", IconArrowRight);
}
function toggleName() {
  iconName.value =
    iconName.value === "arrow-left" ? "arrow-right" : "arrow-left";
}
</script>
<template>
  <c-space wrap>
    <c-button @click="toggleName">{{
      english ? "Switch name" : "切换名称"
    }}</c-button>
    <c-button @click="active = !active">{{
      english ? "Toggle active" : "切换激活"
    }}</c-button>
    <c-button @click="duration = duration ? 0 : 300"
      >{{ english ? "Toggle duration" : "切换时长" }} {{ duration }}ms</c-button
    >
    <KeepAlive
      ><c-icon v-if="active" :name="iconName" :transition="duration" :size="32"
    /></KeepAlive>
  </c-space>
  <p>
    {{
      english
        ? "Inactive changes commit on activation without replay. Duration changes cancel the old phase; zero shows the latest name immediately."
        : "停用后切换名称，激活直接显示最新图标，不重放旧动画；时长变更取消旧阶段，0立即显示最新名称。"
    }}
  </p>
</template>
```

## API

### Icon Props

| Prop | Description | Type | Default |
| --------------- | ---------------------- | ---------------- | ------ |
| name | Explicitly registered icon name | string | - |
| size | `inherit` | number \| string | - |
| color | Icon color | string | - |
| rotate | Rotation angle | number | - |
| spin | Whether to rotate continuously | boolean | false |
| transition | Name-change animation duration in ms | number \| string | 0 |
| animation-class | Custom transition animation class | string | - |

### Icon-xxx Props

| Prop | Description | Type | Default |
| --------------- | ---------- | ------------------------------------------ | ------- |
| size | `inherit` | number \| string | - |
| color | Icon color | string | - |
| rotate | Rotation angle | number | - |
| spin | Whether to rotate | boolean | false |
| title | Accessible title | string | - |
| stroke-width | Stroke width | number | 4 |
| stroke-linecap | Stroke line cap | 'butt' \| 'round' \| 'square' | 'butt' |
| stroke-linejoin | Stroke line join | 'bevel' \| 'inherit' \| 'miter' \| 'round' | 'miter' |

### Icon Events

| Event | Description | Arguments |
| ------ | -------------- | --------------------------- |
| click | Click event | (event: MouseEvent) => void |

### Icon Slots

| Slot | Description |
| ------- | -------------- |
| default | Custom default content |

### Type definitions

The component exports the following types

```ts
import type { IconProps } from "@cedar-design/ui";
```

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Only icons registered in the current application are resolved. Repeated name changes cancel stale timers; no changes run after unmount. Each library locally adapts its registration prefix and legacy spin class; icon resources are not imported across libraries.

Icons inherit the host font size on both platforms. For a fixed 20px icon, set size="20" or icon-size explicitly. The size prop overrides the variable; color inherits from the host by default.

### Motion variables

| Token | Default |
| --- | --- |
| `--c-icon-spin-duration` | `1s` |

Built-in motion follows prefers-reduced-motion: reduce: content and state feedback remain, while decorative spinning, shimmer and ripples stop. Icon name changes display the latest value immediately and cancel unfinished phases, keeping CSS and JS durations aligned. Callers must adapt custom animation classes. Ripple duration/cleanup follows Ripple documentation; its historical 250ms rule is not an Icon duration limit.

---

Document: llms/en-US/components/image.md

<!-- Source: src/image/README.en-US.md; locale: en-US; page: /en/components/image/ -->

# Image

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `width`: Sets the configured width.

Example source: src/image/__demos__/basic.vue

```vue
<template>
  <c-image width="200" src="/cat.jpg" />
</template>
```

## Image presentation and states

### Fit Mode

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `width` | Displayed image width | Fit Mode, Captions and additional content, Error |
| `src` | Image source URL | Fit Mode, Captions and additional content, Error |
| `height` | Displayed image height | Fit Mode, Error, Loader |
| `preview-disabled` | Whether click preview is disabled | Fit Mode, Loader, Lazy |
| `object-fit` | How the image fits its container | Fit Mode, Lazy |
| `title` | Title | Captions and additional content |
<!-- demo-config-notes:end -->


- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/fit-mode.vue

```vue
<script setup lang="ts">
const fits = ['fill', 'contain', 'cover', 'none', 'scale-down'] as const
</script>

<template>
  <c-space :size="16" wrap>
    <c-space v-for="fit in fits" :key="fit" direction="column" align="center" :size="8">
      <c-image width="120" height="120" :object-fit="fit" preview-disabled src="/cat.jpg" />
      <span class="label">{{ fit }}</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: 12px;
}
</style>
```

### Captions and additional content

Compare caption and extra-slot placement independently of previews, loading and failures.

Example source: src/image/__demos__/content-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="caption">
    <h4><span lang="zh-CN">标题与描述</span><span lang="en-US">caption</span></h4>
    <c-space :size="24" wrap>
        <c-image width="200" src="/cat.jpg" title="一只猫" description="页脚在图片内侧" />
        <c-image width="200" src="/cat2.jpg" title="一只猫" description="页脚在图片外侧" footer-position="outer" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="extra">
    <h4><span lang="zh-CN">底部额外内容</span><span lang="en-US">extra</span></h4>
    <c-space :size="24" wrap>
        <c-image width="200" src="/cat.jpg" title="一只猫" description="内侧额外内容">
          <template #extra>
            <span class="extra">Extra</span>
          </template>
        </c-image>
        <c-image width="200" src="/cat.jpg" title="一只猫" description="外侧额外内容" footer-position="outer">
          <template #extra>
            <span class="extra extra--outer">Extra</span>
          </template>
        </c-image>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--2 {

.extra {
  padding: 2px 8px;
  color: #fff;
  font-size: 12px;
  background: rgb(0 0 0 / 45%);
  border-radius: 10px;
}

.extra--outer {
  color: currentColor;
  background: var(--c-color-fill-2);
}

}
</style>
```

### Error

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/error.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image width="160" height="120" src="data:image/png;base64,AA==" />
    <c-image width="160" height="120" src="data:image/png;base64,AA==" alt="自定义错误内容">
      <template #error>
        <div class="error-slot">加载失败</div>
      </template>
    </c-image>
  </c-space>
</template>

<style scoped>
.error-slot {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 100%;
  height: 100%;
  color: var(--c-color-text-3);
  font-size: 12px;
}
</style>
```

### Loader

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/loader.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const timestamp = ref('')

function reload() {
  timestamp.value = String(Date.now())
}
</script>

<template>
  <c-space direction="column" :size="16">
    <c-button status="primary" size="sm" @click="reload">重新加载</c-button>
    <c-space :size="16" wrap>
      <c-image width="160" height="160" show-loader :src="`/cat.jpg?reload=${timestamp}`" preview-disabled />
      <c-image width="160" height="160" :src="`/cat.jpg?reload=${timestamp}`" preview-disabled>
        <template #loader>
          <div class="loader-animate" />
        </template>
      </c-image>
      <c-image width="160" height="160" :src="`/cat.jpg?reload=${timestamp}`" preview-disabled>
        <template #loader>
          <img class="progressive" src="/cat2.jpg" alt="" />
        </template>
      </c-image>
    </c-space>
  </c-space>
</template>

<style scoped>
.loader-animate {
  width: 100%;
  height: 100%;
  background: linear-gradient(
    -60deg,
    var(--c-color-fill-2) 25%,
    var(--c-color-fill-3) 40%,
    var(--c-color-fill-2) 55%
  );
  background-size: 400% 100%;
  animation: loop-circle 1.5s cubic-bezier(0.34, 0.69, 0.1, 1) infinite;
}

.progressive {
  width: 100%;
  height: 100%;
  object-fit: cover;
  filter: blur(5px);
}

@keyframes loop-circle {
  0% {
    background-position: 100% 50%;
  }

  100% {
    background-position: 0 50%;
  }
}
</style>
```

### Lazy

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/lazy.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image width="160" height="120" object-fit="cover" lazy src="/cat.jpg" preview-disabled />
    <c-image width="160" height="120" object-fit="cover" src="data:image/png;base64,AA==" fallback-src="/cat2.jpg" preview-disabled />
  </c-space>
</template>
```

## Preview entries and groups

### Disable Preview

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `width` | Displayed image width | Disable Preview, Preview Entry, Preview Group |
| `src` | Image source URL | Disable Preview, Preview Entry, Preview Group |
| `height` | Displayed image height | Preview Entry, Preview Group |
| `object-fit` | How the image fits its container | Preview Entry, Preview Group |
| `preview-disabled` | Whether click preview is disabled | Disable Preview |
| `preview-props` | Preview options | Preview Entry |
<!-- demo-config-notes:end -->


- `width`: Sets the configured width.

Example source: src/image/__demos__/disable-preview.vue

```vue
<template>
  <c-image preview-disabled width="200" src="/cat.jpg" />
</template>
```

### Preview Entry

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/preview-entry.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const previewOpen = ref(false)
</script>

<template>
  <c-space direction="column" :size="16">
    <c-image width="160" height="120" object-fit="cover" src="/cat.jpg" preview-src="/cat2.jpg" />
    <c-button status="primary" size="sm" @click="previewOpen = true">打开预览</c-button>
    <c-image
      v-model:open="previewOpen"
      width="160"
      height="120"
      object-fit="cover"
      src="/cat.jpg"
      :preview-props="{ scaleStep: 1 }"
    />
  </c-space>
</template>
```

### Component Preview

Preview configuration: `v-model:open="open"`, `src="/cat.jpg"`.

Example source: src/image/__demos__/component-preview.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <c-space direction="column" :size="16">
    <c-button status="primary" size="sm" @click="open = true">打开单图预览</c-button>
    <c-image-preview v-model:open="open" src="/cat.jpg" />
  </c-space>
</template>
```

### Imperative Preview

Example source: src/image/__demos__/imperative-preview.vue

```vue
<script setup lang="ts">
const images = ['/cat.jpg', '/cat2.jpg']
let handle: { next: () => void; close: () => void } | undefined

function previewSingle() {
  imagePreview(images[0])
}

function previewMultiple() {
  handle = imagePreview({ images, modelValue: 1 })
}

function next() {
  handle?.next()
}

function close() {
  handle?.close()
}
</script>

<template>
  <c-space :size="12" wrap>
    <c-button status="primary" size="sm" @click="previewSingle">预览单图</c-button>
    <c-button status="primary" size="sm" @click="previewMultiple">预览多图</c-button>
    <c-button size="sm" @click="next">下一张</c-button>
    <c-button size="sm" @click="close">关闭</c-button>
  </c-space>
</template>
```

### Preview Group

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/preview-group.vue

```vue
<template>
  <c-image-preview-group loop>
    <c-space :size="16" wrap>
      <c-image src="/cat.jpg" width="120" height="120" object-fit="cover" />
      <c-image src="/cat2.jpg" width="120" height="120" object-fit="cover" />
    </c-space>
  </c-image-preview-group>
</template>
```

### Component Preview Group

Preview configuration: `v-model:open="open"`, `:images="images"`, `:loop="false"`.

Example source: src/image/__demos__/component-preview-group.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
const current = ref(2)
const images = ['/cat.jpg', '/cat2.jpg']
</script>

<template>
  <c-space direction="column" :size="16">
    <p>默认在 body 全屏预览；切换缓存图片不重复等待加载。</p>
    <c-button status="primary" size="sm" @click="open = true">打开预览组</c-button>
    <c-image-preview-group v-model:open="open" v-model="current" :images="images" :loop="false" />
  </c-space>
</template>
```

## Preview customization and interaction

### Ripple

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `width` | Displayed image width | Ripple, Overlay Closable, Hide Footer Never |
| `src` | Image source URL | Ripple, Overlay Closable, Hide Footer Never |
| `height` | Displayed image height | Ripple, Overlay Closable, Presentation |
| `object-fit` | How the image fits its container | Ripple, Overlay Closable, Presentation |
| `preview-disabled` | Whether click preview is disabled | Ripple, Hide Footer Never, Presentation |
| `preview-props` | Preview options | Overlay Closable, Preview Popup Container |
<!-- demo-config-notes:end -->


- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/ripple.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image width="120" height="120" object-fit="cover" ripple preview-disabled src="/cat.jpg" />
    <c-image :block="false" width="120" height="120" object-fit="cover" preview-disabled src="/cat.jpg" />
    <c-image :block="false" width="120" height="120" object-fit="cover" preview-disabled src="/cat2.jpg" />
  </c-space>
</template>
```

### Overlay Closable

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/overlay-closable.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-image
      width="120"
      height="120"
      object-fit="cover"
      src="/cat.jpg"
      :preview-props="{ overlayClosable: true }"
    />
    <c-image
      width="120"
      height="120"
      object-fit="cover"
      src="/cat2.jpg"
      :preview-props="{ overlayClosable: false }"
    />
  </c-space>
</template>
```

### Hide Footer Never

- `width`: Sets the configured width.

Example source: src/image/__demos__/hide-footer-never.vue

```vue
<template>
  <c-image
    width="200"
    src="data:image/png;base64,AA=="
    title="一只猫"
    description="错误时仍显示底部信息"
    hide-footer="never"
    preview-disabled
  />
</template>
```

### Preview Features

Preview configuration: `v-model:open="open"`, `:images="images"`, `:loop="false"`, `name="切换"`.

Example source: src/image/__demos__/preview-features.vue

```vue
<script setup lang="ts">
import { ImagePreviewAction as CImagePreviewAction } from '../index'

import { ref } from 'vue'

const open = ref(false)
const current = ref(1)
const images = ['/cat.jpg', '/cat2.jpg']

function onAction() {
  current.value = current.value === 0 ? 1 : 0
}
</script>

<template>
  <c-space direction="column" :size="16">
    <c-button status="primary" size="sm" @click="open = true">打开自定义预览</c-button>
    <c-image-preview-group v-model:open="open" v-model="current" :images="images" :loop="false">
      <template #close-icon>
        <span class="close-icon">×</span>
      </template>
      <template #indicator="{ imageNumber, length }">
        <span class="indicator">{{ imageNumber }} / {{ length }}</span>
      </template>
      <template #actions>
        <c-image-preview-action name="切换" @click="onAction">+</c-image-preview-action>
      </template>
    </c-image-preview-group>
  </c-space>
</template>

<style scoped>
.close-icon {
  font-size: 24px;
  color: #fff;
}

.indicator {
  position: absolute;
  top: 16px;
  left: 50%;
  padding: 4px 12px;
  color: #fff;
  font-size: 12px;
  background: rgb(0 0 0 / 45%);
  border-radius: 12px;
  transform: translateX(-50%);
}
</style>
```

### Presentation

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/image/__demos__/presentation.vue

```vue
<template>
  <c-space :size="16" wrap>
    <c-space direction="column" align="center" :size="8">
      <c-image width="160" height="100" object-fit="cover" object-position="left top" preview-disabled src="/cat.jpg" />
      <span class="label">160×100 · left top</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-image width="100" height="100" object-fit="cover" :radius="12" preview-disabled src="/cat.jpg" />
      <span class="label">radius 12</span>
    </c-space>
    <c-space direction="column" align="center" :size="8">
      <c-image width="100" height="100" object-fit="cover" radius="50%" preview-disabled src="/cat.jpg" />
      <span class="label">radius 50%</span>
    </c-space>
  </c-space>
</template>

<style scoped>
.label {
  color: var(--c-color-text-3);
  font-size: 12px;
}
</style>
```

### Preview Popup Container

- `width`: Sets the configured width.

Example source: src/image/__demos__/preview-popup-container.vue

```vue
<template>
  <div id="image-demo-preview-popup-container" class="popup-container">
    <c-image
      width="160"
      src="/cat.jpg"
      :preview-props="{
        popupContainer: '#image-demo-preview-popup-container',
        closable: false,
      }"
    />
  </div>
</template>

<style scoped>
.popup-container {
  position: relative;
  height: 220px;
  padding: 16px;
  overflow: hidden;
  background: var(--c-color-fill-2);
}
</style>
```

## Lifecycle

### Track Lifecycle

Preview configuration: `v-model:open="open"`, `:images="images"`, `:loop="loop"`, `name="Replace images / 换图"`.

Example source: src/image/__demos__/track-lifecycle.vue

```vue
<script setup lang="ts">
import { ImagePreviewAction as CImagePreviewAction } from '../index'

import { ref } from 'vue'
const active = ref(true)
const open = ref(false)
const current = ref(1)
const loop = ref(true)
const images = ref(['/cat.jpg', '/cat2.jpg'])
function replaceImages() { images.value = [...images.value].reverse() }
</script>
<template>
  <div>
    <c-button @click="open = true">Open / 打开</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="loop = !loop">Loop / 循环</c-button>
    <c-button @click="replaceImages">Replace images / 等长换图</c-button>
    <p>Current / 当前: {{ current }}. Navigate across the loop edge; deactivate, close or replace images. Old work must not replay.</p>
    <KeepAlive>
      <c-image-preview-group v-if="active" v-model:open="open" v-model="current" :images="images" :loop="loop">
        <template #actions>
          <c-image-preview-action name="Replace images / 换图" @click="replaceImages">换图</c-image-preview-action>
          <c-image-preview-action name="Deactivate / 停用" @click="active = false">停用</c-image-preview-action>
        </template>
      </c-image-preview-group>
    </KeepAlive>
  </div>
</template>
```

### Controller Lifecycle

Preview configuration: `v-model:open="open"`, `:src="source"`, `interaction="touch"`, `:keyboard="true"`.

Example source: src/image/__demos__/controller-lifecycle.vue

```vue
<script setup lang="ts">
import { ImagePreviewAction as CImagePreviewAction } from '../index'

import { ref } from "vue";
const open = ref(false);
const active = ref(true);
const source = ref("/cat.jpg");
const presses = ref(0);
const switchSource = () => {
  source.value = source.value === "/cat.jpg" ? "/cat2.jpg" : "/cat.jpg";
};
</script>
<template>
  <div>
    <c-button @click="open = true">Open / 打开预览</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <p>
      Long presses / 长按通知: {{ presses }}. Cancel or deactivate; old input
      must not replay.
    </p>
    <KeepAlive>
      <c-image-preview
        v-if="active"
        v-model:open="open"
        :src="source"
        interaction="touch"
        :keyboard="true"
        @long-press="presses++"
      >
        <template #actions>
          <c-image-preview-action
            name="Switch source / 换图"
            @click="switchSource"
            >换图</c-image-preview-action
          >
          <c-image-preview-action
            name="Deactivate / 停用"
            @click="active = false"
            >停用</c-image-preview-action
          >
        </template>
      </c-image-preview>
    </KeepAlive>
  </div>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Preview collection navigation, horizontal keys and swipes follow reading direction without reversing the image array. Direction changes cancel pending gestures while preserving the current image, scale and rotation. Images and zoomed pan coordinates are not mirrored. Numerical indicators remain LTR.

## API

ImagePreviewGroup binds a one-based image number through ordinary `v-model`; `defaultValue` initializes the uncontrolled index. Panel opening uses `v-model:open` and `defaultOpen` independently. Programmatic preview options also use modelValue/`defaultValue` and onUpdate:modelValue.

### `<image>` Props

| Parameter | Description | Type | Default | Version |
| -------------------------- | ------------------------------------------------------- | ---------------------------------------------------------- | :-------: | :----- |
| src | Image source URL | `string` | `-` |  |
| width | Displayed image width | `string \| number` | `-` |  |
| height | Displayed image height | `string \| number` | `-` |  |
| title | Title | `string` | `-` |  |
| description | Caption displayed at the bottom; also used as alt when alt is empty | `string` | `-` |  |
| object-fit | How the image fits its container | `'contain' \| 'cover' \| 'fill' \| 'none' \| 'scale-down'` | `-` |  |
| alt | Image text description | `string` | `-` |  |
| hide-footer | Whether to hide the footer; supports `'never'`, which retains the footer on error | `boolean \| 'never'` | `false` |  |
| footer-position | Footer region inside (inner) or outside (outer) the image, default inner; not four-side popup placement | `'inner' \| 'outer'` | `'inner'` |  |
| show-loader | Whether to show a loading effect | `boolean` | `false` |  |
| preview-disabled | Whether click preview is disabled | `boolean` | `false` |  |
| open **(v-model)** | Controlled preview open state | `boolean` | `-` |  |
| default-open | Default preview open state | `boolean` | `false` |  |
| preview-props | Preview options | `ImagePreviewProps` | `-` |  |
| footer-class | Footer-area class | `string\|array\|object` | `-` | 2.23.0 |
| popup-container | Preview mount container | `string \| HTMLElement \| false` | `-` |  |

### `<image>` Events

| Event | Description | Arguments |
| ------------------- | -------------------- | --------------- |
| open-change | Preview open/close event | open: `boolean` |

### `<image>` Slots

| Slot | Description | Arguments |
| --------------- | :------------------: | ---- |
| error | Custom error-state content | - |
| error-icon | Custom error-state icon | - |
| loader | Custom loading effect | - |
| extra | Additional footer content | - |
| preview-actions | Custom preview toolbar | - |

### `<image-preview>` Props

| Parameter | Description | Type | Default |
| ------------------ | ----------------------------------------------------------------- | ----------------------- | :----------------------------------------------------------------------------------------: |
| src | Image source URL | `string` | `-` |
| open **(v-model)** | Whether open | `boolean` | `-` |
| default-open | Default uncontrolled open state | `boolean` | `false` |
| overlay-closable | Whether clicking the overlay outside the image requests closing; clicking the image does not close it | `boolean` | `true` |
| closable | Show the close button | `boolean` | `true` |
| actions-layout | Action layout | `string[]` | `[  'fullScreen',  'rotateRight',  'rotateLeft',  'zoomIn',  'zoomOut',  'originalSize',]` |
| popup-container | Popup mount target, matching `teleport` `to`; defaults `to` document.body | `HTMLElement \| string \| false` | `-` |
| esc-to-close | Whether ESC closes the preview | `boolean` | `true` |
| wheel-zoom | Whether mouse-wheel zoom is enabled | `boolean` | `true` |
| keyboard | Whether keyboard controls are enabled | `boolean` | `true` |
| default-scale | Default zoom scale | `number` | `1` |
| scale-step | Zoom increment per action | `number` | `0.5` |

### `<image-preview>` Events

| Event | Description | Arguments |
| ----------- | ------------ | --------------- |
| close | Close event | - |
| open-change | Open-state change | open: `boolean` |

### `<image-preview>` Slots

| Slot | Description | Arguments | Version |
| ------- | :----------------: | ---- | :----- |
| actions | Additional custom actions | - | 2.17.0 |

### `<image-preview-group>` Props

| Parameter | Description | Type | Default |
| --------------------- | ----------------------------------------------------------------- | ----------------------- | :----------------------------------------------------------------------------------------: |
| images | Image list; providing it disables collection of child Image sources | `string[]` | `-` |
| model-value **(v-model)** | Index of the current image, starting at 1 | `number` | `-` |
| default-value | Initially displayed image index, starting at 1 | `number` | `1` |
| loop | Whether to loop indefinitely | `boolean` | `false` |
| open **(v-model)** | Controlled open state | `boolean` | `-` |
| default-open | Default uncontrolled open state | `boolean` | `false` |
| overlay-closable | Whether clicking the overlay outside the image requests closing; clicking the image does not close it | `boolean` | `true` |
| closable | Show the close button | `boolean` | `true` |
| actions-layout | Toolbar layout | `string[]` | `[  'fullScreen',  'rotateRight',  'rotateLeft',  'zoomIn',  'zoomOut',  'originalSize',]` |
| popup-container | Popup mount target, matching `teleport` `to`; defaults `to` document.body | `string \| HTMLElement \| false` | `-` |

### `<image-preview-group>` Events

| Event | Description | Arguments |
| ----------- | ---------------- | --------------- |
| change | Switch image | imageNumber: `number`，previousImageNumber: `number` |
| open-change | Preview open/close | open: `boolean` |

### `<image-preview-group>` Slots

| Slot | Description | Arguments | Version |
| ------- | :----------------: | ---- | :----- |
| actions | Additional custom actions | - | 2.46.0 |

### `<image-preview-action>` Props (2.17.0)

| Parameter | Description | Type | Default |
| -------- | -------- | --------- | :-----: |
| name | Name | `string` | `-` |
| disabled | Whether disabled | `boolean` | `false` |

### Type definitions

```ts
import type { ImageInstance } from "@cedar-design/ui";
import { imagePreview } from "@cedar-design/ui";
```

### `imagePreview` methods

Replacing an imperative preview disposes the previous instance and invokes its `onClosed` once, just like normal closure. Use this callback to release owned resources such as Object URLs. Old handles never close newer previews. If `onClosed` synchronously opens a new preview, that newer call wins and the interrupted outer call returns `undefined`.

| Method | Description | Arguments |
| ---------------------------------- | ------------ | ------------------------------------- |
| `imagePreview` | Open the image preview | `url \| url[] \| ImagePreviewOptions` |
| `imagePreview.close` | Close the preview | `-` |
| `imagePreview.setDefaultOptions` | Set default configuration | `ImagePreviewOptions` |
| `imagePreview.resetDefaultOptions` | Reset default configuration | `-` |

## FAQ

### `image-preview` prop notes

1. With `keyboard` set to `true`, shortcuts are enabled according to `actions-layout`.

- `esc`: close the preview
- `left`: previous image
- `right`: next image
- `up`: zoom in
- `down`: zoom out
- `space`: restore original size

2. `defaultScale` sets the initial zoom ratio. For example, 1.5 initially displays the image at 1.5 times its original size.

3. `scaleStep` sets the zoom increment for wheel, double-click and toolbar actions.

### Variable consumption boundaries

`--c-image-preview-arrow-font-size` controls preview-group arrows. DOM for old actions-item, trigger, scale-value dimensions and simple-toolbar variables no longer exists; these ineffective entries are removed. The toolbar uses preview-color-action-* and preview-padding-action-content; the footer uses existing footer variables. Error/loading layers fill the image without an extra 100px minimum height. Zoom/track transitions use system motion and stop under reduced motion.

### Image-preview group numbering

`modelValue/defaultValue` start at `1`. `open(imageNumber = 1)` and `to(imageNumber)` use the same numbering; invalid/noninteger values are ignored. `prev()/next()` retain this numbering at loop boundaries. Model events are `update:modelValue(imageNumber)`; navigation emits `change(imageNumber, previousImageNumber)`, while external assignments do not. Long press emits `long-press(imageNumber)`; the indicator slot receives `{ imageNumber, length }`. Internal array indices remain zero-based.

Root `class` and `style` merge with the Image wrapper. Use `img-props.class/style` to style the inner image. Preview `open-change` is a Vue notification event: each state transition emits once, `.once` uses Vue event semantics, and returned Promises do not control loading. The typed `onOpenChange` listener uses this same event path.

---

Document: llms/en-US/components/infinite-scroll.md

<!-- Source: src/infinite-scroll/README.en-US.md; locale: en-US; page: /en/components/infinite-scroll/ -->

# Infinite Scroll

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### List

- `status`: Selects the semantic state.

Example source: src/infinite-scroll/__demos__/list.vue

```vue
<template>
  <div ref="scroller" class="infinite-scroll-demo">
    <c-infinite-scroll
      v-model:status="status"
      :target="scroller"
      :bottom-offset="32"
      @load="fetchData"
    >
      <c-list :data="data" :scrollbar="false">
        <template #header>Infinite list</template>
        <template #item="{ item }">
          <c-list-item>{{ item }}</c-list-item>
        </template>
      </c-list>
    </c-infinite-scroll>
  </div>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";

const scroller = ref<HTMLElement>();
const page = ref(0);
const data = ref<string[]>([]);
const status = ref<InfiniteScrollStatus>("idle");
let timer: ReturnType<typeof window.setTimeout> | undefined;

const fetchData = () => {
  window.clearTimeout(timer);
  timer = window.setTimeout(() => {
    timer = undefined;
    const start = data.value.length;
    data.value.push(
      ...Array.from(
        { length: 8 },
        (_, index) => `Cedar list item ${start + index + 1}`,
      ),
    );
    page.value += 1;
    status.value = page.value >= 5 ? "finished" : "idle";
  }, 600);
};
onBeforeUnmount(() => window.clearTimeout(timer));
onDeactivated(() => {
  window.clearTimeout(timer);
  timer = undefined;
  if (status.value === "loading") {
    status.value = "idle";
  }
});
</script>

<style scoped>
.infinite-scroll-demo {
  max-height: 320px;
  overflow-y: auto;
}
</style>
```

## Content and presentation

### Error

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Pagination state; supports `v-model:status` | Error |
| `target` | Scroll container; defaults to the nearest scrolling ancestor | Error |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/infinite-scroll/__demos__/error.vue

```vue
<template>
  <div ref="scroller" class="infinite-scroll-demo">
    <c-infinite-scroll
      v-model:status="status"
      :target="scroller"
      @load="fetchData"
      @retry="fetchData"
    >
      <c-list :data="data" :scrollbar="false">
        <template #item="{ item }">
          <c-list-item>{{ item }}</c-list-item>
        </template>
      </c-list>

      <template #error="{ retry }">
        加载失败，<c-button
          variant="text"
          size="sm"
          status="primary"
          @click="retry"
          >点击重试</c-button
        >
      </template>
    </c-infinite-scroll>
  </div>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";

const scroller = ref<HTMLElement>();
const data = ref<string[]>([]);
const status = ref<InfiniteScrollStatus>("idle");
let failedOnce = false;
let timer: ReturnType<typeof window.setTimeout> | undefined;

const fetchData = () => {
  window.clearTimeout(timer);
  timer = window.setTimeout(() => {
    timer = undefined;
    if (!failedOnce && data.value.length === 8) {
      failedOnce = true;
      status.value = "error";
      return;
    }

    const start = data.value.length;
    data.value.push(
      ...Array.from(
        { length: 8 },
        (_, index) => `Cedar list item ${start + index + 1}`,
      ),
    );
    status.value = data.value.length >= 32 ? "finished" : "idle";
  }, 600);
};
onBeforeUnmount(() => window.clearTimeout(timer));
onDeactivated(() => {
  window.clearTimeout(timer);
  timer = undefined;
  if (status.value === "loading") {
    status.value = "idle";
  }
});
</script>

<style scoped>
.infinite-scroll-demo {
  max-height: 320px;
  overflow-y: auto;
}
</style>
```

## Customization and slots

### Custom Status

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Pagination state; supports `v-model:status` | Custom Status |
| `target` | Scroll container; defaults to the nearest scrolling ancestor | Custom Status |
| `bottom-offset` | Distance-to-bottom threshold; numbers are px, strings are CSS lengths | Custom Status |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/infinite-scroll/__demos__/custom-status.vue

```vue
<template>
  <div ref="scroller" class="infinite-scroll-demo">
    <c-infinite-scroll
      v-model:status="status"
      :target="scroller"
      bottom-offset="2rem"
      @load="fetchData"
    >
      <c-list :data="data" :scrollbar="false">
        <template #item="{ item }">
          <c-list-item>{{ item }}</c-list-item>
        </template>
      </c-list>

      <template #loading>
        <c-space align="center">
          <c-loading />
          正在加载下一页
        </c-space>
      </template>
      <template #finished>全部数据加载完成</template>
    </c-infinite-scroll>
  </div>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";

const scroller = ref<HTMLElement>();
const data = ref<string[]>([]);
const status = ref<InfiniteScrollStatus>("idle");
let timer: ReturnType<typeof window.setTimeout> | undefined;

const fetchData = () => {
  window.clearTimeout(timer);
  timer = window.setTimeout(() => {
    timer = undefined;
    const start = data.value.length;
    data.value.push(
      ...Array.from(
        { length: 8 },
        (_, index) => `Cedar list item ${start + index + 1}`,
      ),
    );
    status.value = data.value.length >= 32 ? "finished" : "idle";
  }, 600);
};
onBeforeUnmount(() => window.clearTimeout(timer));
onDeactivated(() => {
  window.clearTimeout(timer);
  timer = undefined;
  if (status.value === "loading") {
    status.value = "idle";
  }
});
</script>

<style scoped>
.infinite-scroll-demo {
  max-height: 320px;
  overflow-y: auto;
}
</style>
```

## Lifecycle and edge cases

### Scheduler Lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Pagination state; supports `v-model:status` | Scheduler Lifecycle |
| `target` | Scroll container; defaults to the nearest scrolling ancestor | Scheduler Lifecycle |
| `immediate` | Whether to check immediately after mounting and resolving the scroll container | Scheduler Lifecycle |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/infinite-scroll/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { InfiniteScrollStatus } from "@cedar-design/ui";
const first = ref<HTMLElement>();
const second = ref<HTMLElement>();
const alternate = ref(false);
const active = ref(true);
const status = ref<InfiniteScrollStatus>("idle");
const loads = ref(0);
const load = () => {
  loads.value++;
  status.value = "finished";
};
</script>
<template>
  <div>
    <c-button @click="alternate = !alternate"
      >Switch target / 切换目标</c-button
    >
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="status = 'idle'">New status cycle / 新状态循环</c-button>
    <p>
      Loads / 加载次数: {{ loads }}. Old checks must not replay /
      旧检查不能重放。
    </p>
    <div ref="first" style="height: 100px; overflow: auto">
      <div style="height: 300px">Target A</div>
    </div>
    <div ref="second" style="height: 100px; overflow: auto">
      <div style="height: 300px">Target B</div>
    </div>
    <KeepAlive>
      <c-infinite-scroll
        v-if="active"
        v-model:status="status"
        :target="alternate ? second : first"
        :immediate="false"
        @load="load"
      >
        <div>Detector / 触底检测</div>
      </c-infinite-scroll>
    </KeepAlive>
  </div>
</template>
```

## API

### `<infinite-scroll>` Props

| Parameter | Description | Type | Default |
| ------------- | -------------------------------------------------- | ---------------------------------------------- | -------- |
| status | Pagination state; supports `v-model:status` | `'idle' \| 'loading' \| 'error' \| 'finished'` | `'idle'` |
| bottom-offset | Distance-to-bottom threshold; numbers are px, strings are CSS lengths | `string \| number` | `0` |
| immediate | Whether to check immediately after mounting and resolving the scroll container | `boolean` | `true` |
| disabled | Pause loading and retry | `boolean` | `false` |
| target | Scroll container; defaults to the nearest scrolling ancestor | `string \| HTMLElement` | `-` |

### `<infinite-scroll>` Events

| Event | Description | Arguments |
| ------------- | -------------------------- | --------- |
| update:status | Requests pagination status `loading` | `loading` |
| load | Emitted when idle and the threshold is reached | - |
| retry | Emitted when retry is invoked in the error state | - |

`retry` does not also emit `load`. Both events may call the same business request function.

### `<infinite-scroll>` Methods

| Method | Description |
| ------ | ---------------------------- |
| check | Immediately check whether the loading threshold is reached |
| retry | Request a retry in the `error` state |

### `<infinite-scroll>` Slots

| Slot | Description | Arguments |
| -------- | ---------------- | ------------------- |
| default | Observed content | - |
| loading | Pagination loading state | - |
| error | Pagination error state | `retry: () => void` |
| finished | All-pages-loaded state | - |

The default error area retries on click. `finished` is terminal; detection resumes only when the parent resets `status` to `idle`.

### Type definitions

```ts
import type {
  InfiniteScrollInstance,
  InfiniteScrollMethods,
  InfiniteScrollProps,
  InfiniteScrollStatus,
} from "@cedar-design/ui";
```

### Style variables

| Variable | Default |
| ----------------------------------------------- | ----------------------- |
| `--c-infinite-scroll-status-min-height` | `50px` |
| `--c-infinite-scroll-status-padding` | `12px 0` |
| `--c-infinite-scroll-status-color` | `var(--c-color-text-3)` |
| `--c-infinite-scroll-status-font-size` | `var(--c-font-size-md)` |
| `--c-infinite-scroll-loading-gap` | `8px` |
| `--c-infinite-scroll-error-color` | `var(--c-color-danger)` |

---

Document: llms/en-US/components/input-number.md

<!-- Source: src/input-number/README.en-US.md; locale: en-US; page: /en/components/input-number/ -->

# InputNumber

Numeric editing with bounds and formatting.

## Reading direction

The numeric input inherits its source `dir`; step buttons follow reading order. Values, precision and vertical keys retain their meaning: ArrowUp increases and ArrowDown decreases. Neither values nor display strings are reversed.

## Basic examples

### Basic usage

Example source: src/input-number/__demos__/field-basic.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref<number | undefined>(12);
const disabled = ref(false);
const readonly = ref(false);
const clearable = ref(true);
const hint = ref(false);
</script>
<template>
  <div class="number-demo">
    <div class="number-demo__options">
      <c-checkbox v-model="disabled" edit-mode="direct">禁用</c-checkbox>
      <c-checkbox v-model="readonly" edit-mode="direct">只读</c-checkbox>
      <c-checkbox v-model="clearable" edit-mode="direct">可清空</c-checkbox>
      <c-checkbox v-model="hint" edit-mode="direct">浮动提示</c-checkbox>
    </div>
    <c-input-number
      v-model="value"
      :disabled="disabled"
      :readonly="readonly"
      :clearable="clearable"
      :hint="hint"
      placeholder="数量"
    />
    <output>业务数值：{{ value ?? "空值" }}</output>
  </div>
</template>
<style scoped>
.number-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
}
.number-demo__options {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
</style>
```

## Appearance and layout

### Appearance Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                 | Related examples             |
| ------------- | --------------------------------------- | ---------------------------- |
| `size`        | All five sizes implemented; inheritable | Control Sizes, Field Options |
| `variant`     | Field variant; inherits InputGroup      | Control Sizes, Field Options |
| `placeholder` | Placeholder                             | Control Sizes, Field Options |
| `min`         | Minimum                                 | Appearance Lab               |
| `max`         | Maximum                                 | Appearance Lab               |
| `mode`        | Step-button layout                      | Field Modes                  |

<!-- demo-config-notes:end -->

- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/input-number/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(3);
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-input-number
      v-model="value"
      :min="0"
      :max="10"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-input-number>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Control Sizes

- `size`: Controls the component size.
- `variant`: Selects the visual variant.

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### Field Modes

Example source: src/input-number/__demos__/field-modes.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const embed = ref(1)
const button = ref(1)
const input = ref(1)
</script>
<template>
  <div class="number-demo">
    <label>内嵌步进<c-input-number v-model="embed" mode="embed" /></label>
    <label>左右按钮（便于触控）<c-input-number v-model="button" mode="button" /></label>
    <label>纯输入<c-input-number v-model="input" mode="input" /></label>
    <p>按钮可长按；输入框内使用 ↑ / ↓ 步进，Enter 或失焦提交。</p>
  </div>
</template>
<style scoped>
.number-demo, .number-demo label { display: flex; flex-direction: column; gap: 12px; }
</style>
```

### Field Options

- `size`: Controls the component size.
- `variant`: Selects the visual variant.

Example source: src/input-number/__demos__/field-options.vue

```vue
<script setup lang="ts">
const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
const variants = ['outline', 'filled', 'standard'] as const
</script>
<template>
  <div class="number-demo">
    <label v-for="size in sizes" :key="size">{{ size }}<c-input-number :size="size" :default-value="12" /></label>
    <label v-for="variant in variants" :key="variant">{{ variant }}<c-input-number :variant="variant" hint placeholder="金额" :default-value="12" /></label>
  </div>
</template>
<style scoped>
.number-demo, .number-demo label { display: flex; flex-direction: column; gap: 12px; }
</style>
```

## Numeric input and formatting

### Quantity Controls

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                             | Related examples                                   |
| ------------- | --------------------------------------------------- | -------------------------------------------------- |
| `clearable`   | Allow clearing an editable field                    | Quantity Controls, Format Slots, Number Boundaries |
| `mode`        | Step-button layout                                  | Quantity Controls, Format Slots                    |
| `min`         | Minimum                                             | Quantity Controls, Number Boundaries               |
| `max`         | Maximum                                             | Quantity Controls, Number Boundaries               |
| `step`        | Positive finite step; scientific notation supported | Quantity Controls, Number Boundaries               |
| `formatter`   | Display formatting only; does not change the number | Format Slots, Number Boundaries                    |

<!-- demo-config-notes:end -->

- `min`: Sets the lower bound.
- `max`: Sets the upper bound.
- `step`: Controls the allowed increment.
- `disabled`: Prevents user interaction.

Example source: src/input-number/__demos__/quantity-controls.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, ref, shallowRef } from "vue";

const props = defineProps<{ english?: boolean }>();
const value = ref<number | undefined>(2);
const disableInput = ref(true);
const disableIncrement = ref(false);
const disableDecrement = ref(false);
const incrementButton = ref(true);
const decrementButton = ref(true);
const press = ref(true);
const lastStep = ref("—");
const approved = ref<number | undefined>(2);
const blocked = ref(false);
const pending = ref(false);
const status = ref("—");
const decision = shallowRef<((allowed: boolean) => void) | undefined>();
const fail = shallowRef<(() => void) | undefined>();
function beforeCommit(
  { value: next }: { value: unknown },
  _done: (allow?: boolean) => void,
  { signal }: { signal: AbortSignal },
) {
  pending.value = true;
  status.value = props.english
    ? `Waiting to commit ${next ?? "empty"}`
    : `等待提交 ${next ?? "空值"}`;
  return new Promise<void | false>((resolve, reject) => {
    const cleanup = () => {
      signal.removeEventListener("abort", cancel);
      pending.value = false;
      decision.value = undefined;
      fail.value = undefined;
    };
    const cancel = () => {
      cleanup();
      status.value = props.english
        ? "Cancelled; old result ignored"
        : "已取消，旧结果不再生效";
      resolve(false);
    };
    signal.addEventListener("abort", cancel, { once: true });
    decision.value = (allowed) => {
      cleanup();
      status.value = allowed
        ? props.english
          ? "Approved"
          : "已允许"
        : props.english
          ? "Rejected"
          : "已拒绝";
      resolve(allowed ? undefined : false);
    };
    fail.value = () => {
      cleanup();
      status.value = props.english
        ? "Request failed; value preserved"
        : "请求失败，保留原值";
      reject(
        new Error(props.english ? "Quantity request failed" : "数量提交失败"),
      );
    };
  });
}
onBeforeUnmount(() => decision.value?.(false));
</script>

<template>
  <div class="quantity-controls-demo">
    <h4>
      {{
        english ? "Quantity controls and step direction" : "数量控制与步进方向"
      }}
    </h4>
    <c-space wrap>
      <c-checkbox v-model="disableInput" edit-mode="direct">{{
        english ? "Buttons only" : "禁止手输"
      }}</c-checkbox>
      <c-checkbox v-model="disableIncrement" edit-mode="direct">{{
        english ? "Disable increase" : "禁用增加"
      }}</c-checkbox>
      <c-checkbox v-model="disableDecrement" edit-mode="direct">{{
        english ? "Disable decrease" : "禁用减少"
      }}</c-checkbox>
      <c-checkbox v-model="incrementButton" edit-mode="direct">{{
        english ? "Show increase" : "显示增加"
      }}</c-checkbox>
      <c-checkbox v-model="decrementButton" edit-mode="direct">{{
        english ? "Show decrease" : "显示减少"
      }}</c-checkbox>
      <c-checkbox v-model="press" edit-mode="direct">{{
        english ? "Long press" : "开启长按"
      }}</c-checkbox>
    </c-space>
    <c-input-number
      v-model="value"
      edit-mode="direct"
      mode="button"
      aria-label="数量控制示例"
      :disable-input="disableInput"
      :disable-increment="disableIncrement"
      :disable-decrement="disableDecrement"
      :increment-button="incrementButton"
      :decrement-button="decrementButton"
      :press="press"
      :min="0"
      :max="10"
      @step="(next, direction) => (lastStep = `${direction}: ${next}`)"
    />
    <p role="status">
      {{ english ? "Accepted step" : "已接受的步进" }}：{{ lastStep }}
    </p>
    <h4>
      {{
        english
          ? "Approve, reject or cancel an asynchronous commit"
          : "异步允许、拒绝与取消提交"
      }}
    </h4>
    <p>
      {{
        english
          ? "Step, type or clear the value, then choose an approval result below. Pending operations cannot overlap. External updates and disabling cancel the old request."
          : "加减、输入或清空后，在下方手动选择审批结果。等待时不能重复提交；外部回填或禁用会取消旧请求。"
      }}
    </p>
    <c-input-number
      v-model="approved"
      edit-mode="direct"
      mode="button"
      clearable
      aria-label="异步数量示例"
      :before-commit="beforeCommit"
      loading-mode="line"
      :disabled="blocked"
    />
    <c-space wrap>
      <c-button :disabled="!pending" @click="decision?.(true)">{{
        english ? "Approve" : "允许本次变更"
      }}</c-button>
      <c-button :disabled="!pending" @click="decision?.(false)">{{
        english ? "Reject" : "拒绝本次变更"
      }}</c-button>
      <c-button :disabled="!pending" @click="fail?.()">{{
        english ? "Simulate failure" : "模拟失败"
      }}</c-button>
      <c-button @click="approved = 10">{{
        english ? "Set external value to 10" : "外部回填 10"
      }}</c-button>
      <c-button @click="blocked = !blocked">{{
        blocked
          ? english
            ? "Enable"
            : "恢复可用"
          : english
            ? "Disable"
            : "禁用控件"
      }}</c-button>
    </c-space>
    <p role="status">
      {{ status }}；{{ english ? "Committed value" : "已提交值" }}：{{
        approved ?? "—"
      }}
    </p>
  </div>
</template>
```

### Format Slots

Example source: src/input-number/__demos__/format-slots.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref(12);
const formatter = (text: string) => text.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
const parser = (text: string) => text.replace(/,/g, "");
</script>
<template>
  <c-input-number
    v-model="value"
    :formatter="formatter"
    :parser="parser"
    clearable
    mode="button"
  >
    <template #prepend>预算</template>
    <template #prefix>¥</template>
    <template #suffix>元</template>
    <template #append>含税</template>
    <template #plus>＋</template>
    <template #minus>－</template>
    <template #clear-icon="{ clear }"
      ><c-button html-type="button" aria-label="清空金额" @click="clear"
        >×</c-button
      ></template
    >
  </c-input-number>
</template>
```

### Number Boundaries

- `step`: Controls the allowed increment.
- `max`: Sets the upper bound.
- `min`: Sets the lower bound.

Example source: src/input-number/__demos__/number-boundaries.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const tiny = ref(0);
const negative = ref<number>();
const bounded = ref(0.1);
const amount = ref(12);
const formatter = (value: string) => "$" + value;
const parser = (value: string) => value.replace(/^\$/, "");
</script>

<template>
  <div class="number-boundaries-demo">
    <label>
      <span>科学计数法步长：1e-7</span>
      <c-input-number v-model="tiny" :step="1e-7" :precision="0" />
      <output>{{ tiny }}</output>
    </label>
    <label>
      <span>空值开始，最大值为 -1</span>
      <c-input-number v-model="negative" :max="-1" clearable />
      <output>{{ negative ?? "空值" }}</output>
    </label>
    <label>
      <span>边界优先：最大值 0.15，精度 1</span>
      <c-input-number
        v-model="bounded"
        :min="0"
        :max="0.15"
        :step="0.1"
        :precision="1"
      />
      <output>{{ bounded }}</output>
    </label>
    <label>
      <span>格式化展示与业务数字分离</span>
      <c-input-number
        v-model="amount"
        :formatter="formatter"
        :parser="parser"
        model-event="input"
      />
      <output>{{ amount }}</output>
    </label>
  </div>
</template>

<style scoped>
.number-boundaries-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
.number-boundaries-demo label {
  display: flex;
  flex-direction: column;
  gap: 6px;
}
.number-boundaries-demo output {
  font-variant-numeric: tabular-nums;
}
</style>
```

### Empty markers and valid zero

Configure empty-values and empty-value when an API uses -1 for missing data. Initially the input is blank while the model remains -1. Set it to 0 to see a valid zero; clearing returns -1. A second field clears to a valid 0, showing that clear output need not mean missing data.

Example source: src/input-number/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ quantity: -1 as number | null | undefined });
const restored = ref<number | null | undefined>(12);
</script>
<template>
  <c-space direction="column">
    <p>
      -1 means missing and renders blank; 0 remains a valid number. Clearing
      produces -1.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="quantity" label="Quantity">
        <c-input-number
          v-model="model.quantity"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined, -1]"
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-space wrap>
      <c-button @click="model.quantity = 0">Set to 0</c-button>
      <c-button @click="model.quantity = -1">Set to -1</c-button>
    </c-space>
    <p>
      Current model: <output>{{ String(model.quantity) }}</output>
    </p>
    <p>This field clears to 0 without treating 0 as missing.</p>
    <c-form layout="vertical">
      <c-form-item label="Clear restores valid zero">
        <c-input-number
          v-model="restored"
          edit-mode="direct"
          clearable
          :empty-value="0"
        />
        <output>{{ String(restored) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

## Interaction and forms

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                       | Related examples                    |
| ------------- | --------------------------------------------- | ----------------------------------- |
| `disabled`    | Disabled; inherits when omitted               | State Lab, Form Inheritance         |
| `readonly`    | Read-only; allows focus/copy but no mutations | State Lab, Form Inheritance         |
| `clearable`   | Allow clearing an editable field              | Controlled Events, Form Inheritance |
| `min`         | Minimum                                       | State Lab                           |
| `max`         | Maximum                                       | State Lab                           |
| `error`       | Error state; inherits FormItem when omitted   | State Lab                           |

<!-- demo-config-notes:end -->

- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/input-number/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(3);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-input-number
      v-model="value"
      :min="0"
      :max="10"
      v-bind="__demoState"
    ></c-input-number>
  </c-space>
</template>
```

### Controlled Events

Example source: src/input-number/__demos__/controlled-events.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<number | undefined>(1)
const logs = ref<string[]>([])
function log(name: string, next?: number) {
  logs.value = [name + ': ' + (next ?? '空值'), ...logs.value].slice(0, 6)
}
</script>
<template>
  <div class="number-demo">
    <label>父组件接受更新
      <c-input-number v-model="value" clearable model-event="input" @input="(next: number | undefined) => log('input', next)" @update:model-value="(next: number | undefined) => log('update', next)" @change="(next: number | undefined) => log('change', next)" @clear="() => log('clear')" />
    </label>
    <label>固定受控值，父组件不接受更新
      <c-input-number :model-value="5" @update:model-value="(next: number | undefined) => log('rejected', next)" />
    </label>
    <p>第二个输入框允许编辑草稿，提交后恢复为 5。外部回填不会触发用户 change。</p>
    <ol aria-live="polite"><li v-for="(entry, index) in logs" :key="index">{{ entry }}</li></ol>
  </div>
</template>
<style scoped>
.number-demo, .number-demo label { display: flex; flex-direction: column; gap: 12px; }
</style>
```

### Form Inheritance

- `disabled`: Prevents user interaction.
- `readonly`: Displays the current value without allowing edits.
- `size`: Controls the component size.

Example source: src/input-number/__demos__/form-inheritance.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ quantity: 2, editable: 3 });
const disabled = ref(false);
const readonly = ref(false);
</script>
<template>
  <div class="number-demo">
    <c-checkbox v-model="disabled">表单禁用</c-checkbox>
    <c-checkbox v-model="readonly">表单只读</c-checkbox>
    <c-form :model="model" :disabled="disabled" :readonly="readonly" size="lg">
      <c-form-item field="quantity" label="继承状态">
        <c-input-number v-model="model.quantity" clearable />
      </c-form-item>
      <c-form-item field="editable" label="显式覆盖">
        <c-input-number
          v-model="model.editable"
          :disabled="false"
          :readonly="false"
          size="sm"
        />
      </c-form-item>
    </c-form>
  </div>
</template>
<style scoped>
.number-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
}
</style>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Clear output

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

### Props

| Prop          | Description                                                      | Type                            | Default                    |
| ------------- | ---------------------------------------------------------------- | ------------------------------- | -------------------------- |
| model-value   | Controlled number; undefined denotes an empty/uncontrolled value | `number`                        | —                          |
| default-value | Initial uncontrolled value                                       | `number`                        | —                          |
| mode          | Step-button layout                                               | `embed \| button \| input`      | `embed`                    |
| precision     | Decimal places (0–100), at least the step precision              | `number`                        | —                          |
| step          | Positive finite step; scientific notation supported              | `number`                        | `1`                        |
| disabled      | Disabled; inherits when omitted                                  | `boolean`                       | Inherited, otherwise false |
| error         | Error state; inherits FormItem when omitted                      | `boolean`                       | Inherited, otherwise false |
| max           | Maximum                                                          | `number`                        | `Infinity`                 |
| min           | Minimum                                                          | `number`                        | `-Infinity`                |
| formatter     | Display formatting only; does not change the number              | `(text: string) => string`      | —                          |
| parser        | Parse the original text once per edit                            | `(text: string) => string`      | —                          |
| placeholder   | Placeholder                                                      | `string`                        | —                          |
| size          | All five sizes implemented; inheritable                          | `xs \| sm \| md \| lg \| xl`    | Inherited, otherwise md    |
| variant       | Field variant; inherits InputGroup                               | `outline \| filled \| standard` | `outline`                  |
| hint          | Floating hint; inherits InputGroup / FieldDecorator              | `boolean`                       | Library default            |
| clearable     | Allow clearing an editable field                                 | `boolean`                       | `false`                    |
| model-event   | Model update timing; change only reports commits                 | `change \| input`               | `change`                   |
| readonly      | Read-only; allows focus/copy but no mutations                    | `boolean`                       | Inherited, otherwise false |
| input-attrs   | Additional native input attributes                               | `Record<string, unknown>`       | —                          |

### Events

| Event              | Arguments                                                  | Description                                                      |
| ------------------ | ---------------------------------------------------------- | ---------------------------------------------------------------- |
| input              | `(value: number \| undefined, text: string, event: Event)` | Parsed value and display text while editing                      |
| update:model-value | `(value: number \| undefined)`                             | Proposed model update                                            |
| change             | `(value: number \| undefined, event: Event)`               | Commit, step or clear                                            |
| clear              | `(event: Event)`                                           | Explicit clear                                                   |
| focus              | `(event: FocusEvent)`                                      | Focus                                                            |
| blur               | `(event: FocusEvent)`                                      | Blur                                                             |
| keydown            | `(event: KeyboardEvent)`                                   | Native keyboard event; preventDefault intercepts default actions |

### Slots

| Slot             | Arguments                            | Description         |
| ---------------- | ------------------------------------ | ------------------- |
| prefix / suffix  | —                                    | Inside the field    |
| prepend / append | —                                    | Outside the field   |
| plus / minus     | —                                    | Step-button icons   |
| clear-icon       | `{ clear: (event?: Event) => void }` | Custom clear button |

### Methods

| Method / property | Type                               | Description                       |
| ----------------- | ---------------------------------- | --------------------------------- |
| focus             | `(options?: FocusOptions) => void` | Focus; ineffective while disabled |
| blur              | `() => void`                       | Blur                              |
| select            | `() => void`                       | Select all text                   |
| inputRef          | `HTMLInputElement \| undefined`    | Native input element              |

## Type definitions / Types

```ts
import type {
  InputNumberProps,
  InputNumberInstance,
  InputNumberMode,
  InputNumberModelEvent,
  InputNumberSize,
  InputNumberVariant,
  InputNumberFormatter,
  InputNumberParser,
} from "@cedar-design/ui";
```

## Style variables

| Token                                              | Default                                |
| -------------------------------------------------- | -------------------------------------- |
| `--c-input-number-step-button-width`               | `var(--c-sys-control-height-md)`       |
| `--c-input-number-step-button-color`               | `var(--c-sys-color-content-secondary)` |
| `--c-input-number-step-button-disabled-color`      | `var(--c-sys-color-content-disabled)`  |
| `--c-input-number-step-button-border-color`        | `var(--c-sys-color-border-subtle)`     |
| `--c-input-number-step-button-background`          | `var(--c-sys-color-surface-muted)`     |
| `--c-input-number-step-button-hover-background`    | `var(--c-sys-color-state-hover)`       |
| `--c-input-number-step-button-active-background`   | `var(--c-sys-color-state-selected)`    |
| `--c-input-number-step-button-icon-size`           | `14px`                                 |
| `--c-input-number-step-button-transition-duration` | `0.2s`                                 |
| `--c-input-number-addon-background`                | `var(--c-sys-color-surface-muted)`     |
| `--c-input-number-addon-color`                     | `var(--c-sys-color-content-primary)`   |
| `--c-input-number-addon-border-color`              | `var(--c-sys-color-border-default)`    |
| `--c-input-number-border-width`                    | `1px`                                  |
| `--c-input-number-border-radius`                   | `var(--c-field-border-radius)`         |
| `--c-input-number-size-xs-step-button-width`       | `var(--c-sys-control-height-xs)`       |
| `--c-input-number-size-sm-step-button-width`       | `var(--c-sys-control-height-sm)`       |
| `--c-input-number-size-md-step-button-width`       | `var(--c-sys-control-height-md)`       |
| `--c-input-number-size-lg-step-button-width`       | `var(--c-sys-control-height-lg)`       |
| `--c-input-number-size-xl-step-button-width`       | `var(--c-sys-control-height-xl)`       |

Old `--c-field-number-*` tokens are removed in favor of `--c-input-number-*`, without aliases. Shared field appearance still uses FieldDecorator `--c-field-*` tokens.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`--c-field-caret-color` sets the shared caret color, defaulting to `currentColor`. `--c-input-number-caret-color` overrides this component and defaults to `var(--c-field-caret-color)`.

An explicit beforeCommit wait uses the existing loadingMode indicator and native aria-busy. Manual loading remains independent and does not implicitly make the input readonly; the beforeCommit guard owns its existing input lock. Returned change/step notification Promises do not control waiting.

---

Document: llms/en-US/components/input-tag.md

<!-- Source: src/input-tag/README.en-US.md; locale: en-US; page: /en/components/input-tag/ -->

# InputTag

Editable tag values with controlled array models.

## Reading direction

Tags follow reading order while their source array stays unchanged. With empty input, Backspace removes the last closable value; Enter adds a tag. Composition does not submit or delete tags.

## Basic examples

### Basic usage

Example source: src/input-tag/__demos__/basic.vue

```vue
<template>
  <c-input-tag :default-value="['test']" placeholder="Please Enter" clearable />
</template>
```

## Appearance and states

### Tag input size and state

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                            | Related examples         |
| --------------- | ---------------------------------- | ------------------------ |
| `default-value` | Default value (uncontrolled state) | Tag input size and state |
| `placeholder`   | Placeholder                        | Tag input size and state |
| `size`          | The size of the input              | Tag input size and state |
| `clearable`     | Enables the clear action           | Tag input size and state |
| `disabled`      | Whether disabled                   | Tag input size and state |
| `readonly`      | Whether it is read-only mode       | Tag input size and state |

<!-- demo-config-notes:end -->

Compare sizes and disabled, read-only or error appearance while keeping the empty-value protocol separate.

Example source: src/input-tag/__demos__/appearance-state-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const size = ref('md')
return { size }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">输入框尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" size="lg">
        <c-radio-group type="button" v-model="scene1.size">
          <c-radio value="xs">xs</c-radio>
          <c-radio value="sm">sm</c-radio>
          <c-radio value="md">md</c-radio>
          <c-radio value="lg">lg</c-radio>
          <c-radio value="xl">xl</c-radio>
        </c-radio-group>
        <c-input-tag :default-value="['one']" placeholder="Please enter something" :size="scene1.size" clearable />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="status">
    <h4><span lang="zh-CN">输入框状态</span><span lang="en-US">status</span></h4>
    <c-space direction="column" size="lg">
        <c-input-tag :default-value="['test']" placeholder="Please Enter" disabled />
        <c-input-tag :default-value="['test']" placeholder="Please Enter" readonly />
        <c-input-tag :default-value="['test']" placeholder="Please Enter" error />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Content and presentation

### Max

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                   | Related examples |
| --------------- | --------------------------------------------------------- | ---------------- |
| `default-value` | Default value (uncontrolled state)                        | Max              |
| `placeholder`   | Placeholder                                               | Max              |
| `max-tag-count` | The maximum number of tags displayed, `0` means unlimited | Max              |
| `clearable`     | Enables the clear action                                  | Max              |

<!-- demo-config-notes:end -->

- `default-value`: Default value (uncontrolled state)
- `placeholder`: Placeholder
- `max-tag-count`: The maximum number of tags displayed, `0` means unlimited
- `clearable`: Whether to allow clear

Example source: src/input-tag/__demos__/max.vue

```vue
<template>
  <c-input-tag
    :default-value="['one', 'two', 'three', 'four']"
    placeholder="Please Enter"
    :max-tag-count="3"
    clearable
  />
</template>
```

## Loading and waiting

### Controlled loading

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `loading` | Explicit business loading state | `boolean` | `false` |


Set loading explicitly to display feedback. Ordinary event return values do not drive loading. Before hooks retain their documented pending behavior.

Example source: src/input-tag/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const loading = ref(true)
</script>
<template>
  <c-space direction="column" style="width: 100%" :size="16">
    <c-form layout="vertical"><c-form-item label="加载状态 / Loading"><c-switch v-model="loading" /></c-form-item></c-form>
    <c-input-tag :loading="loading" :default-value="['示例 / Example']" />
    <p>通过 loading 显式控制等待展示，普通事件返回 Promise 不会自动加载。Loading is controlled by business state.</p>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### `<input-tag>` Props

| Parameter                 | Description                                               | Type                                              |  Default   |
| ------------------------- | --------------------------------------------------------- | ------------------------------------------------- | :--------: |
| model-value **(v-model)** | Bound value                                               | `(string \| number \| TagData)[]`                 |    `-`     |
| default-value             | Default value (uncontrolled state)                        | `(string \| number \| TagData)[]`                 |    `[]`    |
| input-value **(v-model)** | The value of the input                                    | `string`                                          |    `-`     |
| default-input-value       | The default value of the input (uncontrolled state)       | `string`                                          |    `''`    |
| placeholder               | Placeholder                                               | `string`                                          |    `-`     |
| disabled                  | Whether disabled                                          | `boolean`                                         |  `false`   |
| error                     | Whether it is an error state                              | `boolean`                                         |  `false`   |
| readonly                  | Whether it is read-only mode                              | `boolean`                                         |  `false`   |
| clearable                 | Enables the clear action                                  | `boolean`                                         |  `false`   |
| size                      | The size of the input                                     | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`            |   `'md'`   |
| variant                   | The variant of the input                                  | `'filled' \| 'outline' \| 'standard'`             | `'filled'` |
| max-tag-count             | The maximum number of tags displayed, `0` means unlimited | `number`                                          |    `0`     |
| retain-input-value        | Whether to keep the content of the input box              | `boolean \| { create?: boolean; blur?: boolean }` |  `false`   |
| format-tag                | Format tag content                                        | `(data: TagData) => string`                       |    `-`     |
| unique-value              | Whether to create only unique values                      | `boolean`                                         |  `false`   |
| field-names               | Customize fields in `TagData`                             | `InputTagFieldNames`                              |    `-`     |
| tag-nowrap                | Tag content does not wrap                                 | `boolean`                                         |  `false`   |

### `<input-tag>` Events

| Event              | Description                                   | Arguments                                               |
| ------------------ | --------------------------------------------- | ------------------------------------------------------- |
| change             | Emitted when the value changes                | value: `(string \| number \| TagData)[]`<br>ev: `Event` |
| input-value-change | Emitted when the input value changes          | inputValue: `string`<br>ev: `Event`                     |
| press-enter        | Emitted when Enter is pressed                 | inputValue: `string`<br>ev: `KeyboardEvent`             |
| remove             | Emitted when a tag's remove button is clicked | removed: `string \| number`<br>ev: `Event`              |
| clear              | Emitted when the clear button is clicked      | ev: `MouseEvent`                                        |
| focus              | Emitted when the input gains focus            | ev: `FocusEvent`                                        |
| blur               | Emitted when the input loses focus            | ev: `FocusEvent`                                        |

### `<input-tag>` Methods

| Method | Description     | Arguments | Returns |
| ------ | --------------- | --------- | ------- |
| focus  | Focus the input | -         | -       |
| blur   | Blur the input  | -         | -       |

### `<input-tag>` Slots

| Slot   |         Description         | Arguments       |
| ------ | :-------------------------: | --------------- |
| tag    | Displayed input-tag content | data: `TagData` |
| prefix |       Prefix content        | -               |
| suffix |       Suffix content        | -               |

### TagData

| Parameter | Description      | Type               | Default |
| --------- | ---------------- | ------------------ | :-----: |
| value     | Tag value        | `string \| number` |   `-`   |
| label     | Tag content      | `string`           |   `-`   |
| closable  | Whether closable | `boolean`          | `false` |
| tagProps  | Tag props        | `TagProps`         |   `-`   |

### Type definitions

The component exports the following types

```ts
import type { InputTagInstance } from "@cedar-design/ui";
```

## Removing legacy InputTag icon references

Cedar InputTag embeds Tag's actual close-btn and renders no old c-icon-hover pseudo-element. The old mixin import, default/focus pseudo-element backgrounds and duplicate custom Tag text rules are removed; Tag owns its text. Existing close-button appearance, click removal and readonly/disabled behavior remain, without a new hover background.

Both libraries remove tag-custom-icon-bg-hover; Cedar also removes input-tag-tag-remove-icon-color-bg / input-tag-tag-remove-icon-color-bg-focus. Unused variables have no replacements; remove ineffective overrides. No aliases remain. Maple has no InputTag component and only synchronizes shared Tag-variable cleanup.

The former cross-component exemptions are closed. check:token-consumers checks 414 Badge/Tag declarations without exemptions and compiles InputTag to prevent legacy icon selectors/variables returning. Integration tests cover actual DOM, close interactions and custom colors. The 553 shared defaults are unchanged because removed shared variables previously registered names only. This does not claim complete InputTag token, browser-visual or keyboard governance.

## InputTag wrapper and content responsibilities

FieldDecorator owns InputTag outline / filled / standard wrappers. Form must not redraw backgrounds, borders or focus shadows; old Form overrides for obsolete InputTag state classes are removed, while validation messages remain. filled default/hover/focus still use FieldDecorator fill-1 / fill-2 / fill-3.

input-tag-* controls content density, default tag backgrounds and disabled text. Selectors match actual c-field-decorator--size-* / --focus / --disabled classes rather than nonexistent old InputTag classes; disabled overrides focus. All xs/sm/md/lg/xl sizes are covered. xl uses 32px tags, 16px input text and 4px vertical padding.

Removed 33 unused wrapper variables: size-{xs,sm,md,lg}-height; color-text-error; color-placeholder, color-icon-clear, color-icon-clear-bg-hover; color-border-{default,error,disabled} and -hover/-focus forms; color-bg-{default,error}, their -hover/-focus forms, color-bg-disabled and its -hover form; color-shadow-{default,error}-focus; size-shadow-{default,error}-focus; border-radius, border-width, size-icon-clear and size-icon-clear-hover. All use --c-input-tag-. No compatibility aliases remain.

Migrate by responsibility: field-variant-{variant}-background for wrapper backgrounds; field-border-radius for corners; field-placeholder-text-color for placeholders; field-clear-icon-color / field-clear-icon-size for clear icons. Prefer size for geometry; do not override internal variables. Unused legacy variables have no one-to-one replacement. Tag content uses the InputTag variables below.

InputTag retains 27 content variables in unused-consumer checks. Both libraries’ Badge/Tag plus Cedar InputTag cover 441 declarations and 80 size/focus/disabled cascades. The shared-default contract remains 553 entries; Cedar-only InputTag is not a cross-platform shared component. Default text, disabled text, tag backgrounds and focused backgrounds use content-primary, content-disabled, surface-default and state-hover. Disabled restyles neutral tags only, preserving explicit color/status; business themes own custom-color contrast. Parent disabled/readonly overrides tagProps.closable/checkable. Loading or explicitly nonclosable tags cannot be removed with Backspace. Cedar spot checks cover five sizes, xl input/keyboard removal, light/dark modes and disabled custom colors, not a complete visual audit.

### Current content variables

| Variable                                  | Default                               |
| ----------------------------------------- | ------------------------------------- |
| `--c-input-tag-size-xs-tag-height`        | `20px`                                |
| `--c-input-tag-size-sm-tag-height`        | `20px`                                |
| `--c-input-tag-size-md-tag-height`        | `24px`                                |
| `--c-input-tag-size-lg-tag-height`        | `28px`                                |
| `--c-input-tag-size-xl-tag-height`        | `32px`                                |
| `--c-input-tag-size-xs-font-size`         | `12px`                                |
| `--c-input-tag-size-sm-font-size`         | `14px`                                |
| `--c-input-tag-size-md-font-size`         | `14px`                                |
| `--c-input-tag-size-lg-font-size`         | `14px`                                |
| `--c-input-tag-size-xl-font-size`         | `16px`                                |
| `--c-input-tag-color-text-default`        | `var(--c-sys-color-content-primary)`  |
| `--c-input-tag-color-text-disabled`       | `var(--c-sys-color-content-disabled)` |
| `--c-input-tag-tag-margin-right`          | `4px`                                 |
| `--c-input-tag-tag-margin-y`              | `2px`                                 |
| `--c-input-tag-padding-x`                 | `4px`                                 |
| `--c-input-tag-size-xs-padding-y`         | `0px`                                 |
| `--c-input-tag-size-sm-padding-y`         | `2px`                                 |
| `--c-input-tag-size-md-padding-y`         | `2px`                                 |
| `--c-input-tag-size-lg-padding-y`         | `2px`                                 |
| `--c-input-tag-size-xl-padding-y`         | `4px`                                 |
| `--c-input-tag-tag-font-size`             | `12px`                                |
| `--c-input-tag-tag-color-bg`              | `var(--c-sys-color-surface-default)`  |
| `--c-input-tag-tag-color-bg-focus`        | `var(--c-sys-color-state-hover)`      |
| `--c-input-tag-tag-color-bg-disabled`     | `var(--c-sys-color-state-hover)`      |
| `--c-input-tag-tag-color-border`          | `var(--c-color-fill-3)`               |
| `--c-input-tag-tag-color-border-disabled` | `var(--c-color-fill-3)`               |
| `--c-input-tag-tag-color-border-focus`    | `var(--c-sys-color-state-hover)`      |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/input.md

<!-- Source: src/input/README.en-US.md; locale: en-US; page: /en/components/input/ -->

# Input

Text input with controlled and uncontrolled values.

## Reading direction

The input inherits `dir` from its page or local scope. Affixes, clear actions and input groups follow reading order. Runtime changes retain the native editor, focus and selection; the browser handles caret movement, mixed text and composition without swapping editing keys. Parent rerenders preserve the native composition buffer; older selection-restoration tasks do not overwrite a newer composition.

## Basic examples

### Control Sizes

- `size`: Controls the component size.
- `variant`: Selects the visual variant.

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

Example source: src/input/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-input placeholder="请输入1" clearable variant="outline" />
    <c-input placeholder="请输入1" clearable variant="filled" />
  </c-space>
</template>
```

## Appearance and states

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                  | Related examples             |
| ------------- | ---------------------------------------- | ---------------------------- |
| `placeholder` | Hint text                                | Form Feedback, Floating Hint |
| `hint`        | Whether hint text floats                 | Form Feedback, Floating Hint |
| `clearable`   | Whether to allow the input to be cleared | Form Feedback, Floating Hint |
| `variant`     | Field appearance                         | Floating Hint                |

<!-- demo-config-notes:end -->

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/input/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("示例内容");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-input v-model="value" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"></c-input>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Form Feedback

Example source: src/input/__demos__/form-feedback.vue

```vue
<template>
  <c-form :model="model">
    <c-form-item field="account" label="账户" feedback :validate-status="status" :help="status === 'error' ? '请输入账户后重试' : undefined">
      <c-input v-model="model.account" placeholder="外置标签会关闭内部浮动提示" hint clearable />
    </c-form-item>
    <c-button status="primary" :loading="status === 'validating'" @click="validate">模拟异步校验</c-button>
  </c-form>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue'

const model = reactive({ account: '' })
const status = ref<'validating' | 'success' | 'error'>()
let request = 0
async function validate() {
  const current = ++request
  const value = model.account
  status.value = 'validating'
  await new Promise((resolve) => setTimeout(resolve, 500))
  if (current === request) status.value = value.trim() ? 'success' : 'error'
}
</script>
```

### Floating Hint

- `variant`: Selects the visual variant.

Example source: src/input/__demos__/floating-hint.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-input v-model="name" hint placeholder="姓名" clearable />
    <c-input v-model="email" hint variant="standard" placeholder="邮箱" />
    <c-input v-model="phone" hint placeholder="带前缀的电话" clearable><template #prefix>+86</template></c-input>
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const name = ref('')
const email = ref('')
const phone = ref('')
</script>
```

## Input content and layout

### Word Limit

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                                                          | Related examples                |
| ----------------- | -------------------------------------------------------------------------------- | ------------------------------- |
| `placeholder`     | Hint text                                                                        | Word Limit, Prefix, Group       |
| `clearable`       | Whether to allow the input to be cleared                                         | Word Limit, Prefix, Group State |
| `max-length`      | Maximum input length                                                             | Word Limit                      |
| `show-word-limit` | Show the character counter                                                       | Word Limit                      |
| `default-value`   | Uncontrolled initial value; read only at creation, never written into the parent | Group State                     |
| `disabled`        | Disabled state; can inherit from Form                                            | Group State                     |

<!-- demo-config-notes:end -->

Example source: src/input/__demos__/word-limit.vue

```vue
<template>
  <c-space direction="column">
    <c-input v-model="normalValue" :max-length="10" clearable show-word-limit placeholder="超出后截断" />
    <c-input
      v-model="errorOnlyValue"
      :max-length="{ length: 6, errorOnly: true }"
      show-word-limit
      placeholder="允许超出，但标记错误"
    />
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const normalValue = ref('Cedar')
const errorOnlyValue = ref('超过六个字符后显示错误')
</script>
```

### Password

Example source: src/input/__demos__/password.vue

```vue
<template>
  <c-space direction="column">
    <c-input-password />
  </c-space>
</template>
```

### Prefix

Example source: src/input/__demos__/prefix.vue

```vue
<template>
  <c-space direction="column">
    <c-input :style="{ width: '320px' }" placeholder="请输入">
      <template #prefix> +86 </template>
    </c-input>
    <c-input :style="{ width: '320px' }" placeholder="请输入">
      <template #suffix> RMB </template>
    </c-input>
    <c-input
      v-model="clearableValue"
      :style="{ width: '320px' }"
      clearable
      placeholder="自定义清除图标"
    >
      <template #clear-icon="{ clear }">
        <c-button
          html-type="button"
          class="prefix-demo__clear"
          aria-label="清空"
          @click="clear"
          >清空</c-button
        >
      </template>
    </c-input>
  </c-space>
</template>

<script setup lang="ts">
import { ref } from "vue";

const clearableValue = ref("Cedar");
</script>

<style scoped>
.prefix-demo__clear {
  border: 0;
  background: transparent;
  color: var(--color-text-2);
  cursor: pointer;
  font-size: 12px;
}
</style>
```

### Group

Example source: src/input/__demos__/group.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group v-model="variant">
      <c-radio value="filled">filled</c-radio>
      <c-radio value="outline">outline</c-radio>
      <c-radio value="standard">standard</c-radio>
    </c-radio-group>
    <c-input-group :variant="variant">
      <c-input :style="{ width: '160px' }" placeholder="first" />
      <c-input :style="{ width: '320px' }" placeholder="second" />
    </c-input-group>
    <c-input-group :variant="variant">
      <c-select :options="['Option1', 'Option2', 'Option3']" :style="{ width: '160px' }" placeholder="first" />
      <c-input :style="{ width: '320px' }" placeholder="second" />
    </c-input-group>

    <c-input-group :variant="variant">
      <c-select :options="['Option1', 'Option2', 'Option3']" :style="{ width: '160px' }" placeholder="first" />
      <c-auto-complete :style="{ width: '320px' }" placeholder="second" />
    </c-input-group>
    <c-input-group :variant="variant">
      <c-input-group-label>text</c-input-group-label>
      <c-input :style="{ width: '320px' }" placeholder="second" />
      <c-button status="primary">label</c-button>
    </c-input-group>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const variant = ref('filled')
</script>
```

### Group State

- `disabled`: Prevents user interaction.
- `readonly`: Displays the current value without allowing edits.

Example source: src/input/__demos__/group-state.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-space>
      <c-button variant="outline" @click="disabled = !disabled">{{ disabled ? '启用组合' : '禁用组合' }}</c-button>
      <c-button variant="outline" @click="readonly = !readonly">{{ readonly ? '允许编辑' : '组合只读' }}</c-button>
    </c-space>
    <c-input-group variant="outline" :disabled="disabled" :readonly="readonly" :hint="false">
      <c-input-group-label>https://</c-input-group-label>
      <c-input v-model="domain" placeholder="输入域名" clearable />
      <c-input-group-label>.com</c-input-group-label>
    </c-input-group>
    <c-input-group variant="filled" :disabled="disabled" :readonly="readonly" :hint="false">
      <c-input v-model="first" placeholder="继承组合状态" clearable />
      <c-input default-value="可独立编辑" :disabled="false" :readonly="false" clearable />
    </c-input-group>
    <c-input-group size="lg" variant="outline" :disabled="disabled" :readonly="readonly" :hint="false">
      <c-input-group-label>密码</c-input-group-label>
      <c-input-password v-model="password" placeholder="密码切换继承禁用状态" clearable />
    </c-input-group>
  </c-space>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const disabled = ref(false)
const readonly = ref(false)
const domain = ref('example')
const first = ref('继承状态')
const password = ref('CedarMaple')
</script>
```

## Value model and interaction

### Default Value

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                          | Related examples             |
| --------------- | -------------------------------------------------------------------------------- | ---------------------------- |
| `clearable`     | Whether to allow the input to be cleared                                         | Event Pipeline, TypeScript   |
| `default-value` | Uncontrolled initial value; read only at creation, never written into the parent | Default Value                |
| `aria-label`    | Native input accessible label                                                    | Default Value                |
| `disabled`      | Disabled state; can inherit from Form                                            | Interaction state comparison |
| `readonly`      | Readonly state; can inherit from Form                                            | Interaction state comparison |
| `error`         | Error state; can inherit from FormItem                                           | Interaction state comparison |

<!-- demo-config-notes:end -->

Example source: src/input/__demos__/default-value.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

withDefaults(defineProps<{ english?: boolean }>(), { english: false })
const seed = ref('A: initial text')
const instanceKey = ref(0)
const lastUpdate = ref<string | null>(null)
const updateCount = ref(0)
const controlled = ref('')
function record(value: string) {
  lastUpdate.value = value
  updateCount.value += 1
}
function remount() {
  instanceKey.value += 1
  lastUpdate.value = null
  updateCount.value = 0
}
</script>

<template>
  <div>
    <p>
      {{
        english
          ? '1. Uncontrolled: defaultValue supplies the initial text. Typing updates the component itself; the seed below stays unchanged.'
          : '1. 非受控：defaultValue 提供初始文字。输入后由组件自己保存新值，下方的默认值变量不会随之变化。'
      }}
    </p>
    <c-input :key="instanceKey" :default-value="seed" aria-label="Uncontrolled input" @update:model-value="record" />
    <p>
      defaultValue = <code>{{ seed }}</code>
    </p>
    <p role="status">
      update:modelValue × {{ updateCount }}; {{ english ? 'last emitted value' : '最近一次用户更新' }} =
      <code>{{ lastUpdate === null ? (english ? '(none)' : '（尚未触发）') : JSON.stringify(lastUpdate) }}</code>
    </p>
    <c-space wrap>
      <c-button @click="seed = seed.startsWith('A:') ? 'B: new default' : 'A: initial text'">{{
        english ? 'Change defaultValue only' : '仅修改 defaultValue'
      }}</c-button>
      <c-button @click="remount">{{ english ? 'Remount input' : '重新挂载输入框' }}</c-button>
    </c-space>
    <p>
      {{
        english
          ? 'Try typing, then change defaultValue: the current text stays. Remount to read the latest defaultValue. Initialization never emits update:modelValue.'
          : '操作顺序：先输入，再修改 defaultValue，当前文字不会被覆盖；点击重新挂载后，才读取最新的默认值。初始化不会触发 update:modelValue。'
      }}
    </p>
    <p>
      {{
        english
          ? '2. Controlled: v-model is the source of truth. Its initial empty string takes precedence over defaultValue.'
          : '2. 受控：v-model 是数据来源。这里初始值为空字符串，仍优先于 defaultValue，不会自动填入默认文字。'
      }}
    </p>
    <c-input v-model="controlled" default-value="This default is ignored" aria-label="Controlled input" />
    <p role="status">
      v-model = <code>{{ JSON.stringify(controlled) }}</code>
    </p>
    <c-space wrap>
      <c-button @click="controlled = 'Parent supplied text'">{{
        english ? 'Update parent value' : '从父级设置值'
      }}</c-button>
      <c-button @click="controlled = ''">{{ english ? 'Clear parent value' : '清空父级值' }}</c-button>
    </c-space>
    <p>
      {{
        english
          ? 'For a form, initialize the bound field in the parent. defaultValue does not write an initial value into the parent form.'
          : '表单需要初始值时，请初始化父级绑定字段。defaultValue 不会把初始值写入父级表单。'
      }}
    </p>
  </div>
</template>
```

### Clear icon and manual deletion

Set clear output to null. Clear with the icon, restore the initial value, then delete all text with Backspace. The model shows null for the icon and an empty string for manual deletion.

Example source: src/input/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive } from "vue";
const model = reactive({ text: "Hello" as string | null });
</script>
<template>
  <c-space direction="column">
    <p>
      The clear icon produces null; Backspace to empty produces an empty string.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="text" label="Keyword">
        <c-input
          v-model="model.text"
          edit-mode="direct"
          clearable
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.text = 'Hello'">Restore initial value</c-button>
    <p>
      Current model: <output>{{ JSON.stringify(model.text) }}</output>
    </p>
  </c-space>
</template>
```

### Interaction state comparison

Toggle the state, interact with the component, and restore editing using the controls outside the specimen. Error appearance alone does not run validation.

Example source: src/input/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("示例内容");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-input v-model="value" v-bind="__demoState"></c-input>
  </c-space>
</template>
```

### Event Pipeline

Example source: src/input/__demos__/event-pipeline.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('可编辑内容')
const events = ref<string[]>([])
const record = (name: string) => { events.value = [...events.value.slice(-7), name] }
</script>
<template>
  <div class="input-pipeline-demo">
    <c-input v-model="value" clearable placeholder="输入后尝试清空" @clear="record('clear')" @input="record('input')" @update:model-value="record('update:modelValue')" @change="record('change')" />
    <p>输入：input → update；清空：clear → input → update → change。</p>
    <output>{{ events.join(' → ') || '等待操作' }}</output>
  </div>
</template>
<style scoped>
.input-pipeline-demo { display: flex; flex-direction: column; gap: 12px; }
.input-pipeline-demo p { margin: 0; }
</style>
```

### Commit approval

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes null unchanged; omitted values preserve the existing default. Editors render null as blank without converting ordinary empty-string input to null. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

Example source: src/input/__demos__/en-US/commit-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const value = ref<string | null>("Project A");
const message = ref("");
async function beforeCommit(
  { value: next, previousValue }: { value: unknown; previousValue: unknown },
  _done: (allow?: boolean) => void,
  { signal }: { signal: AbortSignal },
) {
  if (next === previousValue) return true;
  await new Promise((resolve) => setTimeout(resolve, 500));
  if (signal.aborted) return false;
  message.value = `Saved: ${String(next)}`;
  return true;
}
</script>
<template>
  <c-space direction="column">
    <c-input
      v-model="value"
      edit-mode="click"
      clearable
      :empty-value="null"
      :before-commit="beforeCommit"
    />
    <p role="status">{{ message }}</p>
  </c-space>
</template>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## Loading and waiting

### Loading

Toggle loading to compare the default indicator and bottom line. The input remains editable while loading.

Example source: src/input/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const busy = ref(true)
const value = ref('加载时仍可编辑')
</script>
<template>
  <c-space direction="column" :size="16" style="width: 100%">
    <c-form layout="vertical">
      <c-form-item label="加载状态 / Loading"><c-switch v-model="busy" /></c-form-item>
      <c-form-item label="默认指示器 / Default"><c-input v-model="value" :loading="busy" placeholder="加载时仍可编辑 / Editable while loading" loading-mode="default" /></c-form-item>
      <c-form-item label="底部加载线 / Line"><c-input v-model="value" :loading="busy" placeholder="加载时仍可编辑 / Editable while loading" loading-mode="line" /></c-form-item>
    </c-form>
    <p>切换加载状态；加载时仍可输入和清空。Loading keeps the input editable.</p>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### `<Input>` Props

| Parameter                 | Description                                                                       | Type                                                |   Default   |
| ------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------- | :---------: |
| model-value **(v-model)** | Bound value                                                                       | `string \| null`                                    |     `-`     |
| `loading` | Loading presentation; keeps the input editable | `boolean` | `false` |
| `loading-mode` | Loading layout: default indicator or bottom line | `default / line` | `default` |
| model-modifiers           | `v-model` modifiers; supports `trim`                                              | `{ trim?: boolean }`                                |    `{}`     |
| default-value             | Uncontrolled initial value; read only at creation, never written into the parent  | `string`                                            |    `''`     |
| variant                   | Field appearance                                                                  | `'filled' \| 'outline' \| 'standard'`               | `'outline'` |
| size                      | Input size                                                                        | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`              |   `'md'`    |
| clearable                 | Whether to allow the input to be cleared                                          | `boolean`                                           |   `false`   |
| empty-value               | Clear output; omission clears to an empty string and manual deletion is unchanged | `string \| null \| (() => string \| null)`          | `undefined` |
| disabled                  | Disabled state; can inherit from Form                                             | `boolean`                                           |     `-`     |
| readonly                  | Readonly state; can inherit from Form                                             | `boolean`                                           |     `-`     |
| error                     | Error state; can inherit from FormItem                                            | `boolean`                                           |     `-`     |
| placeholder               | Hint text                                                                         | `string`                                            |     `-`     |
| hint                      | Whether hint text floats                                                          | `boolean`                                           |   `false`   |
| line                      | Whether to draw a border or underline                                             | `boolean`                                           |   `true`    |
| text-color                | Input text color                                                                  | `string`                                            |     `-`     |
| focus-color               | Focused hint and supported border colors; does not control the caret              | `string`                                            |     `-`     |
| blur-color                | Unfocused hint color                                                              | `string`                                            |     `-`     |
| aria-label                | Native input accessible label                                                     | `string`                                            |     `-`     |
| autofocus                 | Focus automatically after mount                                                   | `boolean`                                           |   `false`   |
| enterkeyhint              | Mobile virtual-keyboard enter-key hint                                            | `string`                                            |     `-`     |
| max-length                | Maximum input length                                                              | `number \| { length: number; errorOnly?: boolean }` |     `0`     |
| show-word-limit           | Show the character counter                                                        | `boolean`                                           |   `false`   |
| word-length               | Length-counting function                                                          | `(value: string) => number`                         |     `-`     |
| word-slice                | Text-slicing function, used with wordLength                                       | `(value: string, maxLength: number) => string`      |     `-`     |
| input-attrs               | Attributes for the internal input element                                         | `object`                                            |     `-`     |

`disabled / readonly / size` resolve from child → InputGroup → FormItem/Form → library defaults; Cedar size also supports ConfigProvider. `clearable` applies only to nonempty editable inputs: PC shows it on hover/focus, while touch devices and Maple keep it visible. Native name/id/aria-_/data-_ reach the input; class/style stay on the wrapper. `input-attrs` cannot override controlled value, type, disabled/readonly state or length policy.

### `<Input>` Events

| Event       | Description                                   | Arguments                      |
| ----------- | --------------------------------------------- | ------------------------------ |
| input       | Emitted on user input                         | value: `string`<br>ev: `Event` |
| change      | Emitted on blur, Enter submission or clearing | value: `string`<br>ev: `Event` |
| press-enter | Emitted when the user presses Enter           | ev: `KeyboardEvent`            |
| clear       | Emitted when the user clicks the clear button | ev: `MouseEvent`               |
| focus       | Emitted when the input gains focus            | ev: `FocusEvent`               |
| blur        | Emitted when the input loses focus            | ev: `FocusEvent`               |

### `<Input>` Methods

| Method | Description     | Arguments | Returns |
| ------ | --------------- | --------- | ------- |
| focus  | Focus the input | -         | -       |
| blur   | Blur the input  | -         | -       |
| select | Select all text | -         | -       |

### `<input>` Slots

| Slot       |     Description     | Arguments              |
| ---------- | :-----------------: | ---------------------- |
| suffix     |   Suffix content    | -                      |
| prefix     |   Prefix content    | -                      |
| clear-icon | Custom clear button | `clear(event?: Event)` |

### `<InputPassword>` Props

| Parameter          | Description                                                 | Type      | Default |
| ------------------ | ----------------------------------------------------------- | --------- | :-----: |
| visibility-toggle  | Whether to show the password-visibility toggle              | `boolean` | `true`  |
| default-visibility | Default uncontrolled visibility                             | `boolean` | `false` |
| visibility         | Controlled password visibility; supports v-model:visibility | `boolean` |   `-`   |

InputPassword supports all Input props, events, slots and methods.

### `<InputGroup>` Props

| Parameter | Description                      | Type                            | Default                                     |
| --------- | -------------------------------- | ------------------------------- | ------------------------------------------- |
| size      | Default size within the group    | `ComponentSize`                 | Inherited from Form/ConfigProvider, or `md` |
| variant   | Default variant within the group | `filled \| outline \| standard` | `filled`                                    |
| disabled  | Group disabled state             | `boolean`                       | Inherited from Form, or `false`             |
| readonly  | Group readonly state             | `boolean`                       | Inherited from Form, or `false`             |
| hint      | Group floating hint              | `boolean`                       | Library default                             |

### `<InputPassword>` Events

| Parameter         | Description                     | Arguments         |
| ----------------- | ------------------------------- | ----------------- |
| visibility-change | Emitted when visibility changes | `visible:boolean` |

## Type definitions

The component exports the following types

```ts
import type { InputProps } from "@cedar-design/ui";
```

Public types: `InputEmits`, `InputSlots`, `InputExpose`, `InputGroupSlots`, `InputPasswordEmits`, `InputPasswordSlots`, `InputPasswordExpose`.

### Form presentation inheritance

Supports `edit-mode`: `direct / click / dblclick`. Inherits FormItem/Form when unset; standalone usage defaults to direct. readPretty displays plain text; popup editing updates v-model after confirmation by default. Optional before-commit can intercept saving after candidate validation. See the Form documentation for usage and comparison demos.

### Input caret theme

| CSS variable            | Default        | Description                                            |
| ----------------------- | -------------- | ------------------------------------------------------ |
| `--c-input-caret-color` | `currentColor` | Caret color, independently overridable from text color |

`--c-field-caret-color` sets the shared caret color, defaulting to `currentColor`. `--c-input-caret-color` overrides this component and defaults to `var(--c-field-caret-color)`.

---

Document: llms/en-US/components/layout.md

<!-- Source: src/layout/README.en-US.md; locale: en-US; page: /en/components/layout/ -->

# Layout

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/layout/__demos__/basic.vue

```vue
<template>
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout-content class="layout-content">Content</c-layout-content>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
  <br />
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-sider class="layout-sider">Sider</c-layout-sider>
      <c-layout-content class="layout-content">Content</c-layout-content>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
  <br />
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-content class="layout-content">Content</c-layout-content>
      <c-layout-sider class="layout-sider">Sider</c-layout-sider>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
  <br />
  <c-layout style="height: 300px">
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-sider class="layout-sider" style="width: 64px">Sider</c-layout-sider>
      <c-layout-sider class="layout-sider" style="width: 206px; margin-left: 1px">Sider </c-layout-sider>
      <c-layout-content class="layout-content">Content</c-layout-content>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
</template>

<style scoped lang="less">
.layout-header {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-3);
  color: var(--c-color-text-1);
}

.layout-content {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-4);
  color: var(--c-color-text-1);
}

.layout-sider {
  min-height: 100px;
  background-color: var(--c-color-primary);

  :deep(.c-layout-sider-children) {
    display: flex;
    justify-content: center;
    align-items: center;
    color: var(--c-color-text-1);
  }
}

.layout-footer {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary);
  color: var(--c-color-text-1);
}
</style>
```

## Layout and arrangement

### Scroll

Preview configuration: `bordered`, `scrollable`.

Example source: src/layout/__demos__/scroll.vue

```vue
<template>
  <c-layout class="scroll-layout">
    <c-layout-header bordered class="bar">
      固定头部
      <c-button
        size="sm"
        @click="content?.scrollTo({ top: 0, behavior: 'smooth' })"
        >回到顶部</c-button
      >
    </c-layout-header>
    <c-layout-content ref="content" scrollable @scroll="onScroll">
      <div v-for="item in 30" :key="item" class="row">
        内容 {{ item }} · 只有内容区域滚动
      </div>
    </c-layout-content>
    <c-layout-footer bordered class="bar"
      >固定底部 · 已滚动 {{ offset }}px</c-layout-footer
    >
  </c-layout>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { LayoutContentInstance } from "../index";
const content = ref<LayoutContentInstance>();
const offset = ref(0);
const onScroll = (event: Event) => {
  offset.value = Math.round((event.target as HTMLElement).scrollTop);
};
</script>
<style scoped>
.scroll-layout {
  height: 320px;
  background: var(--c-color-bg-2);
}
.bar {
  padding: 12px 16px;
  display: flex;
  align-items: center;
  justify-content: space-between;
}
.row {
  padding: 16px;
  border-bottom: 1px solid var(--c-color-border-2);
}
</style>
```

### Sider Options

- `has-sider`: Indicates that there is a Sider in the sub-element, which generally does not need to be specified. Used to avoid style flicker when rendering on the server side.

Example source: src/layout/__demos__/sider-options.vue

```vue
<template>
  <div class="controls">
    <c-radio-group v-model="placement"
      ><c-radio value="left">左侧</c-radio
      ><c-radio value="right">右侧</c-radio></c-radio-group
    >
    <c-radio-group v-model="mode"
      ><c-radio value="width">宽度折叠</c-radio
      ><c-radio value="transform">位移折叠</c-radio></c-radio-group
    >
    <label>完全收起 <c-switch v-model="zero" /></label>
    <c-button size="sm" @click="collapsed = !collapsed">{{
      collapsed ? "展开" : "收起"
    }}</c-button>
  </div>
  <c-layout has-sider class="options-layout">
    <c-layout-sider
      v-model:collapsed="collapsed"
      :placement="placement"
      :collapse-mode="mode"
      :collapsed-width="zero ? 0 : 48"
      :width="200"
      bordered
      collapsible
    >
      <div v-for="item in 12" :key="item" class="item">
        {{ item }} · 项目导航和工作空间
      </div>
    </c-layout-sider>
    <c-layout-content scrollable class="content">
      <h4>内容区域</h4>
      <p>切换左右位置和折叠方式。完全收起后仍可通过边缘按钮展开。</p>
      <p>Tab 可聚焦折叠按钮，Enter 或空格可切换状态。</p>
    </c-layout-content>
  </c-layout>
</template>
<script setup lang="ts">
import { ref } from "vue";
const placement = ref<"left" | "right">("left");
const mode = ref<"width" | "transform">("width");
const collapsed = ref(false);
const zero = ref(false);
</script>
<style scoped>
.controls {
  display: flex;
  gap: 16px;
  flex-wrap: wrap;
  margin-bottom: 16px;
  align-items: center;
}
.controls label {
  display: flex;
  align-items: center;
  gap: 8px;
}
.options-layout {
  height: 300px;
  background: var(--c-color-bg-2);
}
.item {
  padding: 16px;
}
.content {
  padding: 16px;
}
</style>
```

## Content and presentation

### Resize

Preview configuration: `:resize-directions="['right']"`.

Example source: src/layout/__demos__/resize.vue

```vue
<template>
  <c-layout>
    <c-layout-header class="layout-header">Header</c-layout-header>
    <c-layout>
      <c-layout-sider class="layout-sider" :resize-directions="['right']"> Sider </c-layout-sider>
      <c-layout-content class="layout-content">Content</c-layout-content>
    </c-layout>
    <c-layout-footer class="layout-footer">Footer</c-layout-footer>
  </c-layout>
</template>

<style scoped lang="less">
.layout-header {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-3);
  color: var(--c-color-text-1);
}

.layout-content {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary-light-4);
  color: var(--c-color-text-1);
}

.layout-sider {
  min-height: 100px;
  background-color: var(--c-color-primary);

  :deep(.c-layout-sider-children) {
    display: flex;
    justify-content: center;
    align-items: center;
    color: var(--c-color-text-1);
  }
}

.layout-footer {
  height: 100px;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--c-color-primary);
  color: var(--c-color-text-1);
}
</style>
```

### Collapse

- `has-sider`: Indicates that there is a Sider in the sub-element, which generally does not need to be specified. Used to avoid style flicker when rendering on the server side.

Example source: src/layout/__demos__/collapse.vue

```vue
<template>
  <c-layout class="collapse-layout" has-sider>
    <c-layout-sider v-model:collapsed="collapsed" collapsible>
      <div class="sider-content">{{ collapsed ? '导航' : '侧栏导航区域' }}</div>
    </c-layout-sider>
    <c-layout>
      <c-layout-header class="header">可折叠侧栏</c-layout-header>
      <c-layout-content class="content">
        <c-button @click="collapsed = !collapsed">{{ collapsed ? '展开侧栏' : '收起侧栏' }}</c-button>
        <p>侧栏和内容区共享可用高度，底部触发器保持在侧栏底部。</p>
      </c-layout-content>
    </c-layout>
  </c-layout>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const collapsed = ref(false)
</script>

<style scoped>
.collapse-layout { height: 300px; background: var(--c-color-bg-2); }
.sider-content, .header, .content { padding: 16px; }
.header { background: var(--c-color-bg-3); }
</style>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Content inherits reading direction. Sider placement=left/right and physical ResizeBox handles keep their physical-side semantics. Nested headings and content may override dir locally.

## API

### Layout Props

| Parameter | Description | Type | Default |
| --------- | ------------------------------------------------------------------ | ------- | :----: |
| scrollable | Enable native scrolling on this element; requires constrained height | boolean | false |
| has-sider | Indicates that there is a Sider in the sub-element, which generally does not need to be specified. Used to avoid style flicker when rendering on the server side. | boolean | false |

### Layout-Header Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| default | Content | - |

### Layout-content Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| default | Content | - |

### Layout-Footer Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| default | Content | - |

### Layout-Sider Props

| Parameter | Description | Type | Default |
| ----------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------- | :-----: |
| theme | Theme color | 'dark' \| 'light' | 'light' |
| collapsed | Current collapsed state | boolean | - |
| default-collapsed | Default collapsed state | boolean | false |
| collapsible | Whether collapsing is enabled | boolean | false |
| width | Width | number \| string | 200 |
| collapsed-width | Collapsed width | number | 48 |
| reverse-arrow | Reverse the collapse arrow; useful for a right-side Sider | boolean | false |
| breakpoint | Responsive breakpoint; see responsive Grid | 'xxl' \| 'xl' \| 'lg' \| 'md' \| 'sm' \| 'xs' | - |
| resize-directions | Replace the native aside with ResizeBox; this is the ResizeBox directions parameter. See ResizeBox | Array<'left' \| 'right' \| 'top' \| 'bottom'> | - |
| hide-trigger | Hide the bottom collapse trigger | boolean | false |

### Layout-Sider Events

| Event | Description | Arguments |
| ---------- | ---------------------------------------------------------------- | -------------------------------------------------------- |
| collapse | Expand/collapse event, from the collapse control or responsive changes | collapsed: boolean<br>type: 'clickTrigger'\|'responsive' |
| breakpoint | Responsive-breakpoint event | collapsed: boolean |

### Layout-Sider Slots

| Slot | Description | Arguments |
| ------- | :------------------: | ------------------ |
| trigger | Custom bottom collapse trigger | collapsed: boolean |

## Type definitions

The component exports the following types

```ts
import type { LayoutProps } from '@cedar-design/ui'
```

### Additional layout capabilities

| Component | Prop | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Content | scrollable | boolean | false | Use this element as a native scroll container |
| Header / Footer / Sider | bordered | boolean | false | Show a border adjacent to the content |
| Sider | placement | 'left' / 'right' | 'left' | Sidebar placement; handles arrows automatically, while reverse-arrow remains supported |
| Sider | collapse-mode | 'width' / 'transform' | 'width' | Resize or translate content while collapsing |

Layout, Content and Sider emit `scroll`(event: Event) and expose `scrollTo(options: ScrollToOptions)` / `scrollTo(x: number, y: number)`. Sider scrolls its internal content node by default. `width` accepts numeric px or CSS lengths. Percentage widths with transform mode are discouraged; use definite lengths such as px/rem.

The collapse control is a native button supporting Tab, Enter and Space. With `collapsed-width="0"`, the hidden region is inert and the expansion entry stays at the sidebar edge. A custom trigger slot should contain display content without nested buttons.

---

Document: llms/en-US/components/link.md

<!-- Source: src/link/README.en-US.md; locale: en-US; page: /en/components/link/ -->

# Link

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/link/__demos__/basic.vue

```vue
<template>
  <c-link href="https://example.com/" target="_blank" rel="noopener noreferrer"
    >访问示例网站</c-link
  >
</template>
```

## Appearance and states

### Link sizes and semantic colors

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Link status | Link sizes and semantic colors, Link Mode, Link Underline |
| `href` | Link URL | Link Mode, Hoverable |
| `size` | Text, icon and loading-icon size | Link sizes and semantic colors |
| `icon` | Icon | Link sizes and semantic colors |
| `loading` | Whether the link is loading | Link sizes and semantic colors |
| `target` | Native link target | Link Mode |
<!-- demo-config-notes:end -->


Compare sizes and semantic colors independently of navigation, disabled interception and loading.

Example source: src/link/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
return { sizes }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">五种尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" size="md">
        <c-space v-for="size in scene1.sizes" :key="size" wrap size="md" align="center">
          <c-link :size="size" status="primary">{{ size }} 链接</c-link>
          <c-link :size="size" status="primary" icon>{{ size }} 图标</c-link>
          <c-link :size="size" loading>{{ size }} 加载中</c-link>
        </c-space>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="link-status">
    <h4><span lang="zh-CN">链接状态</span><span lang="en-US">link status</span></h4>
    <c-space wrap size="sm">
        <c-link status="default">默认链接</c-link>
        <c-link status="primary">主要链接</c-link>
        <c-link status="secondary">次要链接</c-link>
        <c-link status="tertiary">三级链接</c-link>
        <c-link status="info">信息链接</c-link>
        <c-link status="success">成功链接</c-link>
        <c-link status="warning">警告链接</c-link>
        <c-link status="danger">危险链接</c-link>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Link Mode

- `status`: Selects the semantic state.

Example source: src/link/__demos__/link-mode.vue

```vue
<template>
  <c-space size="sm">
    <c-link
      status="primary"
      href="https://example.com/"
      target="_blank"
      rel="noopener noreferrer"
    >
      href 链接
    </c-link>
  </c-space>
</template>
```

### Link Underline

- `status`: Selects the semantic state.

Example source: src/link/__demos__/link-underline.vue

```vue
<template>
  <c-space size="sm">
    <c-link status="primary" underline="always">始终显示</c-link>
    <c-link status="primary" underline="hover">悬停显示</c-link>
    <c-link status="primary" underline="none">不显示</c-link>
  </c-space>
</template>
```

### Link Disabled

- `disabled`: Prevents user interaction.

Example source: src/link/__demos__/link-disabled.vue

```vue
<template>
  <c-link disabled>禁用状态</c-link>
</template>
```

### Hoverable

Preview configuration: `hoverable`, `href="#link"`.

Example source: src/link/__demos__/hoverable.vue

```vue
<template>
  <c-space size="sm">
    <c-link hoverable href="#link">悬浮态底色</c-link>
    <c-link href="#link">Tab 键聚焦</c-link>
  </c-space>
</template>
```

## Content and presentation

### Link Icon

Preview configuration: `icon`.

Example source: src/link/__demos__/link-icon.vue

```vue
<template>
  <c-space size="sm">
    <c-link icon>默认图标</c-link>
    <c-link>
      <template #icon><c-icon-edit /></template>
      自定义图标
    </c-link>
  </c-space>
</template>
```

## Interaction and control

### Link Loading

Preview configuration: `loading`, `:loading="loading"`.

Example source: src/link/__demos__/link-loading.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, ref } from "vue";

const loading = ref(false);
const ready = ref(false);
const href =
  "data:text/plain;charset=utf-8," + encodeURIComponent("示例报告：准备完成。");
let timer: ReturnType<typeof setTimeout> | undefined;

function prepareDownload(event: MouseEvent) {
  if (ready.value) {
    return;
  }
  event.preventDefault();
  loading.value = true;
  // 模拟业务准备；完成后再次激活链接，交给浏览器原生下载。
  timer = setTimeout(() => {
    ready.value = true;
    loading.value = false;
    timer = undefined;
  }, 1000);
}
onBeforeUnmount(() => clearTimeout(timer));
</script>
<template>
  <c-space size="sm">
    <c-link :href="href" download="report.txt" loading>加载中</c-link>
    <c-link
      :href="href"
      download="report.txt"
      :loading="loading"
      @click="prepareDownload"
    >
      {{ loading ? "准备中" : ready ? "下载示例报告" : "准备下载报告" }}
    </c-link>
  </c-space>
  <p>
    首次点击或按 Enter 准备报告；完成后再次激活链接，浏览器下载文本文件。loading
    由业务手动控制。
  </p>
</template>
```

## API

### Native links and controlled loading

Provide href for navigation. Disabled/loading links retain their link role when an href was provided, remove navigation attributes and leave the Tab order. Native download, hreflang, referrerpolicy and ARIA attributes pass through. Loading replaces the icon slot. click is a MouseEvent notification with Vue once semantics; returned promises do not manage loading. Use Button for operations without a navigation target.

The loading example prepares a report on the first activation, then uses the browser's native download on the next activation. Preparation is canceled when unmounted.


### `<Link>` Props

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| `size` | Five text, icon and spinner sizes | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' |
| `href` | Native link destination | string | - |
| `target` | Native target | string | - |
| `rel` | Native rel | string | - |
| `status` | Semantic status | SemanticStatus | 'default' |
| `underline` | Underline policy | 'always' \| 'hover' \| 'none' | 'none' |
| `hoverable` | Padded hover/active backgrounds | boolean | false |
| `icon` | Show the leading icon; icon slot takes priority | boolean | false |
| `loading` | Show spinner and block navigation/click | boolean | false |
| `disabled` | Disable the link | boolean | false |


### `<Link>` Events

| Event | Description | Arguments |
| ------ | -------------- | ----------------------------- |
| click | Click event | `(event: MouseEvent) => void` |

### Slots

| Slot | Description |
| --- | --- |
| default | Link content |
| icon | Custom icon; replaced by the loading icon while loading |

### Type definitions

The component exports the following types

```ts
import type { LinkProps, LinkSize, LinkUnderline, LinkInstance } from '@cedar-design/ui'
```

### Style migration

Internal classes use `c-link--status-*`, `c-link--underline-*`, `c-link--disabled`, `c-link--loading` and `c-link__icon`. Migrate old single-hyphen selectors and prefer `--c-link-*` CSS variables. Focus supports `--c-link-focus-width` (2px), `--c-link-focus-offset` (2px), `--c-link-focus-color` (currentColor) and `--c-link-focus-opacity` (0.8). Reduced motion disables loading rotation and transitions.

Text colors match Button text variants: default uses content-primary; secondary/tertiary use content-secondary; colored statuses use their semantic content colors; disabled/loading use content-disabled. Both brands inherit these in light/dark modes.

Size variables: `--c-link-size-xs-font-size`, `--c-link-size-sm-font-size`, `--c-link-size-md-font-size`, `--c-link-size-lg-font-size`, `--c-link-size-xl-font-size`. Defaults are 12 / 13 / 14 / 16 / 18px. md references `--c-link-font-size`; icons/loading icons use 1em.

---

Document: llms/en-US/components/list.md

<!-- Source: src/list/README.en-US.md; locale: en-US; page: /en/components/list/ -->

# List

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/list/__demos__/basic.vue

```vue
<template>
  <c-list>
    <template #header> List title </template>
    <c-list-item>Beijing Bytedance Technology Co., Ltd.</c-list-item>
    <c-list-item>Bytedance Technology Co., Ltd.</c-list-item>
    <c-list-item>Beijing Toutiao Technology Co., Ltd.</c-list-item>
    <c-list-item>Beijing Volcengine Technology Co., Ltd.</c-list-item>
    <c-list-item>China Beijing Bytedance Technology Co., Ltd.</c-list-item>
  </c-list>
</template>
<script lang="ts" setup>
</script>
```

## Appearance and states

### Size

- `size`: Controls the component size.

Example source: src/list/__demos__/size.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-radio-group v-model="size" type="button">
      <c-radio value="sm">sm</c-radio>
      <c-radio value="md">md</c-radio>
      <c-radio value="lg">lg</c-radio>
    </c-radio-group>
    <c-list :size="size">
      <template #header> List title </template>
      <c-list-item>Beijing Bytedance Technology Co., Ltd.</c-list-item>
      <c-list-item>Bytedance Technology Co., Ltd.</c-list-item>
      <c-list-item>Beijing Toutiao Technology Co., Ltd.</c-list-item>
      <c-list-item>Beijing Volcengine Technology Co., Ltd.</c-list-item>
      <c-list-item>China Beijing Bytedance Technology Co., Ltd.</c-list-item>
    </c-list>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')
</script>
```

## Content and layout

### Prefix Suffix

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `bordered` | Outer border | Actions Layout |
| `data` | Data consumed by item slot | Actions Layout |
<!-- demo-config-notes:end -->


Preview configuration: `shape="square"`.

Example source: src/list/__demos__/prefix-suffix.vue

```vue
<template>
  <c-list>
    <c-list-item v-for="item in items" :key="item.title">
      <template #prefix>
        <c-avatar shape="square">{{ item.initial }}</c-avatar>
      </template>
      <template #suffix>
        <c-button size="sm">编辑</c-button>
      </template>
      <div class="list-item-title">{{ item.title }}</div>
      <div class="list-item-description">{{ item.description }}</div>
    </c-list-item>
  </c-list>
</template>

<script lang="ts" setup>
const items = [
  {
    initial: 'B',
    title: 'Beijing Bytedance Technology Co., Ltd.',
    description: 'Beijing ByteDance Technology Co., Ltd. is an enterprise located in China.',
  },
  {
    initial: 'T',
    title: 'Beijing Toutiao Technology Co., Ltd.',
    description: 'Toutiao is a content platform under ByteDance.',
  },
  {
    initial: 'V',
    title: 'Beijing Volcengine Technology Co., Ltd.',
    description: 'Volcengine provides cloud and AI infrastructure.',
  },
]
</script>

<style scoped>
.list-item-title {
  font-weight: var(--c-font-weight-500);
}

.list-item-description {
  margin-top: 4px;
  color: var(--c-color-text-2);
}
</style>
```

### Actions Layout

- `data`: Supplies the example data.

Example source: src/list/__demos__/actions-layout.vue

```vue
<template>
  <c-list :bordered="false" :data="dataSource">
    <template #item="{ item }">
      <c-list-item>
        <template #prefix>
          <c-avatar shape="square">
            <img alt="avatar" :src="item.avatar" />
          </c-avatar>
        </template>
        <template #suffix>
          <img class="list-demo-cover" alt="cover" :src="item.imageSrc" />
        </template>
        <div class="list-item-title">{{ item.title }}</div>
        <div class="list-item-description">{{ item.description }}</div>
      </c-list-item>
    </template>
  </c-list>
</template>

<script lang="ts" setup>
const names = ['Socrates', 'Balzac', 'Plato']
const avatarSrc = [
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/a8c8cdb109cb051163646151a4a5083b.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/e278888093bef8910e829486fb45dd69.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/9eeb1800d9b78349b24682c3518ac4a3.png~tplv-uwbnlip3yd-webp.webp',
]
const imageSrc = [
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/29c1f9d7d17c503c5d7bf4e538cb7c4f.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/04d7bc31dd67dcdf380bc3f6aa07599f.png~tplv-uwbnlip3yd-webp.webp',
  '//p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/1f61854a849a076318ed527c8fca1bbf.png~tplv-uwbnlip3yd-webp.webp',
]
const dataSource = names.map((title, index) => ({
  avatar: avatarSrc[index],
  title,
  description:
    'Beijing ByteDance Technology Co., Ltd. is an enterprise located in China. ByteDance has products such as TikTok, Toutiao, volcano video and Douyin (the Chinese version of TikTok).',
  imageSrc: imageSrc[index],
}))
</script>

<style scoped>
.list-item-title {
  font-weight: var(--c-font-weight-500);
}

.list-item-description {
  margin-top: 4px;
  color: var(--c-color-text-2);
}

.list-demo-cover {
  display: block;
  width: 120px;
  height: 80px;
  object-fit: cover;
  border-radius: var(--c-border-radius-md);
}
</style>
```

## Scrolling and virtualization

### Bounded Scroll

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Data consumed by item slot | Bounded Scroll, Virtual List, Virtual Navigation |
| `virtual-list-props` | Data virtualization; ignored when default slot exists | Virtual List, Virtual Navigation |
| `max-height` | Maximum ordinary viewport height; number in px or CSS length, zero means unlimited | Bounded Scroll |
| `scrollbar` | Ordinary viewport custom scrollbar; false uses native scrolling | Bounded Scroll |
| `size` | Implemented sizes only; xs/xl are not supported | Bounded Scroll |
| `split` | Item/header/footer separators, independent of border | Bounded Scroll |
<!-- demo-config-notes:end -->


- `data`: Supplies the example data.
- `size`: Controls the component size.

Example source: src/list/__demos__/bounded-scroll.vue

```vue
<script setup>
const rows = Array.from({ length: 20 }, (_, index) => ({ id: index, name: '记录 ' + (index + 1) }))
</script>
<template>
  <c-space direction="column" style="width: 100%">
    <c-list :data="rows" :max-height="180" :scrollbar="false">
      <template #header>原生滚动条</template>
      <template #item="{ item }"><c-list-item>{{ item.name }}</c-list-item></template>
    </c-list>
    <c-list :data="rows" max-height="12rem" :scrollbar="{ type: 'track' }" size="sm" :split="false">
      <template #header>自定义滚动条，无分隔线</template>
      <template #item="{ item }"><c-list-item>{{ item.name }}</c-list-item></template>
    </c-list>
  </c-space>
</template>
```

### Virtual List

- `data`: Supplies the example data.

Example source: src/list/__demos__/virtual-list.vue

```vue
<template>
  <h3 :style="{ color: 'var(--c-color-text-2)' }">10000 items</h3>
  <c-list
    :style="{ width: `600px` }"
    :virtualListProps="{
      height: 560,
    }"
    :data="list"
  >
    <template #item="{ item, index }">
      <c-list-item :key="index">
        <template #prefix>
          <c-avatar shape="square">A</c-avatar>
        </template>
        <div>{{ item.title }}</div>
        <div class="list-item-description">{{ item.description }}</div>
      </c-list-item>
    </template>
  </c-list>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const list = reactive(
  Array(10000)
    .fill(null)
    .map((_, index) => {
      const prefix = `0000${index}`.slice(-5)
      return {
        title: 'Beijing Bytedance Technology Co., Ltd.',
        description: `(${prefix}) Beijing ByteDance Technology Co., Ltd. is an enterprise located in China.`,
      }
    }),
)
</script>

<style scoped>
.list-item-description {
  margin-top: 4px;
  color: var(--c-color-text-2);
}
</style>
```

### Virtual Navigation

- `data`: Supplies the example data.

Example source: src/list/__demos__/virtual-navigation.vue

```vue
<script setup>
import { ref } from 'vue'
const list = ref()
const rows = Array.from({ length: 1000 }, (_, id) => ({ id, name: '记录 ' + (id + 1) }))
</script>
<template>
  <c-space direction="column" style="width: 100%">
    <c-space wrap>
      <c-button @click="list.scrollIntoView({ key: 499, align: 'top' })">第 500 项置顶</c-button>
      <c-button @click="list.scrollIntoView({ key: 499, align: 'bottom' })">第 500 项置底</c-button>
      <c-button @click="list.scrollIntoView({ key: 499, align: 'auto' })">仅滚动到可见</c-button>
    </c-space>
    <c-list ref="list" :data="rows" :virtual-list-props="{ height: 240, itemKey: 'id', estimatedSize: 48, buffer: 10 }">
      <template #item="{ item, index }"><c-list-item><template #prefix>{{ index + 1 }}</template>{{ item.name }}</c-list-item></template>
    </c-list>
  </c-space>
</template>
```

## Lifecycle

### Virtual Lifecycle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Data consumed by item slot | Virtual Lifecycle |
| `virtual-list-props` | Data virtualization; ignored when default slot exists | Virtual Lifecycle |
<!-- demo-config-notes:end -->


- `data`: Supplies the example data.

Example source: src/list/__demos__/virtual-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const active = ref(true);
const mounted = ref(true);
const rows = Array.from({ length: 100 }, (_, key) => ({ key }));
let retained:
  | { scrollIntoView: (options: { key: number; align: "top" }) => void }
  | undefined;
const capture = (instance: typeof retained) => {
  if (instance) retained = instance;
};
const jump = () => retained?.scrollIntoView({ key: 50, align: "top" });
</script>

<template>
  <div>
    <c-button @click="active = !active">Activate / deactivate</c-button>
    <c-button @click="mounted = !mounted">Mount / dispose cache</c-button>
    <c-button @click="jump">Retained command: row 51</c-button>
    <p>Inactive/disposed commands do nothing. Activation never replays them.</p>
    <KeepAlive v-if="mounted">
      <c-list
        v-if="active"
        :ref="capture"
        :data="rows"
        :virtual-list-props="{
          height: 100,
          fixedSize: true,
          estimatedSize: 20,
          buffer: 2,
          itemKey: 'key',
        }"
      >
        <template #item="{ item }"
          ><div style="height: 20px">{{ item.key + 1 }}</div></template
        >
      </c-list>
    </KeepAlive>
  </div>
</template>
```

## API

### List Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| data | Data consumed by item slot | unknown[] | undefined |
| size | Implemented sizes only; xs/xl are not supported | 'sm' \| 'md' \| 'lg' | md |
| bordered | Outer border | boolean | true |
| split | Item/header/footer separators, independent of border | boolean | true |
| loading | Initial loading/refresh feedback, not pagination state | boolean | false |
| max-height | Maximum ordinary viewport height; number in px or CSS length, zero means unlimited | number \| string | 0 |
| virtual-list-props | Data virtualization; ignored when default slot exists | ListVirtualListProps | undefined |
| scrollbar | Ordinary viewport custom scrollbar; false uses native scrolling | boolean \| ListScrollbarProps | true |

Virtual lists use a dedicated viewport without nesting a custom scrollbar. virtualListProps.height overrides maxHeight; with neither, height defaults to 200px. Numeric and unit-bearing CSS lengths are accepted. Invalid/nonpositive max-height does not constrain height.

ListVirtualListProps supports height, threshold, fixedSize, estimatedSize, buffer, itemKey and component. Removed isStaticItemHeight is unsupported; List.data supplies data. Counts at or below threshold render all items. Variable heights use measurements and estimatedSize; buffer controls overscan rows.

ListScrollbarProps supports type: 'track'|'embed', outerClass, outerStyle, hide, disableHorizontal and disableVertical. JavaScript object fields use camelCase.

### Events / Methods

- scroll(event: Event): one notification per real scroll event.
- scrollIntoView({ index?, key?, align }): virtual-list positioning. index overrides key; align is top/bottom/auto. auto does nothing for a fully visible item, otherwise scrolls the minimum distance required. Invalid targets or nonvirtual mode do nothing.

### Slots

List slots: default (overrides data), item({ item, index }), header, footer, empty. Empty state appears only without a default slot/data and while not loading. ListItem prefix/default/suffix retain list-item semantics without managing buttons/business interactions.

### Types

ListProps、ListSize、ListVirtualListProps、ListScrollbarProps、ListExpose、ListSlots、ListEmits、ListInstance、ListItemInstance。

List handles display and an optional virtual viewport. Compose InfiniteScroll status/target behavior for pagination rather than duplicating its loading state machine inside List.

## Style variables

| Token | Default |
| --- | --- |
| `--c-list-background` | `transparent` |
| `--c-list-empty-padding` | `16px` |
| `--c-list-empty-color` | `var(--c-list-text-color)` |
| `--c-list-loading-padding` | `0px` |
| `--c-list-border-width` | `1px` |
| `--c-list-border-color` | `var(--c-color-neutral-3)` |
| `--c-list-border-radius` | `var(--c-border-radius-md)` |
| `--c-list-text-color` | `var(--c-color-text-1)` |
| `--c-list-font-size` | `var(--c-font-size-body-3)` |
| `--c-list-line-height` | `var(--c-line-height)` |
| `--c-list-text-color-header` | `var(--c-color-text-1)` |
| `--c-list-font-size-header` | `var(--c-font-size-title-1)` |
| `--c-list-font-weight-header` | `var(--c-font-weight-500)` |
| `--c-list-line-height-header` | `1.5` |
| `--c-list-size-sm-padding-vertical-header` | `var(--c-spacing-4)` |
| `--c-list-size-sm-padding-horizontal-header` | `var(--c-spacing-8)` |
| `--c-list-size-sm-padding-vertical-item` | `9px` |
| `--c-list-size-sm-padding-horizontal-item` | `var(--c-spacing-8)` |
| `--c-list-size-md-padding-vertical-header` | `var(--c-spacing-6)` |
| `--c-list-size-md-padding-horizontal-header` | `var(--c-spacing-8)` |
| `--c-list-size-md-padding-vertical-item` | `13px` |
| `--c-list-size-md-padding-horizontal-item` | `var(--c-spacing-8)` |
| `--c-list-size-lg-padding-vertical-header` | `var(--c-spacing-7)` |
| `--c-list-size-lg-padding-horizontal-header` | `var(--c-spacing-8)` |
| `--c-list-size-lg-padding-vertical-item` | `17px` |
| `--c-list-size-lg-padding-horizontal-item` | `var(--c-spacing-8)` |
| `--c-list-item-prefix-margin-right` | `var(--c-spacing-8)` |
| `--c-list-item-suffix-margin-left` | `var(--c-spacing-8)` |
| `--c-list-size-sm-padding-vertical-footer` | `var(--c-list-size-sm-padding-vertical-item)` |
| `--c-list-size-sm-padding-horizontal-footer` | `var(--c-list-size-sm-padding-horizontal-item)` |
| `--c-list-size-md-padding-vertical-footer` | `var(--c-list-size-md-padding-vertical-item)` |
| `--c-list-size-md-padding-horizontal-footer` | `var(--c-list-size-md-padding-horizontal-item)` |
| `--c-list-size-lg-padding-vertical-footer` | `var(--c-list-size-lg-padding-vertical-item)` |
| `--c-list-size-lg-padding-horizontal-footer` | `var(--c-list-size-lg-padding-horizontal-item)` |

---

Document: llms/en-US/components/loading.md

<!-- Source: src/loading/README.en-US.md; locale: en-US; page: /en/components/loading/ -->

# Loading

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `tip="加载中"`.

Example source: src/loading/__demos__/basic.vue

```vue
<template>
  <c-loading tip="加载中" />
</template>
```

## Appearance and states

### Loading shape, size and color

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | Loading-indicator size; numbers are px | Loading shape, size and color |
| `type` | Loading animation type | Loading shape, size and color |
| `color` | Indicator and hint-text color | Loading shape, size and color |
<!-- demo-config-notes:end -->


Compare the shape, size and color of loading indicators. Container masks and directives remain separate.

Example source: src/loading/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">大小</span><span lang="en-US">size</span></h4>
    <c-space align="center" justify="space-between">
        <c-loading size="sm" />
        <c-loading type="cube" size="sm" />
        <c-loading type="wave" size="sm" />
        <c-loading type="rect" size="sm" />
        <c-loading type="disappear" size="sm" />
        <c-loading :size="32" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="color">
    <h4><span lang="zh-CN">颜色</span><span lang="en-US">color</span></h4>
    <c-space align="center" justify="space-between">
        <c-loading color="var(--c-color-info)" />
        <c-loading type="cube" color="var(--c-color-success)" />
        <c-loading type="wave" color="var(--c-color-warning)" />
        <c-loading type="rect" color="var(--c-color-danger)" />
        <c-loading type="disappear" color="var(--c-color-text-disabled)" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="type">
    <h4><span lang="zh-CN">类型</span><span lang="en-US">type</span></h4>
    <c-space align="center" justify="space-between">
        <c-loading />
        <c-loading type="cube" />
        <c-loading type="wave" />
        <c-loading type="rect" />
        <c-loading type="disappear" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Layout and arrangement

### Wrap

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `tip` | Prompt copy | Wrap |
| `loading` | Whether loading; effective only when wrapping content | Wrap |
<!-- demo-config-notes:end -->


Preview configuration: `tip="LOADING"`, `:loading="loading"`, `title="介绍"`, `description="Cedar 是一个基于 Vue 3 的企业级桌面端组件库。"`.

Example source: src/loading/__demos__/wrap.vue

```vue
<template>
  <c-button style="margin-bottom: 8px" @click="loading = !loading">
    {{ loading ? "关闭" : "打开" }}
  </c-button>
  <c-loading tip="LOADING" :loading="loading">
    <c-card
      title="介绍"
      description="Cedar 是一个基于 Vue 3 的企业级桌面端组件库。"
    />
  </c-loading>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const loading = ref(false);
</script>
```

## Content and presentation

### Directive

Preview configuration: `title="介绍"`, `description="v-c-loading 会在当前容器内渲染 Loading 遮罩，不会改变内容结构。"`.

Example source: src/loading/__demos__/directive.vue

```vue
<template>
  <c-space direction="column">
    <h4>简单用法</h4>
    <c-switch v-model="simpleLoading" />
    <c-card
      v-c-loading="simpleLoading"
      title="介绍"
      description="v-c-loading 会在当前容器内渲染 Loading 遮罩，不会改变内容结构。"
    />

    <h4>复杂配置</h4>
    <c-switch v-model="configuredLoading" />
    <c-card
      v-c-loading="{
        loading: configuredLoading,
        tip: '加载中...',
        color: 'var(--c-color-primary)',
        background: 'color-mix(in srgb, var(--c-color-bg-1) 72%, transparent)',
      }"
      title="介绍"
      description="v-c-loading 会在当前容器内渲染 Loading 遮罩，不会改变内容结构。"
    />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const simpleLoading = ref(false);
const configuredLoading = ref(false);
</script>
```

## API

### `<Loading>` Props

| Prop | Description | Type | Default |
| --------- | -------------------------------------- | --------------------------------------------- | -------- |
| type | Loading animation type | `circle \| wave \| cube \| rect \| disappear` | `circle` |
| size | Loading-indicator size; numbers are px | `xs \| sm \| md \| lg \| xl \| number` | `md` |
| radius | Radius for `circle` indicators | `string \| number` | - |
| color | Indicator and hint-text color | `string` | - |
| loading | Whether loading; effective only when wrapping content | `boolean` | `false` |
| tip | Prompt copy | `string` | - |
| hide-icon | Whether to hide the loading indicator | `boolean` | `false` |

`v-c-loading` accepts boolean shorthand or `{ loading, tip, type, size, radius, color, hideIcon, fullscreen, background }`. The object's `loading` field controls state; other props match `Loading`.

#### Registration

`v-c-loading` renders Cedar's built-in `Loading` component. The `c-` prefix avoids collisions with other libraries’ directives. Register it in any of the following ways.

```ts
// 1. Full installation: registers Loading and v-c-loading automatically
import CedarVue from "@cedar-design/ui";

app.use(CedarVue);
```

```ts
// 2. Install Loading on demand: registers the component and directive
import { Loading } from "@cedar-design/ui";

app.use(Loading);
```

```ts
// 3. Register only the directive manually
import { vLoading } from "@cedar-design/ui";

app.directive("c-loading", vLoading);
```

With `CedarResolver()`, `unplugin-vue-components` resolves template `v-c-loading` automatically. `directives: false` disables directive resolution.

### `<Loading>` Slots

| Slot | Description |
| ------- | ---------------------- |
| default | Content covered by the loading mask |
| tip | Custom hint content |
| icon | Custom loading indicator |

The `icon` slot replaces every built-in `type` animation. Without it, the ConfigProvider `loading` slot takes precedence over built-in animations. `hide-icon=true` hides all indicators while allowing tip content to remain visible.

## Type definitions

The component exports the following types:

```ts
import type { LoadingProps } from "@cedar-design/ui";
```

The loading-directive mask prevents default click behavior and propagation. Clicking it does not activate Card or ordinary parent click handlers. Normal clicking resumes after loading. It does not disable keyboard access to underlying controls; set those controls’ `disabled` props to block all interaction.

### Overlay styles

| Variable | Description |
| --- | --- |
| `--c-loading-overlay-background` | Directive overlay background; the background option overrides this value. |

Content-overlay class: `.c-loading__content-overlay`.

Each directive update replaces the complete configuration; omitted options and boolean `true` use defaults. Changing `fullscreen` while loading moves the overlay between the host and its owner document body. Host children stay in place. Multiple fullscreen instances share a counted scroll lock: closing a local instance does not unlock fullscreen instances, and the final fullscreen instance preserves an existing external lock class.

---

Document: llms/en-US/components/map.md

<!-- Source: src/map/README.en-US.md; locale: en-US; page: /en/components/map/ -->

# Map

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `map-type="amaps"`.

Example source: src/map/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const location = ref({ longitude: 116.397, latitude: 39.908, address: '北京示例位置' })
function reset() { location.value = { longitude: 116.397, latitude: 39.908, address: '北京示例位置' } }
</script>
<template>
  <c-space direction="column">
    <p>未接入地图 SDK 时显示降级状态，不请求定位权限、不发送真实接口请求。按钮只演示本地位置模型。</p>
    <c-space wrap>
      <c-button @click="location = { longitude: 121.4737, latitude: 31.2304, address: '上海示例位置' }">使用上海示例位置</c-button>
      <c-button @click="reset">重置位置</c-button>
    </c-space>
    <p role="status">当前位置：{{ location.address }}（{{ location.longitude }}, {{ location.latitude }}）</p>
    <c-map v-model="location" map-type="amaps" style="height: 300px" />
  </c-space>
</template>
```

## Content and presentation

### Auth

Example source: src/map/__demos__/auth.vue

```vue
<template>
  <c-alert status="info" title="地图 SDK 接入">
    本地示例不需要登录、令牌或外部图片。生产应用须自行接入地图 SDK 适配器、配置服务与授权域名，再验证搜索、选点和定位；当前降级展示不代表 SDK 已接入成功。
  </c-alert>
</template>
```

## Data and options

### Google

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `map-type` | Map type | Google |
| `is-international` | Whether this is a Google map | Google |
<!-- demo-config-notes:end -->


Preview configuration: `map-type="google"`, `is-international`, `map-type="amaps"`.

Example source: src/map/__demos__/google.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const location = ref({ longitude: -0.1276, latitude: 51.5072, address: 'London sample location' })
</script>
<template>
  <c-space direction="column">
    <p>国际地图使用 is-international 和 map-type="google"。未配置 SDK 时保留降级展示，应用须自行接入适配器和地图服务；示例不保存密钥或 token。</p>
    <c-map v-model="location" map-type="google" is-international style="height: 300px" />
    <p role="status">{{ location.address }}</p>
  </c-space>
</template>
```

Example source: src/map/__demos__/use-vmodel.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const location = ref({ longitude: 116.397, latitude: 39.908, address: '北京示例位置' })
</script>
<template>
  <c-space direction="column">
    <c-map v-model="location" map-type="amaps" style="height: 300px" />
    <p role="status">{{ location.address }}（{{ location.longitude }}, {{ location.latitude }}）</p>
  </c-space>
</template>
```

## API

### Map Props

| Prop | Description | Type | Default |
| ----------------------- | -------------------------------------------- | -------------------------------------------- | ---------------- |
| model-value(**v-model**) | Initial map value representing the selected location | `Object` | - |
| default-value | Default map center | `{ [key in valueKeyAlias[keys]]: any }` | - |
| driver | Return value of `Fetch.genDriiver` | `Driver` | `-` |
| fetch | Return value of `Fetch.genFetch` | `CoreService` | `-` |
| geocoder-url | Geocoder endpoint URL | `string` | `-` |
| geocoder-handler | Processes geocoding-service responses | `(longitude: number, latitude: number)=>{})` | - |
| base-path | Base URL for map data | `String` | `'/pe/powerpro'` |
| is-international | Whether this is a Google map | `Boolean` | - |
| show-name | Whether to show the floating location name | `boolean` | `false` |
| show-locate-me-button | Whether to show the current-location button | `boolean` | `false` |
| show-edit-address-button | Whether to show the floating change-location button | `boolean` | `false` |
| show-map-tips | Whether to show tips above the map | `boolean` | `false` |
| map-type | Map type | `'qqmaps'\|'bmapGL'\|'amaps'` | `'amaps'` |
| enable-gis-search | Whether to enable GIS search; `fetch` is required when enabled | `boolean` | `false` |
| value-key-scope | String array of values displayed on the map | `Array` | `valueKeyScope` |
| value-key-alias | Mapping from map keys to values | `Object` | `valueKeyAlias` |

### MapSelect Props

| map-style | Styles applied directly to the map; can set map height | `object` | `{ height: '300px'}` |

### Map Events

| Event | Description | Arguments |
| --------------- | -------------------------- | ------------------------- |
| change | Emitted when the address changes | `(value: ModelValueType)` |
| init | Emitted after map initialization | `(value: ModelValueType)` |
| loading:address | Emitted while resolving the selected location's address | `-` |
| loaded:address | Emitted after resolving the selected location's address | `-` |

## Type definitions

### valueKeyAlias

```ts
{
  longitude: 'longitude',
  latitude: 'latitude',
  address: 'address',
  name: 'name',
  adcode: 'adcode',
  city: 'city',
  countryCode: 'countryCode',
  country: 'country',
}
```

### valueKeyScope

```ts
;['longitude', 'latitude', 'address', 'name', 'adcode', 'city', 'country', 'countryCode']
```

### ModelValueType

ModelValueType keys depend on valueKeyAlias

```ts
interface ModelValueType {
  adcode?: string
  city?: string
  country?: string
  countryCode?: string
  address?: string
  latitude?: number
  longitude?: number
  name?: string
}
```

The component exports the following types

```ts
import type { MapProps } from '@cedar-design/ui'
```

---

Document: llms/en-US/components/mention.md

<!-- Source: src/mention/README.en-US.md; locale: en-US; page: /en/components/mention/ -->

# Mention

Text input with mention suggestions supplied by the application.

## Basic examples

### Basic usage

Example source: src/mention/__demos__/basic.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-mention v-model="value" :data="['Bytedance', 'Bytedesign', 'Bytenumner']" placeholder="enter something" />
    <c-mention
      v-model="text"
      :data="['Bytedance', 'Bytedesign', 'Bytenumner']"
      type="textarea"
      placeholder="enter something" />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value = ref('')
const text = ref('')
</script>
```

## Customization and slots

### Prefix

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                               | Related examples |
| ------------- | ------------------------------------- | ---------------- |
| `data`        | Data for automatic completion         | Prefix           |
| `prefix`      | Keywords that trigger auto-completion | Prefix           |

<!-- demo-config-notes:end -->

- `data`: Data for automatic completion
- `prefix`: Keywords that trigger auto-completion

Example source: src/mention/__demos__/prefix.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-mention :data="['Bytedance', 'Bytedesign', 'Bytenumner']" placeholder="input @" />
    <c-mention :data="['Bytedance', 'Bytedesign', 'Bytenumner']" prefix="#" placeholder="input #" />
    <c-mention :data="['Bytedance', 'Bytedesign', 'Bytenumner']" prefix="$" placeholder="input $" />
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## Lifecycle and edge cases

### Mirror Lifecycle

Example source: src/mention/__demos__/mirror-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import Mention from "../index";

const active = ref(true);
const mounted = ref(true);
const disabled = ref(false);
const searches = ref(0);
const value = ref("第一行\n第二行\n第三行\n@al");
</script>

<template>
  <div>
    <c-button html-type="button" @click="active = !active"
      >切换 KeepAlive</c-button
    >
    <c-button html-type="button" @click="mounted = !mounted"
      >卸载／挂载</c-button
    >
    <c-button html-type="button" @click="disabled = !disabled"
      >切换禁用</c-button
    >
    <p>
      搜索通知：{{ searches }}。在文本域滚动后输入
      @al，停用再激活，继续输入检查镜像定位。
    </p>
    <KeepAlive v-if="mounted">
      <Mention
        v-if="active"
        v-model="value"
        type="textarea"
        :disabled="disabled"
        :data="['alice', 'alex']"
        :rows="3"
        @search="searches++"
      />
    </KeepAlive>
  </div>
</template>
```

## Loading and waiting

### Controlled loading

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `loading` | Explicit business loading state | `boolean` | `false` |


Set loading explicitly to display feedback. Ordinary event return values do not drive loading. Before hooks retain their documented pending behavior.

Example source: src/mention/__demos__/loading.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, ref } from 'vue'
import type { OptionsLoader } from '../../_hooks/use-option-request'
const loading = ref(true)
const requests = new Set<(failed?: boolean) => void>()
const pending = ref(0)
const status = ref('等待数据 / Waiting for data')
const load: OptionsLoader<string> = (query, { signal }) => new Promise((resolve, reject) => {
  const finish = (failed = false) => {
    requests.delete(finish)
    pending.value = requests.size
    signal.removeEventListener('abort', cancel)
    if (failed) reject(new Error('Candidate request failed'))
    else resolve(['Alice', 'Bob'].filter(name => name.toLowerCase().includes(query.toLowerCase())))
  }
  const cancel = () => finish()
  requests.add(finish)
  pending.value = requests.size
  signal.addEventListener('abort', cancel, { once: true })
})
function settle(failed = false) {
  status.value = failed ? '请求失败，可继续输入重试 / Failed; type to retry' : '数据已返回 / Data received'
  ;[...requests].forEach(finish => finish(failed))
}
onBeforeUnmount(() => settle())
</script>
<template>
  <c-space direction="column" style="width: 100%" :size="16">
    <h4>业务控制 / Manual loading</h4>
    <c-switch v-model="loading" aria-label="业务加载状态 / Manual loading" />
    <c-mention edit-mode="direct" :loading="loading" :data="['Alice', 'Bob']" placeholder="单行输入 @ / Single line" />
    <c-mention edit-mode="direct" type="textarea" :loading="loading" :data="['Alice', 'Bob']" placeholder="多行输入 @ / Multiple lines" />
    <p>loading 只控制显示，两种输入框均可继续编辑。普通事件返回 Promise 不会触发等待。Loading does not disable editing or await notification handlers.</p>
    <h4>数据源等待 / Remote candidates</h4>
    <c-mention edit-mode="direct" :data="load" placeholder="输入 @a，手动返回候选数据 / Type @a" @load-error="() => {}" />
    <c-space>
      <c-button :disabled="!pending" @click="settle()">返回数据 / Resolve</c-button>
      <c-button :disabled="!pending" @click="settle(true)">模拟失败 / Reject</c-button>
    </c-space>
    <p role="status">{{ pending ? '请求中，仍可输入 / Pending; editing remains available' : status }}</p>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### `<mention>` Props

| Parameter                 | Description                                  | Type                                                                                                       |   Default   | Version |
| ------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | :---------: | :------ |
| model-value **(v-model)** | Bound value                                  | `string`                                                                                                   |     `-`     |         |
| default-value             | Default value (uncontrolled state)           | `string`                                                                                                   |    `''`     |         |
| data                      | Data for automatic completion                | `(string \| number \| SelectOptionData \| SelectOptionGroup)[]` / `(query, { signal }) => Array / Promise` | `undefined` |         |
| prefix                    | Keywords that trigger auto-completion        | `string \| string[]`                                                                                       |    `'@'`    |         |
| split                     | Before and after the selected item separator | `string`                                                                                                   |    `' '`    |         |
| type                      | default input or textarea                    | `'input' \| 'textarea'`                                                                                    |  `'input'`  |         |
| disabled                  | Whether disabled                             | `boolean`                                                                                                  |   `false`   |         |
| clearable                 | Whether to allow the input to be cleared     | `boolean`                                                                                                  |   `false`   | 2.23.0  |

### `<mention>` Events

| Event  | Description                                               | Arguments                                                     | Version |
| ------ | --------------------------------------------------------- | ------------------------------------------------------------- | :------ |
| change | Emitted when the value changes                            | value: `string`                                               |         |
| search | Emitted during dynamic search; prefix was added in 2.47.0 | value: `string`<br>prefix: `string`                           |         |
| select | Emitted when a dropdown option is selected                | value: `string \| number \| Record<string, any> \| undefined` |         |
| clear  | Emitted when the user clicks the clear button             | -                                                             | 2.23.0  |
| focus  | Emitted when the text input gains focus                   | ev: `FocusEvent`                                              | 2.42.0  |
| blur   | Emitted when the text input loses focus                   | ev: `FocusEvent`                                              | 2.42.0  |

### `<mention>` Methods

| Method | Description     | Arguments | Returns | Version |
| ------ | --------------- | --------- | ------- | :------ |
| focus  | Focus the input | -         | -       | 2.24.0  |
| blur   | Blur the input  | -         | -       | 2.24.0  |

### `<mention>` Slots

| Slot   |  Description   | Arguments          | Version |
| ------ | :------------: | ------------------ | :------ |
| option | Option content | data: `OptionInfo` | 2.13.0  |

### Type definitions

The component exports the following types

```ts
import type { MentionInstance } from "@cedar-design/ui";
```

Mention reuses Input/Textarea typography and spacing; its measurement mirror copies computed native input styles. Override the corresponding input variables. Ineffective mention-font-size, mention-line-height and mention-padding-* variables are removed.

### Form field presentation and confirmation

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.
Text and person-ID models remain strings; use an empty string or a business-defined string sentinel.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

`data` accepts an array or (query, { signal }) => array/Promise. The component manages loading, cancellation and stale-result isolation; failures emit load-error. Single/multiple groups initialize with an empty query; searchable fields reload when queries change. Tree root loading is independent of existing load-more child loading.

Both input and textarea show manual loading and the current explicit data-loader wait. Loading feedback does not implicitly disable editing; search notification return Promises do not start tasks. Old data requests cannot clear the current request indicator, and load-error retains its original error payload.

---

Document: llms/en-US/components/menu.md

<!-- Source: src/menu/README.en-US.md; locale: en-US; page: /en/components/menu/ -->

# Menu

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `options`: Supplies the available options.

Example source: src/menu/__demos__/basic.vue

```vue
<template>
  <c-menu :options="options">
    <c-button variant="tonal" :elevation="false" aria-label="更多操作"><template #icon><c-icon-more /></template></c-button>
  </c-menu>
</template>

<script setup lang="ts">
const options = [
  { label: '编辑', value: 'edit' },
  { label: '复制', value: 'copy' },
  { type: 'divider' },
  { label: '删除', value: 'delete' },
]
</script>
```

## Appearance and states

### Disabled

- `disabled`: Prevents user interaction.

Example source: src/menu/__demos__/disabled.vue

```vue
<template>
  <c-space wrap>
    <c-menu disabled>
      <c-button disabled>菜单禁用</c-button>
      <template #content><c-menu-option label="Option 1" /></template>
    </c-menu>
    <c-menu>
      <c-button>选项禁用</c-button>
      <template #content>
        <c-menu-option label="可用选项" />
        <c-menu-option label="禁用选项" disabled />
        <c-menu-option label="另一个可用选项" />
      </template>
    </c-menu>
  </c-space>
</template>
```

## Options and hierarchy

### Groups, submenus and option content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `options` | Command tree | Groups, submenus and option content, Active Rendering |
| `hide-on-select` | Close the popup after activating a command | Active Rendering |
| `submenu-trigger` | How every submenu level expands | Active Rendering |
<!-- demo-config-notes:end -->


Compare flat groups, nested menus and option content. Expand or select options to inspect their hierarchy.

Example source: src/menu/__demos__/structure-comparison.vue

```vue
<script setup lang="ts">
import { h } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const options = [
  { type: 'group', label: '文件操作', children: [{ label: '新建', value: 'new' }, { label: '打开', value: 'open' }] },
  { type: 'group', label: '编辑操作', children: [{ label: '复制', value: 'copy' }, { label: '粘贴', value: 'paste' }] },
]
return { options }
})())

const scene2 = demoProxyRefs((() => {

const options = [
  { label: '首页', value: 'home' },
  { label: '产品', children: [
    { label: '产品概览', value: 'overview' },
    { label: '解决方案', children: [{ label: '企业版', value: 'enterprise' }, { label: '团队版', value: 'team' }] },
  ] },
  { label: '关于我们', value: 'about' },
]
return { options }
})())

const scene3 = demoProxyRefs((() => {


const icon = (text: string) => h('span', { 'aria-hidden': 'true' }, text)

const options = [
  { label: '编辑', value: 'edit', icon: icon('✎'), extra: '⌘ E' },
  { label: ({ active }: { active: boolean }) => h('strong', active ? '已选中复制' : '复制'), value: 'copy', icon: icon('⧉'), extra: '⌘ C' },
  { label: '删除', value: 'delete', icon: icon('⌫'), extra: '⌫', disabled: true },
]
return { icon, options }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="group">
    <h4><span lang="zh-CN">选项分组</span><span lang="en-US">group</span></h4>
    <c-menu :options="scene1.options">
        <c-button>选项分组</c-button>
      </c-menu>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="submenu">
    <h4><span lang="zh-CN">多级菜单</span><span lang="en-US">submenu</span></h4>
    <c-menu :options="scene2.options">
        <c-button>多级菜单</c-button>
      </c-menu>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="option-content">
    <h4><span lang="zh-CN">自定义选项内容</span><span lang="en-US">option content</span></h4>
    <c-menu :options="scene3.options">
        <c-button>自定义选项内容</c-button>
      </c-menu>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Active Rendering

- `options`: Supplies the available options.

Example source: src/menu/__demos__/active-rendering.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { MenuRenderContext } from '@cedar-design/ui'

const selectedValue = ref('account')
const status = ({ active }: MenuRenderContext) => active ? '当前项已选中' : '当前项未选中'
const options = [
  { label: '设置', value: 'settings', extra: status, children: [
    { label: '账户', value: 'account', extra: status },
    { label: '通知', value: 'notifications', extra: status },
  ] },
  { label: '帮助', value: 'help', extra: status },
]
const helpLabel = ({ active }: MenuRenderContext) => active ? '帮助（已选中）' : '帮助（未选中，仅视觉强调）'
</script>

<template>
  <p>当前值：{{ selectedValue }}。默认选中“账户”；父分支“设置”处于选中路径，但 active=false。</p>
  <c-space wrap>
    <c-menu v-model="selectedValue" :options="options" :hide-on-select="false" submenu-trigger="click">
      <c-button>渲染函数中的 active</c-button>
    </c-menu>
    <c-menu v-model="selectedValue" :options="options" :hide-on-select="false" submenu-trigger="click">
      <c-button>作用域插槽中的 active</c-button>
      <template #option-extra="{ active }">
        <c-tag :status="active ? 'primary' : 'default'">{{ active ? '当前项已选中' : '当前项未选中' }}</c-tag>
      </template>
    </c-menu>
    <c-menu v-model="selectedValue" :hide-on-select="false">
      <c-button>自定义子项与 highlight</c-button>
      <template #content>
        <c-menu-option value="account">
          <template #default="{ active }">账户：{{ active ? '已选中' : '未选中' }}</template>
        </c-menu-option>
        <c-menu-option value="help" :label="helpLabel" highlight />
      </template>
    </c-menu>
  </c-space>
</template>
```

## Triggers and positioning

### Context Menu

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `trigger` | Root menu trigger | Context Menu, Trigger |
| `options` | Command tree | Context Menu, Positioning |
| `align-point` | Align to the pointer position at activation; stays in place until the next context menu activation | Context Menu |
| `placement` | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Placement |
| `strategy` | Positioning strategy inherited by every submenu | Positioning |
| `submenu-trigger` | How every submenu level expands | Positioning |
<!-- demo-config-notes:end -->


- `options`: Supplies the available options.

Example source: src/menu/__demos__/context-menu.vue

```vue
<script setup lang="ts">
const options = [
  { label: 'Option 1', value: 'option-1' },
  { label: 'Option 2', value: 'option-2' },
  { label: 'Option 3', value: 'option-3' },
]
</script>

<template>
  <c-menu trigger="contextMenu" align-point :options="options" style="display: block">
    <div class="c-menu-context-target">右键点击</div>
  </c-menu>
</template>

<style scoped>
.c-menu-context-target {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 160px;
  background-color: var(--c-sys-color-surface-muted);
}
</style>
```

### Trigger

Preview configuration: `trigger="click"`, `label="Option 1"`, `label="Option 2"`, `trigger="hover"`.

Example source: src/menu/__demos__/trigger.vue

```vue
<template>
  <c-space wrap>
    <c-menu trigger="click">
      <c-button>点击触发</c-button>
      <template #content>
        <c-menu-option label="Option 1" />
        <c-menu-option label="Option 2" />
      </template>
    </c-menu>
    <c-menu trigger="hover">
      <c-button>悬浮触发</c-button>
      <template #content>
        <c-menu-option label="Option 1" />
        <c-menu-option label="Option 2" />
      </template>
    </c-menu>
  </c-space>
</template>
```

### Placement

- `placement`: Chooses the position relative to the trigger.

Example source: src/menu/__demos__/placement.vue

```vue
<template>
  <c-space wrap>
    <c-menu placement="bottom-start">
      <c-button>Bottom Left</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="bottom">
      <c-button>Bottom</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="bottom-end">
      <c-button>Bottom Right</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="top-start">
      <c-button>Top Left</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="top">
      <c-button>Top</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>

    <c-menu placement="top-end">
      <c-button>Top Right</c-button>
      <template #content>
        <c-menu-option>Option 1</c-menu-option>
        <c-menu-option>Option 2</c-menu-option>
        <c-menu-option>Option 3</c-menu-option>
      </template>
    </c-menu>
  </c-space>
</template>
```

### Positioning

- `options`: Supplies the available options.

Example source: src/menu/__demos__/positioning.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { MenuStrategy } from '@cedar-design/ui'

const strategy = ref<MenuStrategy>('fixed')
const options = [
  { label: '操作', children: [
    { label: '导出', children: [
      { label: 'CSV', value: 'csv' },
      { label: 'JSON', value: 'json' },
    ] },
    { label: '复制', value: 'copy' },
  ] },
]
</script>

<template>
  <c-space direction="column">
    <c-button @click="strategy = strategy === 'fixed' ? 'absolute' : 'fixed'">
      切换定位：{{ strategy }}
    </c-button>
    <c-menu :strategy="strategy" :options="options" submenu-trigger="click">
      <c-button>打开三级菜单</c-button>
      <template #footer>
        <c-button variant="text" @click.stop="strategy = strategy === 'fixed' ? 'absolute' : 'fixed'">
          展开时切换：{{ strategy }}
        </c-button>
      </template>
    </c-menu>
    <small>所有层级继承同一定位策略；挂载容器仍由 popup-container 单独控制。</small>
  </c-space>
</template>
```

### Popup Height

Preview configuration: `:popup-max-height="120"`, `:label="item"`, `:popup-max-height="false"`.

Example source: src/menu/__demos__/popup-height.vue

```vue
<template>
  <c-space wrap>
    <c-menu :popup-max-height="120">
      <c-button>限制为 120px</c-button>
      <template #content>
        <c-menu-option v-for="item in options" :key="item" :label="item" />
      </template>
    </c-menu>
    <c-menu :popup-max-height="false">
      <c-button>不限制高度</c-button>
      <template #content>
        <c-menu-option v-for="item in options" :key="item" :label="item" />
      </template>
    </c-menu>
  </c-space>
</template>

<script lang="ts" setup>
const options = Array.from({ length: 8 }, (_, index) => `Option ${index + 1}`);
</script>
```

## State and content customization

### Selection

- `options`: Supplies the available options.

Example source: src/menu/__demos__/selection.vue

```vue
<template>
  <c-space direction="column">
    <c-menu v-model="active" :options="options" @select="handleSelect">
      <c-button>{{ selectedLabel || "请选择操作" }}</c-button>
    </c-menu>
    <span
      >当前值：{{ active || "-" }}，最近选择：{{ selectedLabel || "-" }}</span
    >
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const active = ref("edit");
const selectedLabel = ref("编辑");
const options = [
  { label: '编辑', value: 'edit' },
  { label: '复制', value: 'copy' },
  { label: '删除', value: 'delete' },
]

const handleSelect = (_value: unknown, option: { label?: string | number }) => {
  selectedLabel.value = String(option.label ?? "");
};
</script>
```

### Controlled

Preview configuration: `v-model:open="open"`, `label="Option 1"`, `label="Option 2"`.

Example source: src/menu/__demos__/controlled.vue

```vue
<template>
  <c-space direction="column">
    <c-button @mousedown.stop @click.stop="open = !open">{{
      open ? "关闭菜单" : "打开菜单"
    }}</c-button>
    <c-menu v-model:open="open">
      <c-button>菜单触发器</c-button>
      <template #content>
        <c-menu-option label="Option 1" />
        <c-menu-option label="Option 2" />
      </template>
    </c-menu>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const open = ref(false);
</script>
```

### Footer

Example source: src/menu/__demos__/footer.vue

```vue
<template>
  <c-menu>
    <c-button>页脚</c-button>
    <template #content>
      <c-menu-option>Option 1</c-menu-option>
      <c-menu-option>Option 2</c-menu-option>
    </template>
    <template #footer>
      <div style="padding: 8px 12px">自定义页脚</div>
    </template>
  </c-menu>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Submenus and horizontal parent/child navigation follow the current reading direction. Vertical and boundary navigation keeps item order and skips disabled items. Portals inherit their source direction; switching direction preserves selection.

## API

### Value and default value

Use ordinary `v-model`. `modelValue` is the selected option value; `defaultValue` initializes uncontrolled state once, and later changes do not reset it. Explicit binding takes precedence. Initialization emits no `update:modelValue`.

### `<Menu>` Props

| Parameter | Description | Type | Default |
| --- | --- | --- | :---: |
| options | Command tree | `MenuOptionData[]` | `[]` |
| field-names | `label/value/children/disabled` field mapping | `MenuFieldNames` | `-` |
| model-value **(v-model)** | Current active value for controlled highlighting | `MenuValue` | `-` |
| open **(v-model)** | Whether the popup is visible | `boolean` | `-` |
| default-open | Uncontrolled default visibility | `boolean` | `false` |
| trigger | Root menu trigger | `'hover' \| 'click' \| 'focus' \| 'contextMenu'` | `'click'` |
| submenu-trigger | How every submenu level expands | `'hover' \| 'click'` | `'hover'` |
| placement | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `MenuPlacement` | `'bottom'` |
| `strategy` | Positioning strategy inherited by every submenu | `'absolute' \| 'fixed'` | `'absolute'` |
| popup-container | Popup mount container | `string \| HTMLElement \| false` | `-` |
| popup-max-height | Default limit, pixel height, or unlimited | `boolean \| number` | `true` |
| hide-on-select | Close the popup after activating a command | `boolean` | `true` |
| auto-fit-popup-width | Match popup width to the trigger | `boolean` | `false` |
| disabled | Disable the menu | `boolean` | `false` |
| align-point | Align to the pointer position at activation; stays in place until the next context menu activation | `boolean` | `false` |

### `MenuOptionData`

| Field | Description | Type |
| --- | --- | --- |
| type | Plain command, group or divider | `'item' \| 'group' \| 'divider'` |
| label | Main content | `VNodeChild \| (context) => VNodeChild` |
| icon | Leading icon | `VNodeChild \| (context) => VNodeChild` |
| extra | Trailing content such as a shortcut | `VNodeChild \| (context) => VNodeChild` |
| value | Value passed to events on activation | `any` |
| children | Child commands; a plain option with children becomes a submenu | `MenuOptionData[]` |
| disabled | Disable this item and its descendants | `boolean` |
| show | Whether to render | `boolean` |
| ripple | Whether to show the click ripple | `boolean` |
| props | HTML attributes forwarded to the row element | `HTMLAttributes` |

The render context is `{ option, active, level }`. `type: 'group'` is visual only and does not add a level; `type: 'divider'` is neither focusable nor activatable.

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:model-value | Active value update request | `value: MenuValue` |
| open-change | Visibility update request | `open: boolean` |
| select | A menu item was activated | `value, option, event` |

### Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| default | Trigger element | - |
| content | Hand-written content, pairs with `MenuOption` | - |
| footer | Footer | - |
| option-label | Render every option's main content | `{ option, active, level }` |
| option-icon | Render every option's icon | `{ option, active, level }` |
| option-extra | Render every option's trailing content | `{ option, active, level }` |

### `<MenuOption>`

Retained for SplitButton and a few handwritten `content` cases. Props are `label`, `value`, `disabled`, `ripple` and `highlight`. The `label` render function and `default`/`icon`/`suffix` slots receive `{ option, active, level }`. Clicking emits `click`. `highlight` controls visual emphasis without committing selection. Groups/submenus are described only through `options`; `MenuGroup` and `MenuSubmenu` are no longer exported.

### Instance methods and keyboard

The instance exposes `open()`, `close()`, `resize()` and `setReference(reference?)`. Root menus support Up/Down, Home/End and Enter. Right enters submenus; Left/Escape returns. Each Escape closes only the topmost layer and restores focus.

Classes, CSS variables and internal DOM markers consistently use `c-menu-*`, `--c-menu-*` and `data-menu-*`.

### State and duration variables

Disabled overrides selection, pointer hover and keyboard focus. Selected hover uses a separate role, inheriting the selected background by default; override it for additional feedback. Both platforms paint selected backgrounds directly on options.

| Token | Default |
| --- | --- |
| `--c-menu-option-bg-selected-hover` | `var(--c-menu-option-bg-selected)` |

### Data identity and trigger switching

Reorderable items should provide stable unique values; internal Vue keys derive from business values. Numeric `0`, string `'0'` and boolean `false` remain distinct. Groups, separators and display items without values retain identity through their original option objects; no public key alias is added. Clicking another sibling trigger that is already hover-open closes the previous menu. Clicking inside a submenu does not incorrectly close its parent.


### Placement semantics and configuration

MenuPlacement uses the twelve-value TriggerPlacement domain. Both prop and type describe the preferred popup side relative to its trigger. The old MenuPosition export has been removed.

---

Document: llms/en-US/components/message.md

<!-- Source: src/message/README.en-US.md; locale: en-US; page: /en/components/message/ -->

# Message

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/message/__demos__/basic.vue

```vue
<template>
  <c-button @click="handleClick">Info Message</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    return {
      handleClick() {
        Message.info("This is an info message");
      },
    };
  },
});
</script>
```

## Appearance and states

### Type

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Semantic status | Appearance Lab |
| `position` | Region of the message itself in the viewport: top/center/bottom, default top. Not positioned relative to a trigger | Appearance Lab |
| `closable` | Show the close button | Appearance Lab |
| `duration` | Auto-close duration in ms; `0` disables automatic closing | Appearance Lab |
| `variant` | Visual emphasis | Appearance Lab |
<!-- demo-config-notes:end -->


Example source: src/message/__demos__/type.vue

```vue
<template>
  <div>
    <c-space>
      <c-button @click="() => Message.info('This is an info message!')"
        >Info Message</c-button
      >
      <c-button
        @click="() => Message.success('This is a success message!')"
        status="success"
        >Success Message
      </c-button>
      <c-button
        @click="() => Message.warning('This is a warning message!')"
        status="warning"
        >Warning Message
      </c-button>
      <c-button
        @click="() => Message.error('This is an error message!')"
        status="danger"
        >Error Message</c-button
      >
    </c-space>
  </div>
  <div style="margin-top: 20px">
    <c-space>
      <c-button @click="() => Message('This is a default message!')"
        >Default Message</c-button
      >
      <c-button
        @click="
          () =>
            Message({
              content: 'This is a default message!',
              icon: renderIcon,
            })
        "
        >Default Message With Icon
      </c-button>
      <c-button @click="handleLoading" status="primary"
        >Loading Message
      </c-button>
    </c-space>
  </div>
</template>

<script lang="ts">
import { defineComponent, h } from "vue";
import { IconExclamationCircleFill } from "@cedar-design/icons-vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const renderIcon = () => h(IconExclamationCircleFill);

    const handleLoading = () => {
      const message = Message.loading("This is a loading message!");
      setTimeout(() => {
        message.close();
        Message.success("Loaded");
      }, 2000);
    };

    return {
      renderIcon,
      handleLoading,
      Message,
    };
  },
});
</script>
```

### Variant

Example source: src/message/__demos__/variant.vue

```vue
<script setup lang="ts">
import { Message } from "@cedar-design/ui";

const variants = ["neutral", "tonal", "solid"] as const;
</script>

<template>
  <c-space wrap>
    <c-button
      @click="Message.success({ content: 'neutral (default)', closable: true })"
      >neutral (default)</c-button
    >
    <c-button
      v-for="variant in variants"
      :key="variant"
      @click="Message.success({ content: variant, variant, closable: true })"
      >{{ variant }}</c-button
    >
  </c-space>
</template>
```

### Appearance Lab

- `status`: Selects the semantic state.

Example source: src/message/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const open = ref(false);
const __demoAppearance = __demoReactive({
  variant: "neutral",
  status: "default",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["neutral","tonal","solid"]},{"name":"status","values":["default","info","success","warning","danger","loading"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'neutral', value: 'neutral' },
            { label: 'tonal', value: 'tonal' },
            { label: 'solid', value: 'solid' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
            { label: 'loading', value: 'loading' },
          ]"
          aria-label="status"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<c-space wrap><c-button v-for="sample in demoComparedOptions" :key="String(sample)" @click="() => { __demoAppearance[demoCompareAxis] = sample; open = true }">{{ demoCompareAxis }}={{ sample }}</c-button></c-space>
<c-message
      v-model:open="open"
      status="success"
      position="center"
      closable
      :duration="0"
      v-bind="__demoAppearance"
    >
      Declarative message
      <template #action>
        <c-button size="sm" variant="text" @click="open = false"
          >Close</c-button
        >
      </template>
    </c-message>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Layout and arrangement

### Location

Example source: src/message/__demos__/location.vue

```vue
<template>
  <c-space>
    <c-button
      @click="() => Message.info({ content: 'This is an info message!' })"
      >Top Message</c-button
    >
    <c-button
      @click="
        () =>
          Message.info({
            content: 'This is an info message!',
            position: 'bottom',
          })
      "
      >Bottom Message</c-button
    >
    <c-button
      @click="
        () =>
          Message.info({
            content: 'This is an info message!',
            position: 'center',
          })
      "
      >Center Message</c-button
    >
  </c-space>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    return {
      Message,
    };
  },
});
</script>
```

## Content and presentation

### Time

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Semantic status | Component |
| `position` | Region of the message itself in the viewport: top/center/bottom, default top. Not positioned relative to a trigger | Component |
| `closable` | Show the close button | Component |
| `duration` | Auto-close duration in ms; `0` disables automatic closing | Component |
<!-- demo-config-notes:end -->


Example source: src/message/__demos__/time.vue

```vue
<template>
  <c-button @click="handleClick">Duration 1000ms</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "This is an info message!",
        duration: 1000,
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

### Update

Example source: src/message/__demos__/update.vue

```vue
<template>
  <c-button @click="handleClick">Update Info Message</c-button>
</template>
<script lang="ts">
import { defineComponent, ref } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const index = ref(0);
    const handleClick = () => {
      Message.info({
        id: "myInfo",
        content: `This is an info message ${index.value++}`,
        duration: 2000,
        resetOnUpdate: true,
      });
    };
    return {
      index,
      handleClick,
    };
  },
});
</script>
```

### Pause On Hover

Example source: src/message/__demos__/pause-on-hover.vue

```vue
<template>
  <c-button @click="handleClick">Reset On Hover</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "Hover to pause auto close",
        duration: 3000,
        pauseOnHover: true,
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

### Component

- `status`: Selects the semantic state.

Example source: src/message/__demos__/component.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>

<template>
  <c-button status="primary" @click="open = true">Open Message</c-button>
  <c-message
    v-model:open="open"
    status="success"
    position="center"
    closable
    :duration="0"
  >
    Declarative message
    <template #action>
      <c-button size="sm" variant="text" @click="open = false">Close</c-button>
    </template>
  </c-message>
</template>
```

## Customization and slots

### Custom Icon

Example source: src/message/__demos__/custom-icon.vue

```vue
<template>
  <c-button @click="handleClick">Info Message</c-button>
</template>

<script lang="ts">
import { defineComponent, h } from "vue";
import { IconFaceSmileFill } from "@cedar-design/icons-vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "This is an info message!",
        icon: () => h(IconFaceSmileFill),
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

## Interaction and control

### Closable

Example source: src/message/__demos__/closable.vue

```vue
<template>
  <c-button @click="handleClick">Closeable Message</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      Message.info({
        content: "This is an info message!",
        closable: true,
      });
    };
    return {
      handleClick,
    };
  },
});
</script>
```

### Loading

Example source: src/message/__demos__/loading.vue

```vue
<template>
  <c-space>
    <c-button status="primary" @click="handleLoading">Loading</c-button>
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleLoading = () => {
      const message = Message.loading("This is a loading message");
      setTimeout(() => {
        message.close();
        Message.success("Loaded");
      }, 2000);
    };

    return {
      handleLoading,
    };
  },
});
</script>
```

Example source: src/message/__demos__/multiple.vue

```vue
<template>
  <c-button @click="handleClick">Multiple Messages</c-button>
</template>
<script lang="ts">
import { defineComponent } from "vue";
import { Message } from "@cedar-design/ui";

export default defineComponent({
  setup() {
    const handleClick = () => {
      const message1 = Message.info("Message 1");
      Message.success("Message 2");
      Message.warning("Message 3");
      setTimeout(() => {
        message1.close();
      }, 1000);
    };
    return {
      handleClick,
    };
  },
});
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Content, icon and close gaps follow reading direction. Direction changes preserve message type, timing and close semantics. Imperative calls use explicit or document direction.

## API

### Props / MessageOptions

| Prop | Description | Type | Default |
| --------------------- | -------------------------------------- | ------------------------------------------------------------ | --------------- |
| open / `v-model:open` | Controlled visibility | `boolean` | `false` |
| id | Unique queue identifier; the same id updates the existing instance | `string \| number` | Automatically generated |
| status | Semantic status | `default \| info \| success \| warning \| danger \| loading` | `default` |
| variant | Visual emphasis | `neutral \| tonal \| solid` | `neutral` |
| position | Region of the message itself in the viewport: top/center/bottom, default top. Not positioned relative to a trigger | `top \| center \| bottom` | `top` |
| content | Content | `MessageContent` | - |
| icon | Custom icon | `MessageContent` | - |
| action | Action-area content | `MessageContent` | - |
| duration | Auto-close duration in ms; `0` disables automatic closing | `number` | `3000` |
| showIcon | Whether to show the status icon | `boolean` | `true` |
| closable | Show the close button | `boolean` | `false` |
| pauseOnHover | Pause while hovered | `boolean` | `false` |
| resetOnUpdate | Whether same-id updates reset the complete duration | `boolean` | `false` |
| closeButtonAriaLabel | Close button label | `string` | `Close message` |
| popupContainer | Mount container; function-call queues are isolated by container and position | `string \| HTMLElement \| false` | `body` |

Function options additionally accept `onOpen / onOpened / onClose / onClosed`. Close callbacks receive the current `id`.

### Events

`update:open`, `open`, `opened`, `close`, and `closed`, emitted once per visibility cycle.

### Methods

| Method | Description |
| ------------------------------------------------- | ------------------------ |
| `Message(options \| string)` | Open a default message |
| `Message.info/success/warning/error/loading(...)` | Open a message with the corresponding status |
| `Message.clear(position?)` | Clear all messages or a specified position |
| `Message.setDefaultOptions(options)` | Set defaults for subsequent calls |
| `Message.resetDefaultOptions()` | Restore defaults |

Returns `{ close() }`. Repeated `close()` calls do not duplicate closing lifecycle events.

### Slots

`default`、`icon`、`action`。

## Public CSS variables

Visual variant is independent of status. neutral uses a neutral popup and status icon; tonal uses a low-emphasis status background with dark content; solid uses a high-emphasis fill and matching foreground. Cedar/Maple both default to neutral; explicit solid/tonal have matching visual semantics. default/loading solid retains a dark background, with the loading icon indicating progress. Both export MessageVariant; function calls, setDefaultOptions and same-id updates support variant.

Colors use `--c-message-{variant}-{status}-{bg|content-color|icon-color|border-color|close-color}`. bg sets the panel background; content-color sets body/action text unless separately styled; icon-color sets status icons; border-color sets borders; close-color sets close controls. With a custom background, verify all three foregrounds. Geometry retains platform density rather than forcing equal defaults. Variables must affect actual Teleport-container ancestors.

| Variable | Default |
| --- | --- |
| `--c-message-neutral-default-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-default-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-default-icon-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-default-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-default-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-info-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-info-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-info-icon-color` | `var(--c-sys-color-content-info)` |
| `--c-message-neutral-info-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-info-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-success-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-success-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-success-icon-color` | `var(--c-sys-color-content-success)` |
| `--c-message-neutral-success-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-success-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-warning-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-warning-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-warning-icon-color` | `var(--c-sys-color-content-warning)` |
| `--c-message-neutral-warning-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-warning-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-danger-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-danger-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-danger-icon-color` | `var(--c-sys-color-content-danger)` |
| `--c-message-neutral-danger-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-danger-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-neutral-loading-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-message-neutral-loading-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-neutral-loading-icon-color` | `var(--c-sys-color-content-brand)` |
| `--c-message-neutral-loading-border-color` | `var(--c-sys-color-border-default)` |
| `--c-message-neutral-loading-close-color` | `var(--c-sys-color-content-secondary)` |
| `--c-message-tonal-default-bg` | `var(--c-sys-color-surface-muted)` |
| `--c-message-tonal-default-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-default-icon-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-default-border-color` | `transparent` |
| `--c-message-tonal-default-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-info-bg` | `rgba(var(--c-blue-6), 0.12)` |
| `--c-message-tonal-info-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-info-icon-color` | `var(--c-sys-color-content-info)` |
| `--c-message-tonal-info-border-color` | `transparent` |
| `--c-message-tonal-info-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-success-bg` | `var(--c-color-success-light-1)` |
| `--c-message-tonal-success-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-success-icon-color` | `var(--c-sys-color-content-success)` |
| `--c-message-tonal-success-border-color` | `transparent` |
| `--c-message-tonal-success-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-warning-bg` | `var(--c-color-warning-light-1)` |
| `--c-message-tonal-warning-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-warning-icon-color` | `var(--c-sys-color-content-warning)` |
| `--c-message-tonal-warning-border-color` | `transparent` |
| `--c-message-tonal-warning-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-danger-bg` | `var(--c-color-danger-light-1)` |
| `--c-message-tonal-danger-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-danger-icon-color` | `var(--c-sys-color-content-danger)` |
| `--c-message-tonal-danger-border-color` | `transparent` |
| `--c-message-tonal-danger-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-loading-bg` | `var(--c-color-primary-light-1)` |
| `--c-message-tonal-loading-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-tonal-loading-icon-color` | `var(--c-sys-color-content-brand)` |
| `--c-message-tonal-loading-border-color` | `transparent` |
| `--c-message-tonal-loading-close-color` | `var(--c-sys-color-content-primary)` |
| `--c-message-solid-default-bg` | `#333` |
| `--c-message-solid-default-content-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-default-icon-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-default-border-color` | `transparent` |
| `--c-message-solid-default-close-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-info-bg` | `var(--c-sys-color-status-info)` |
| `--c-message-solid-info-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-info-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-info-border-color` | `transparent` |
| `--c-message-solid-info-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-success-bg` | `var(--c-sys-color-status-success)` |
| `--c-message-solid-success-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-success-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-success-border-color` | `transparent` |
| `--c-message-solid-success-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-warning-bg` | `var(--c-sys-color-status-warning)` |
| `--c-message-solid-warning-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-warning-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-warning-border-color` | `transparent` |
| `--c-message-solid-warning-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-danger-bg` | `var(--c-sys-color-status-danger)` |
| `--c-message-solid-danger-content-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-danger-icon-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-danger-border-color` | `transparent` |
| `--c-message-solid-danger-close-color` | `var(--c-sys-color-content-on-bright)` |
| `--c-message-solid-loading-bg` | `#333` |
| `--c-message-solid-loading-content-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-loading-icon-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-solid-loading-border-color` | `transparent` |
| `--c-message-solid-loading-close-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-message-wrapper-margin-top` | `var(--c-spacing-12)` |
| `--c-message-wrapper-margin-bottom` | `var(--c-spacing-12)` |
| `--c-message-wrapper-padding-horizontal` | `var(--c-spacing-5)` |
| `--c-message-z-index` | `var(--c-z-index-message)` |
| `--c-message-padding-top` | `var(--c-spacing-5)` |
| `--c-message-padding-bottom` | `var(--c-spacing-5)` |
| `--c-message-padding-left` | `var(--c-spacing-7)` |
| `--c-message-padding-right` | `var(--c-spacing-7)` |
| `--c-message-margin-bottom` | `var(--c-spacing-7)` |
| `--c-message-border-radius` | `var(--c-border-radius-sm)` |
| `--c-message-icon-font-size` | `20px` |
| `--c-message-content-font-size` | `var(--c-font-size-body-3)` |
| `--c-message-icon-margin-right` | `var(--c-spacing-4)` |
| `--c-message-box-shadow` | `var(--c-shadow2-down)` |
| `--c-message-border-width` | `1px` |
| `--c-message-border-style` | `solid` |
| `--c-message-close-icon-font-size` | `12px` |
| `--c-message-close-btn-margin-left` | `var(--c-spacing-4)` |
| `--c-message-close-icon-hover-size` | `20px` |
| `--c-message-close-icon-hover-opacity` | `0.08` |
| `--c-message-transition-duration` | `var(--c-transition-duration-1)` |
| `--c-message-transition-duration-icon` | `var(--c-transition-duration-4)` |
| `--c-message-transition-timing-function` | `var( --c-transition-timing-function-linear )` |
| `--c-message-transition-timing-function-icon` | `var( --c-transition-timing-function-overshoot )` |

A throwing close/closed notification cannot retain the closed item or its empty manager host. Resources are released independently of notification callbacks.

---

Document: llms/en-US/components/nav-menu.md

<!-- Source: src/nav-menu/README.en-US.md; locale: en-US; page: /en/components/nav-menu/ -->

# Nav Menu

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `options`: Supplies the available options.

Example source: src/nav-menu/__demos__/basic.vue

```vue
<template>
  <div class="nav-menu-demo">
    <c-nav-menu v-model="selected" :options="options" />
    <p>当前页面：{{ selected }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { options } from "./data";

const selected = ref<string | number | null>(0);
</script>

<style scoped>
.nav-menu-demo {
  width: 240px;
  max-width: 100%;
}
</style>
```

Example source: src/nav-menu/__demos__/horizontal-sub-menu.vue

```vue
<template>
  <div class="nav-menu-demo">
    <c-nav-menu v-model="selected" mode="horizontal" :options="options" />
    <p>当前页面：{{ selected }}</p>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { options } from "./data";

const selected = ref<string | number | null>("cloud");
</script>

<style scoped>
.nav-menu-demo {
  min-height: 180px;
}
</style>
```

## Appearance and layout

### Size

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `options` | Navigation tree | Size |
| `size` | Size | Size |
| `mode` | Navigation orientation | Size |
<!-- demo-config-notes:end -->


- `options`: Supplies the available options.
- `size`: Controls the component size.

Example source: src/nav-menu/__demos__/size.vue

```vue
<template>
  <div v-for="size in sizes" :key="size" style="margin-bottom: 16px">
    <p>尺寸：{{ size }}</p>
    <c-nav-menu :options="options" :size="size" mode="horizontal" />
  </div>
</template>
<script setup lang="ts">
import { options } from './data'
const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
</script>
```

## Hierarchy and responsive layout

### Sub Menu

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `options` | Navigation tree | Sub Menu |
| `accordion` | Expand only one branch per level | Sub Menu |
| `default-value` | Initial uncontrolled selected value | Sub Menu |
| `collapsed` | Collapsed state; supports v-model:collapsed | Sub Menu |
| `mode` | Navigation orientation | Sub Menu |
<!-- demo-config-notes:end -->


- `options`: Supplies the available options.

Example source: src/nav-menu/__demos__/sub-menu.vue

```vue
<template>
  <c-nav-menu :options="options" accordion default-value="compute" />
</template>
<script setup lang="ts">
import { options } from './data'

</script>
```

Example source: src/nav-menu/__demos__/collapsed.vue

```vue
<template>
  <div class="nav-menu-demo">
    <c-button @click="collapsed = !collapsed">{{
      collapsed ? "展开菜单" : "折叠菜单"
    }}</c-button>
    <c-nav-menu
      :options="options"
      :collapsed="collapsed"
      default-value="cloud"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { options } from "./data";

const collapsed = ref(false);
</script>

<style scoped>
.nav-menu-demo {
  display: grid;
  justify-items: start;
  gap: 12px;
  width: 240px;
  max-width: 100%;
}

.nav-menu-demo :deep(.c-nav-menu) {
  width: 100%;
}
</style>
```

Example source: src/nav-menu/__demos__/breakpoint.vue

```vue
<template>
  <div class="nav-menu-demo">
    <p>拖动虚线容器右下角，观察菜单项收入“更多”。</p>
    <div class="nav-menu-demo__resizable">
      <c-nav-menu :options="options" mode="horizontal" />
    </div>
  </div>
</template>

<script setup lang="ts">
import { options } from "./data";
</script>

<style scoped>
.nav-menu-demo p {
  margin-top: 0;
}

.nav-menu-demo__resizable {
  width: 520px;
  max-width: 100%;
  min-width: 240px;
  min-height: 180px;
  overflow: auto;
  resize: horizontal;
  border-right: 1px dashed var(--c-color-border-2);
  border-bottom: 1px dashed var(--c-color-border-2);
}
</style>
```

## Entries and panels

### Items Horizontal

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `mode` | Navigation orientation | Items Horizontal |
| `active-item` | Controlled named NavMenu.Item activation; supports v-model:active-item | Items Horizontal |
<!-- demo-config-notes:end -->


Preview configuration: `mode="horizontal"`, `label="分类"`, `:options="categories"`, `label="地区"`.

Example source: src/nav-menu/__demos__/items-horizontal.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import type { NavMenuKey, NavMenuOption } from '..'

const category = ref<NavMenuKey | null>(null)
const region = ref<NavMenuKey | null>(null)
const keyword = ref('')
const appliedKeyword = ref('')
const categories: NavMenuOption[] = [
  { key: 'all', label: '全部分类' },
  { key: 'design', label: '设计资源' },
  { key: 'development', label: '开发工具' },
]
const regions: NavMenuOption[] = [
  { key: 'all', label: '全部地区' },
  { key: 'east', label: '华东' },
  { key: 'south', label: '华南' },
  { key: 'north', label: '华北' },
]
const categoryLabel = computed(() => categories.find((item) => item.key === category.value)?.label ?? '未选择')
const regionLabel = computed(() => regions.find((item) => item.key === region.value)?.label ?? '未选择')
function resetFilters(close: () => void) {
  keyword.value = ''
  appliedKeyword.value = ''
  close()
}
function applyFilters(close: () => void) {
  appliedKeyword.value = keyword.value.trim()
  close()
}
</script>
<template>
  <div>
    <c-nav-menu mode="horizontal">
      <c-nav-menu-item v-model="category" label="分类" :options="categories" />
      <c-nav-menu-item
        v-model="region"
        label="地区"
        :options="regions"
        options-mode="horizontal"
        popup-layout="full-width"
      />
      <c-nav-menu-item label="更多筛选" :highlight="!!appliedKeyword" popup-layout="full" :hide-on-select="false">
        <template #content="{ close }">
          <div style="height: 100%; display: flex; flex-direction: column; gap: 16px">
            <div style="flex: 1; min-height: 0; overflow-y: auto">
              <c-space direction="column" style="width: 100%">
                <strong>按关键词筛选</strong>
                <c-input v-model="keyword" placeholder="输入资源名称" aria-label="资源名称" />
              </c-space>
            </div>
            <c-space>
              <c-button @click="resetFilters(close)">重置</c-button>
              <c-button @click="applyFilters(close)">应用</c-button>
            </c-space>
          </div>
        </template>
      </c-nav-menu-item>
    </c-nav-menu>
    <p aria-live="polite">分类：{{ categoryLabel }}；地区：{{ regionLabel }}；关键词：{{ appliedKeyword || '不限' }}</p>
  </div>
</template>
```

Example source: src/nav-menu/__demos__/items-vertical.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import type { NavMenuKey, NavMenuOption } from '../types'

const section = ref<NavMenuKey | null>('overview')
const project = ref<NavMenuKey | null>(null)
const keyword = ref('')
const appliedKeyword = ref('')
const projects: NavMenuOption[] = [
  { key: 'website', label: '官网改版' },
  { key: 'dashboard', label: '数据平台' },
  { key: 'archived', label: '已归档项目', disabled: true },
]
const projectLabel = computed(() => projects.find(item => item.key === project.value)?.label ?? '未选择')
</script>

<template>
  <div class="vertical-items-demo">
    <c-nav-menu v-model:active-item="section" mode="vertical" class="vertical-items-demo__menu">
      <c-nav-menu-item label="工作概览" name="overview" />
      <c-nav-menu-item label="我的任务" name="tasks" />
      <c-nav-menu-item
        v-model="project"
        label="选择项目"
        :options="projects"
        options-mode="vertical"
        placement="right-start"
      />
      <c-nav-menu-item
        label="高级筛选"
        :highlight="!!appliedKeyword"
        popup-layout="full-height"
        placement="right-start"
        :popup-style="{ width: 'min(360px, 100vw)' }"
      >
        <template #content="{ close }">
          <c-space direction="column" style="width: 100%; height: 100%">
            <h3>任务筛选</h3>
            <p>应用后高亮入口，保留“高级筛选”标题。</p>
            <c-input v-model="keyword" placeholder="输入任务关键词" aria-label="任务关键词" />
            <c-space>
              <c-button @click="appliedKeyword = keyword.trim(); close()">应用</c-button>
              <c-button @click="keyword = ''; appliedKeyword = ''; close()">重置</c-button>
              <c-button @click="close()">关闭</c-button>
            </c-space>
          </c-space>
        </template>
      </c-nav-menu-item>
    </c-nav-menu>
    <div aria-live="polite">
      <h3>{{ section === 'overview' ? '工作概览' : '我的任务' }}</h3>
      <p>当前项目：{{ projectLabel }}</p>
      <p>关键词：{{ appliedKeyword || '不限' }}</p>
      <p>页面入口互斥选中，项目和高级筛选独立控制。</p>
    </div>
  </div>
</template>

<style scoped>
.vertical-items-demo { display: flex; flex-wrap: wrap; gap: 24px; align-items: flex-start; }
.vertical-items-demo__menu { width: 200px; max-width: 100%; flex: none; }
</style>
```

Example source: src/nav-menu/__demos__/entry-state.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuKey } from '..'

const value = ref<NavMenuKey | null>(null)
const activeItem = ref<NavMenuKey | null>(null)
const highlight = ref<boolean | undefined>(undefined)
const options = [{ key: 0, label: '数字零' }, { key: '', label: '空字符串' }, { key: 'account', label: '账户' }]
const highlightText = () => highlight.value === undefined ? '跟随业务 active' : String(highlight.value)
</script>

<template>
  <c-space direction="column">
    <c-space wrap>
      <c-button @click="highlight = undefined">跟随业务状态</c-button>
      <c-button @click="highlight = true">强制强调</c-button>
      <c-button @click="highlight = false">取消强调</c-button>
      <c-button @click="value = null">清空主值</c-button>
      <c-button @click="value = 'missing'">设为未匹配值</c-button>
    </c-space>
    <p>独立入口主值：{{ JSON.stringify(value) }}；highlight：{{ highlightText() }}。</p>
    <c-nav-menu mode="horizontal" class="entry-state-menu">
      <c-nav-menu-item v-model="value" :options="options" :highlight="highlight">
        <template #label="{ active, open }">独立入口 active={{ active }} / open={{ open }}</template>
      </c-nav-menu-item>
    </c-nav-menu>
    <p>具名当前入口：{{ activeItem ?? '无' }}。只打开面板不会改变 activeItem；选择叶子项后才切换。</p>
    <c-nav-menu v-model:active-item="activeItem" mode="horizontal" class="entry-state-menu">
      <c-nav-menu-item name="first" :options="options">
        <template #label="{ active, open }">入口一 active={{ active }} / open={{ open }}</template>
      </c-nav-menu-item>
      <c-nav-menu-item name="second" :options="options">
        <template #label="{ active, open }">入口二 active={{ active }} / open={{ open }}</template>
      </c-nav-menu-item>
    </c-nav-menu>
  </c-space>
</template>

<style scoped>
.entry-state-menu {
  width: 100%;
  min-width: 0;
}
</style>
```

Example source: src/nav-menu/__demos__/item-label.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
import type { NavMenuKey } from "../types";

const options = [
  { key: 0, label: "全部分类" },
  { key: "design", label: "设计" },
  { key: "development", label: "开发" },
];
const activeItem = ref<NavMenuKey | null>(null);
const automatic = ref<NavMenuKey | null>(null);
const fixed = ref<NavMenuKey | null>(null);
const manual = ref<NavMenuKey | null>(null);
const manualLabel = ref("手动标题");
const appliedValue = ref<NavMenuKey | null>(null);
const automaticLabel = computed(
  () =>
    options.find((option) => option.key === automatic.value)?.label ?? "未选择",
);
const fixedLabel = computed(
  () => options.find((option) => option.key === fixed.value)?.label ?? "未选择",
);
const selectedLabel = computed(
  () =>
    options.find((option) => option.key === manual.value)?.label ?? "未选择",
);
const pending = computed(() => manual.value !== appliedValue.value);

function applyLabel() {
  if (manual.value === null) return;
  manualLabel.value = `当前：${selectedLabel.value}`;
  appliedValue.value = manual.value;
}

function reset() {
  manual.value = appliedValue.value = null;
  manualLabel.value = "手动标题";
}
</script>

<template>
  <div class="item-label-demo">
    <c-nav-menu v-model:active-item="activeItem" mode="horizontal">
      <c-nav-menu-item
        v-model="automatic"
        name="automatic"
        label="自动标题"
        :options="options"
      />
      <c-nav-menu-item v-model="fixed" name="fixed" :options="options">
        <template #label>固定标题</template>
      </c-nav-menu-item>
      <c-nav-menu-item v-model="manual" name="manual" :options="options">
        <template #label>{{ manualLabel }}</template>
      </c-nav-menu-item>
    </c-nav-menu>

    <div class="item-label-demo__status" aria-live="polite">
      <p>
        <strong>自动标题：</strong>选择后入口直接显示“{{ automaticLabel }}”。
      </p>
      <p>
        <strong>固定标题：</strong>入口始终显示“固定标题”，当前选择“{{
          fixedLabel
        }}”。
      </p>
      <p>
        <strong>手动标题：</strong>当前选择“{{ selectedLabel }}”，入口显示“{{
          manualLabel
        }}”。
        <span v-if="pending">选择尚未应用到标题。</span>
      </p>
    </div>

    <c-space wrap>
      <c-button :disabled="!pending || manual === null" @click="applyLabel">
        {{ pending ? `应用手动标题：${selectedLabel}` : "手动标题已同步" }}
      </c-button>
      <c-button @click="reset">重置手动标题</c-button>
    </c-space>

    <p class="item-label-demo__tip">
      当前激活入口：{{ activeItem ?? "暂无" }}。打开入口不会激活，选择叶子节点后才会统一切换高亮；各面板内部数据仍各自保留。
    </p>
  </div>
</template>

<style scoped>
.item-label-demo {
  display: grid;
  grid-template-columns: minmax(0, 1fr);
  min-width: 0;
  gap: 16px;
  min-height: 220px;
}

.item-label-demo__status {
  display: grid;
  gap: 8px;
}

.item-label-demo__status p,
.item-label-demo__tip {
  margin: 0;
}

.item-label-demo__tip {
  color: var(--c-color-text-3);
}
</style>
```

Example source: src/nav-menu/__demos__/item-label-independent.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import type { NavMenuKey, NavMenuOption } from '..'

const categories: NavMenuOption[] = [
  { key: 'design', label: '设计资源' },
  { key: 'development', label: '开发工具' },
  { key: 'document', label: '文档资料' },
]
const regions: NavMenuOption[] = [
  { key: 'east', label: '华东' },
  { key: 'south', label: '华南' },
  { key: 'north', label: '华北' },
]

const category = ref<NavMenuKey | null>('design')
const region = ref<NavMenuKey | null>('east')
const categoryLabel = computed(
  () => categories.find(option => option.key === category.value)?.label ?? '未选择',
)
const regionLabel = computed(
  () => regions.find(option => option.key === region.value)?.label ?? '未选择',
)
</script>

<template>
  <div class="item-label-independent-demo">
    <c-nav-menu mode="horizontal">
      <c-nav-menu-item v-model="category" label="选择分类" :options="categories" />
      <c-nav-menu-item v-model="region" label="选择地区" :options="regions" />
    </c-nav-menu>

    <div class="item-label-independent-demo__status" aria-live="polite">
      <p><strong>分类：</strong>{{ categoryLabel }}</p>
      <p><strong>地区：</strong>{{ regionLabel }}</p>
    </div>

    <c-space>
      <c-button :disabled="category === null" @click="category = null">清空分类</c-button>
      <c-button :disabled="region === null" @click="region = null">清空地区</c-button>
    </c-space>

    <p class="item-label-independent-demo__tip">
      两个 Item 未设置 name，各自根据选中值更新标题和高亮，互不清除；面板仍互斥展开。
    </p>
  </div>
</template>

<style scoped>
.item-label-independent-demo {
  display: grid;
  gap: 16px;
  min-height: 180px;
}

.item-label-independent-demo__status {
  display: flex;
  flex-wrap: wrap;
  gap: 8px 24px;
}

.item-label-independent-demo__status p,
.item-label-independent-demo__tip {
  margin: 0;
}

.item-label-independent-demo__tip {
  color: var(--c-color-text-3);
}
</style>
```

## Data and state control

### Controlled

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `options` | Navigation tree | Controlled |
| `model-value` | Current selected key; supports v-model. null means no selection | Controlled |
| `expanded-keys` | Controlled expanded branches | Controlled |
| `field-names` | Field mapping for key/label/children/disabled | Controlled |
| `disabled` | Globally disable selection/user expansion | Controlled |
| `default-value` | Initial uncontrolled selected value | Controlled |
<!-- demo-config-notes:end -->


- `options`: Supplies the available options.
- `disabled`: Prevents user interaction.

Example source: src/nav-menu/__demos__/controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuKey } from '../types'
import { options } from './data'
const selected = ref<NavMenuKey | null>(0)
const expanded = ref<NavMenuKey[]>([])
const acceptUpdates = ref(true)
const lastRequest = ref('尚未操作')
function select(key: NavMenuKey | null) {
  lastRequest.value = `请求选择：${key}`
  if (acceptUpdates.value) selected.value = key
}
function expand(keys: NavMenuKey[]) {
  lastRequest.value = `请求展开：${keys.join('、') || '无'}`
  if (acceptUpdates.value) expanded.value = keys
}
</script>
<template>
  <div>
    <c-button @click="acceptUpdates = !acceptUpdates">{{ acceptUpdates ? '当前接受更新，点击拒绝' : '当前拒绝更新，点击接受' }}</c-button>
    <c-nav-menu :options="options" :model-value="selected" :expanded-keys="expanded" @update:model-value="select" @update:expanded-keys="expand" />
    <p aria-live="polite">{{ lastRequest }}；实际选中：{{ selected }}；实际展开：{{ expanded.join('、') || '无' }}</p>
  </div>
</template>
```

Example source: src/nav-menu/__demos__/item-controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const accepted = ref(true)
const open = ref(false)
const value = ref<string | number | null>(null)
const options = [
  { key: 0, label: '不限' },
  { key: 'design', label: '设计' },
  { key: 'disabled', label: '禁用选项', disabled: true },
]
function updateOpen(next: boolean) {
  if (accepted.value) {
    open.value = next
  }
}
function updateValue(next: string | number | null) {
  if (accepted.value) {
    value.value = next
  }
}
</script>
<template>
  <c-button @click="accepted = !accepted">{{
    accepted ? '当前接受更新，点击拒绝' : '当前拒绝更新，点击接受'
  }}</c-button>
  <c-nav-menu>
    <c-nav-menu-item
      :open="open"
      :model-value="value"
      :options="options"
      label="受控筛选"
      @update:open="updateOpen"
      @update:model-value="updateValue"
    />
    <c-nav-menu-item label="禁用入口" disabled :options="options" />
  </c-nav-menu>
  <p>选中：{{ value ?? '未选择' }}；展开：{{ open }}</p>
</template>
```

Example source: src/nav-menu/__demos__/panel-state.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuInstance } from '..'

const menu = ref<NavMenuInstance>()
const unmountOnClose = ref(false)
const options = [{ key: 0, label: '不限' }, { key: 'design', label: '设计资源' }]
</script>
<template>
  <c-space direction="column" style="width: 100%">
    <c-space>
      <span>关闭后卸载</span>
      <c-switch v-model="unmountOnClose" />
      <c-button @click="menu?.close()">关闭当前面板</c-button>
    </c-space>
    <c-nav-menu ref="menu" mode="horizontal">
      <c-nav-menu-item label="草稿表单" :unmount-on-close="unmountOnClose">
        <template #content="{ close }">
          <c-space direction="column" style="width: 100%">
            <c-input default-value="" placeholder="输入后关闭，再打开查看草稿" aria-label="面板内部草稿" />
            <c-button @click="close">关闭并返回入口</c-button>
          </c-space>
        </template>
      </c-nav-menu-item>
      <c-nav-menu-item label="分类" :options="options" />
    </c-nav-menu>
    <p>默认保留面板内部草稿；开启卸载后再次展开会重新创建。关闭面板不会提交或重置业务筛选值。</p>
  </c-space>
</template>
```

Example source: src/nav-menu/__demos__/field-names.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { NavMenuOption } from '../types'
const disabled = ref(false)
const fieldNames = { key: 'id', label: 'name', children: 'items', disabled: 'unavailable' }
const options: NavMenuOption[] = [
  { type: 'group', name: '工作空间', items: [
    { id: 0, name: '概览' },
    { id: 'projects', name: '项目', items: [{ id: 'active', name: '进行中' }, { id: 'archived', name: '已归档', unavailable: true }] },
  ] },
  { type: 'divider' },
  { id: 'settings', name: '设置' },
  { id: 'hidden', name: '隐藏入口', show: false },
]
</script>
<template>
  <div>
    <c-button @click="disabled = !disabled">{{ disabled ? '启用菜单' : '禁用整个菜单' }}</c-button>
    <c-nav-menu :options="options" :field-names="fieldNames" :disabled="disabled" :default-value="0" default-expand-all />
  </div>
</template>
```

Example source: src/nav-menu/__demos__/custom-content.vue

```vue
<template>
  <c-nav-menu :options="options">
    <template #label="{ option, active }"><strong :style="{ fontWeight: active ? 700 : 400 }">{{ option.label }}</strong></template>
    <template #extra="{ option }"><c-tag v-if="option.key === 'inbox'">3</c-tag></template>
  </c-nav-menu>
</template>
<script setup lang="ts">
import { h } from 'vue'
import type { NavMenuOption } from '..'
const options: NavMenuOption[] = [
  { key: 'workspace', type: 'group', label: '工作空间', children: [
    { key: 'inbox', label: '收件箱' }, { key: 'docs', label: '文档', icon: h('span', '文') },
  ] },
  { type: 'divider' }, { key: 'settings', label: '设置' },
]
</script>
```

## NavMenu API

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| options | Navigation tree | NavMenuOption[] | [] |
| model-value | Current selected key; supports v-model. null means no selection | string / number / null | undefined |
| default-value | Initial uncontrolled selected value | string / number / null | null |
| active-item | Controlled named NavMenu.Item activation; supports v-model:active-item | string / number / null | undefined |
| default-active-item | Initial uncontrolled named NavMenu.Item activation | string / number / null | null |
| expanded-keys | Controlled expanded branches | (string / number)[] | undefined |
| default-expanded-keys | Initial uncontrolled expanded branches | (string / number)[] | [] |
| default-expand-all | Initially expand every branch | boolean | false |
| auto-expand-selected | Expand selected-item ancestors in vertical noncollapsed mode; controlled mode requests updates | boolean | true |
| accordion | Expand only one branch per level | boolean | false |
| mode | Navigation orientation | vertical / horizontal | vertical |
| collapsed | Collapsed state; supports v-model:collapsed | boolean | undefined |
| default-collapsed | Initial uncontrolled collapsed state | boolean | false |
| theme | Code Theme | light / dark | Inherit Sider, otherwise light |
| size | Size | xs / sm / md / lg / xl | md |
| disabled | Globally disable selection/user expansion | boolean | false |
| field-names | Field mapping for key/label/children/disabled | NavMenuFieldNames | Same-name fields by default |
| responsive | Enable horizontal overflow collection | boolean | true |
| indent | Indent per level in px | number | 24 |
| root-indent | Root indent in px | number | 12 |
| collapsed-width | Collapsed width in px | number | 56 |
| icon-size | Icon size in px | number | 20 |
| popup-container | Popup mount container; false renders locally | Matching Trigger type | Inherits Trigger definition |
| popup-class | Additional popup class | string / array / object | — |
| overflow-label | Overflow-entry label | string | More |
| node-props | Node DOM attributes/events; internal selection, disabled and keyboard semantics remain | (context) => Record<string, unknown> | — |

Controlled props follow supplied values; update events are requests only. `default-*` initializes once, not on later changes. Selection and expansion are independent. `showOption` does not select.

### NavMenuOption

```ts
interface NavMenuOption {
  key?: string | number
  type?: 'item' | 'group' | 'divider'
  label?: VNodeChild | ((context: NavMenuRenderContext) => VNodeChild)
  icon?: VNodeChild | ((context: NavMenuRenderContext) => VNodeChild)
  extra?: VNodeChild | ((context: NavMenuRenderContext) => VNodeChild)
  children?: NavMenuOption[]
  disabled?: boolean
  show?: boolean
  props?: HTMLAttributes
}
```

Ordinary options require unique stable keys, using mapped keys when fieldNames is supplied. Numeric 0 is valid. Groups/dividers may omit keys, though explicit keys are recommended for dynamic reordering. Duplicate keys/missing ordinary-item keys throw to prevent ambiguous selection paths. show=false hides nodes/subtrees. Disabled branches propagate downward. Ordinary branches expand; leaves select.

### Events

| Event | Arguments |
| --- | --- |
| update:model-value | key / null |
| update:active-item | name / null |
| update:expanded-keys | keys |
| update:collapsed | collapsed |
| select | key, original option, original Event |

### Slots

The default slot contains independent `CNavMenuItem` entries. When present, horizontal menus scroll rather than using `responsive` overflow collection.

label/icon/extra render functions, same-name slots and nodeProps receive `{ option, active, expanded, level }`. `active` means this node itself matches modelValue; ancestor-path emphasis is internal. `expanded` describes branch expansion; level starts at 0.

### Cross-platform contract

Both libraries create panel content on first open and retain it when closed or switched, including local drafts and expanded branches. With `unmount-on-close`, content is destroyed after the closing transition and recreated on the next open; the Item's own selected value remains intact. Applications own draft submission, resets and filter application.

Root `close()` requests closing Item panels and restores entry focus without changing selected values, active-item or desktop tree expanded-keys. Controlled open values remain authoritative when closure is rejected. Entries with neither options nor a content slot never open; asynchronous options follow the current open state when they arrive. KeepAlive suspension hides panels and requests closure; controlled state remains authoritative on activation.

Item values, open state, events, slot contexts and `select/close/setOpen` methods share the same contract. Both roots expose `close/resize/setActiveItem`. Names must be unique within the menu; changing a name releases the previous one. Batched swaps and insertions validate the final rendered names. Vertical options expand enabled ancestors of the selected value on initialization and value/options updates. Users can still collapse branches manually.

| Capability | Cedar | Maple |
| --- | --- | --- |
| Root menu | options tree or Item entries; vertical by default | Item filter bar only; horizontal by default |
| popup-layout | dropdown (default) / full-width / full-height / full | full-width (default) / full |
| Panel origin | Individual entry bottom | Entire filter bar bottom; standalone Item uses its own bottom |
| Trigger and placement | trigger / placement | Click to open downward |
| Backdrop and scrolling | Non-modal; background scroll remains available | Root overlay / overlay-closable / lock-scroll / esc-to-close / z-index |
| Theme | theme override | Global theme; no theme prop |
| Tree-only methods | showOption / scrollTo / setCollapsed | — |

Each library exports `NavMenuPopupLayout` with its supported values. Maple's `NavMenuMode` is horizontal only; `options-mode` supports both orientations. The default entry slot replaces the entry's inner content. Maple renders it inside a native button: use non-interactive text/icons and place forms and action buttons in the content slot.

### Methods

| Method | Description |
| --- | --- |
| close() | Request closing Item panels and restore focus without changing tree expansion |
| showOption(key?) | Expand ancestors of the specified item, defaulting to current selection; does not select |
| scrollTo(key?) | Expand then scroll to an item; controlled expansion requires parent acceptance |
| resize() | Manually remeasure horizontal overflow |
| setCollapsed(value) | Update uncontrolled collapse or request a controlled update |
| setActiveItem(value) | Update uncontrolled named-Item activation or request a controlled update |

### Arrow direction

Horizontal dropdowns point down when closed/up when open. Vertical inline branches point right/down. Right-opening submenus point right/left. Independent Item arrows follow placement and reverse when open. Arrows follow actual open state, not unaccepted controlled proposals.

### Keyboard

Vertical Up/Down and horizontal Left/Right move focus; Home/End reach first/last. Right expands vertical branches, Down opens horizontal branches, Left returns to parents. Escape closes the current popup and restores reference focus. Enter/Space activates nodes. Disabled nodes are skipped; inputs retain native keys. If narrowing moves a focused item into overflow, focus moves to the overflow entry.

## NavMenu.Item API

Titles follow matching selected options by default. `label` slots take highest precedence: use `<template #label>Advanced filters</template>` for fixed titles or bind a separate reactive variable for manual titles. `update-label` is removed.

`v-model` stores panel selection. Slot `active` indicates business entry state: named entries in a root menu compare root activeItem with name; independent entries match their main value against ordinary options, including 0/empty string. Unknown values/groups/dividers do not activate independent entries. `highlight` overrides emphasis only: true forces it, false removes it, omission follows `active`. It changes neither `active` nor value. Opening a panel does not activate the entry.

`CNavMenuItem` (also `NavMenu.Item`) is an independent top-level entry outside root navigation-tree `modelValue`. Without `name`, each Item highlights from its own value, allowing simultaneous category/region filters. With unique names, root `activeItem/defaultActiveItem` maintains one highlighted entry. Both modes allow only one open Item panel without clearing other panels’ values. Ordinary root navigation uses `options + v-model`. Entries define their own `options` or replace panels through `content`. default customizes the entry; `label`/`icon` customize parts; `option-label`/`option-icon`/`option-extra` customize `options`.

Horizontal menus with default slots scroll rather than collecting entries into overflow, avoiding cloned form content. Pure `options` menus retain automatic overflow collection. New Item does not support legacy child collection. Item panels within one NavMenu are mutually exclusive. Clicking another entry requests closing the previous one; controlled open requires parent acceptance.

| Item prop | Description | Default |
| --- | --- | --- |
| name | Stable unique entry identifier; root activeItem makes named entries mutually exclusive. highlight separately overrides appearance | — |
| label | Entry title when unselected or selection does not match options; supports VNode/render functions | — |
| options / fieldNames | Same options/field mappings as NavMenu | `[]` |
| model-value / default-value | Independent controlled/initial value; string, number or null | `undefined` / `null` |
| highlight | Visual emphasis override without changing active/selection; defaults to active | — |
| hide-on-select | Close the panel after select | `true` |
| unmount-on-close | Destroy panel content after the closing transition; retain it by default | false |
| open / default-open | Controlled / initial panel state | `undefined` / `false` |
| disabled | Disable the entry, also respecting parent menu disabled | `undefined` |
| trigger | Trigger mode | `click` |
| placement | Ordinary dropdown placement; full-height right/left placements align to the corresponding entry edge | `bottom-start` |
| popup-layout | `dropdown`: standard `dropdown` / `full-width`: `full` width below the trigger / `full-height`: `full` height on the right / `full`: fills the available width and height below the trigger | `dropdown` |
| popup-style | Panel CSS; may override full-height width/direction/dimensions | — |
| popup-container / popup-class | Trigger container and popup class | Follow parent menu |
| options-mode | Horizontal/vertical default options-panel layout | `vertical` |

Entry/`content` slots receive `{ modelValue, selectedOption, active, open, select, close }`. select(key,event?) emits `update:modelValue` and select(key,option,event). Custom panels may select outside options, making option undefined and independent active false; use highlight if emphasis is needed. `close()` closes/restores entry focus. Controlled values affect titles/active only after acceptance. Entry-slot active is entry state, while label-render active compares its context option with the Item value. `hideOnSelect` is independent of acceptance; set false for manual confirmation.

Item also emits `update:open`/entry `click` and exposes `select`/`close`/`setOpen`. Full-width/full-height popups are nonmodal without scroll locks/focus traps. They default to body; custom containers must avoid ancestor transforms changing the fixed-position reference.

## Migrating from older versions

Legacy child collection and state aliases are removed. New `NavMenu.Item` is an independent top-level entry with different usage.

| Previous usage | Current usage |
| --- | --- |
| Legacy Item/SubMenu/ItemGroup components | Use options/children/type=group for navigation trees; new NavMenu.Item for custom top-level entries |
| selectedKeys/defaultSelectedKeys arrays | modelValue/defaultValue single key |
| openKeys/defaultOpenKeys | expandedKeys/defaultExpandedKeys |
| menu-item-click | select(key, option, event) |
| pop/popButton mode | vertical + collapsed; horizontal remains horizontal |
| Child title/icon slots | Root scoped label/icon/extra slots or option VNodes |
| Built-in collapse button/breakpoint | External buttons control collapsed; containers handle responsive layout |
| Unrestricted triggerProps/tooltipProps forwarding | Explicit popupContainer/popupClass props |

All library demos, exports, global types and resolver entries are migrated. Styles use BEM `c-nav-menu__*` / `c-nav-menu--*`; old selectors and unused tokens are removed.

## Design reference

The workspace Naive UI 2.44.1 Menu informed option trees, ancestor paths and content rendering. No Naive UI/TreeMate runtime dependency is introduced. Local Trigger provides popups; public APIs follow Cedar names.

## Style variables

| Variable | Default |
| --- | --- |
| --c-nav-menu-font-size | `var(~'--c-font-size-body-3')` |
| --c-nav-menu-border-radius | `var(~'--c-border-radius-sm')` |
| --c-nav-menu-light-bg | `var(~'--c-color-bg-2')` |
| --c-nav-menu-light-item-bg-hover | `var(~'--c-color-fill-2')` |
| --c-nav-menu-light-item-bg-selected | `var(~'--c-color-fill-2')` |
| --c-nav-menu-light-item-text-color | `var(~'--c-color-text-2')` |
| --c-nav-menu-light-item-text-color-selected | `rgb(var(~'--c-primary-6'))` |
| --c-nav-menu-light-item-text-color-disabled | `var(~'--c-color-text-4')` |
| --c-nav-menu-dark-bg | `var(~'--c-color-menu-dark-bg')` |
| --c-nav-menu-dark-item-bg-hover | `var(~'--c-color-menu-dark-hover')` |
| --c-nav-menu-dark-item-bg-selected | `var(~'--c-color-menu-dark-hover')` |
| --c-nav-menu-dark-item-text-color | `var(~'--c-color-text-4')` |
| --c-nav-menu-dark-item-text-color-selected | `var(~'--c-color-white')` |
| --c-nav-menu-dark-item-text-color-disabled | `var(~'--c-color-text-2')` |
| --c-nav-menu-row-height | `40px` |
| --c-nav-menu-row-height-xs | `28px` |
| --c-nav-menu-row-height-sm | `32px` |
| --c-nav-menu-row-height-lg | `48px` |
| --c-nav-menu-row-height-xl | `56px` |
| --c-nav-menu-content-gap | `8px` |
| --c-nav-menu-content-padding | `12px` |
| --c-nav-menu-icon-size | `20px` |
| --c-nav-menu-arrow-size | `12px` |
| --c-nav-menu-focus-width | `2px` |
| --c-nav-menu-focus-offset | `-2px` |
| --c-nav-menu-divider-width | `1px` |
| --c-nav-menu-divider-color | `var(--c-color-border-2)` |
| --c-nav-menu-popup-min-width | `180px` |
| --c-nav-menu-popup-max-height | `320px` |
| --c-nav-menu-popup-shadow | `0 6px 24px rgb(0 0 0 / 12%)` |
| --c-nav-menu-motion-duration | `150ms` |
| --c-nav-menu-panel-width | `min(400px, 100vw)` |

`popup-layout="full"` starts at the bottom edge of the trigger, spans the viewport width and fills the remaining viewport height below it. On Maple, the same layout starts below the entire filter bar. Mobile defaults to full-width; desktop defaults to dropdown.


## Reading direction and keyboard interaction

NavMenu inherits the nearest native `dir` and reacts to changes. Horizontal navigation follows reading direction; vertical up/down navigation stays unchanged. Data-menu branches mirror expand/parent keys and prefer the inline-end side for nested popups. Popups retain the source direction. Explicit Item placement remains physical; changing direction does not select an item or clear filters.

---

Document: llms/en-US/components/notification.md

<!-- Source: src/notification/README.en-US.md; locale: en-US; page: /en/components/notification/ -->

# Notification

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/notification/__demos__/basic.vue

```vue
<template>
  <c-space>
    <c-button @click="handleNotification"> Open Notification </c-button>
  </c-space>
</template>
<script lang="ts" setup>
import { Notification } from '@cedar-design/ui'

const handleNotification = () => {
  Notification.info({
    title: 'Notification',
    content: 'This is a notification!',
  })
}
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Explicit left/right notification corners remain physical. Icons, content, close actions and footers follow reading direction. Imperative calls use explicit or document direction rather than borrowing another app context.

## API

clear immediately releases entries and IDs. Re-adding the same ID, even in the same update cycle, creates an independent internal instance and a fresh complete display timer. Ordinary active-ID updates remain in place. Internal keys are not public API. clear still does not add business onClose calls. Reduced-motion component styles disable opacity, left/right enter, appear and leave transitions and initial displacement without a global tiny-duration fallback. Static layout/colors and business display deadlines remain unchanged. Real OS/browser matrices require separate validation.

duration (default 3000ms; 0 stays open) is a business display timer, not CSS animation duration. close notifies once per mounted instance and immediately cancels timers. Updates/repeated closing during leave do not reschedule auto-close. reset-on-update restarts only active, unclosed instances. KeepAlive deactivation cancels timing; reactivation restarts the full configured duration. Unmounting/stale callbacks emit no delayed close. TransitionGroup unmounts after actual leave completion, independently of duration. Six transition-* tokens control opacity/left/right enter/leave without changing auto-close deadlines. Normal override checks are not real OS reduced-motion validation.

### `Notification` global methods

`Notification` global methods can be used in three ways:

1. Call `this.$notification`
2. In Composition API, call `getCurrentInstance().appContext.config.globalProperties.$notification`
3. Import `Notification` and call its methods directly

Import-based calls cannot obtain the current Vue Context. AppContext injections such as i18n or route
must be supplied manually in the call, or by configuring a global AppContext for the component.

```ts
import { createApp } from 'vue'
import { Notification } from '@cedar-design/ui'

const app = createApp(App)
Notification._context = app._context
```

### NotificationMethod

| Parameter | Description | Type | Default |
| ------- | ---------------------- | ------------------------------------------------------------------------------------------------ | :----: |
| info | Show an information notification | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` | `-` |
| success | Show a success notification | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` | `-` |
| warning | Show a warning notification | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` | `-` |
| error | Show an error notification | `(    config: string \| NotificationConfig,    appContext?: AppContext  ) => NotificationReturn` | `-` |
| remove | Clear the notification with the specified `id` | `(id: string) => void` | `-` |
| clear | Clear all notifications | `(position?: NotificationPosition) => void` | `-` |

### NotificationConfig

| Parameter | Description | Type | Default | Version |
| ---------------- | --------------------------- | ---------------------------------------------------- | :-----: | :----- |
| content | Content | `RenderContent` | `-` |  |
| title | Title | `RenderContent` | `-` |  |
| icon | Icon | `RenderFunction` | `-` |  |
| id | Unique id | `string` | `-` |  |
| style | Style | `CSSProperties` | `-` |  |
| class | Class name | `ClassName` | `-` |  |
| position | Physical corner of the notification itself in the viewport, default top-right. Corner values use vertical-first kebab-case spelling | `'top-left'\|'top-right'\|'bottom-left'\|'bottom-right'` | `top-right` |  |
| showIcon | Whether to show the icon | `boolean` | `true` |  |
| closable | Whether closable | `boolean` | `false` |  |
| duration | Display duration in `ms` | `number` | `3000` |  |
| footer | Footer content | `RenderFunction` | `-` | 2.25.0 |
| closeIcon | Close-button icon | `RenderFunction` | `-` |  |
| closeIconElement | Close-button element | `RenderFunction` | `-` |  |
| onClose | Close callback | `(id: number \| string) => void` | `-` |  |

### NotificationReturn

| Parameter | Description | Type | Default |
| ------ | ------------------ | ------------ | :----: |
| close | Close the current notification | `() => void` | `-` |

### Type definitions

The component exports the following types

```ts
import type { NotificationInstance, NotificationConfig, NotificationReturn } from '@cedar-design/ui'
```

## Public CSS variables

Panels use surface-overlay; body/title use content-primary; close buttons use content-secondary; borders use border-default. Status icons use readable status content colors: info no longer uses brand fills, and loading uses content-brand. Colors are grouped by status. Custom backgrounds require checking content/icon/close contrast. Plain-text actions/footers inherit panel content color; applications own independently styled slots.

wrapper-* controls list position/spacing; padding-*/margin-* control panel layout; icon-*/title-*/content-* control typography; close-* controls close buttons; border-*/box-shadow control borders/shadows; transition-* controls motion; z-index controls stacking. Existing geometry/motion defaults remain. The table lists actual declarations, not a claim that every historical geometry variable has verified consumers.

| Variable | Default |
| --- | --- |
| `--c-notification-wrapper-margin-top` | `var(--c-spacing-8)` |
| `--c-notification-wrapper-margin-bottom` | `var(--c-spacing-8)` |
| `--c-notification-wrapper-margin-left` | `var(--c-spacing-8)` |
| `--c-notification-wrapper-margin-right` | `var(--c-spacing-8)` |
| `--c-notification-z-index` | `var(--c-z-index-notification)` |
| `--c-notification-border-radius` | `var(--c-border-radius-md)` |
| `--c-notification-margin-bottom` | `var(--c-spacing-8)` |
| `--c-notification-width` | `300px` |
| `--c-notification-padding-top` | `var(--c-spacing-8)` |
| `--c-notification-padding-bottom` | `var(--c-spacing-8)` |
| `--c-notification-padding-left` | `var(--c-spacing-8)` |
| `--c-notification-padding-right` | `var(--c-spacing-8)` |
| `--c-notification-icon-font-size` | `24px` |
| `--c-notification-title-font-size` | `var(--c-font-size-title-1)` |
| `--c-notification-title-font-weight` | `var(--c-font-weight-500)` |
| `--c-notification-content-font-size` | `var(--c-font-size-body-3)` |
| `--c-notification-icon-margin-right` | `var(--c-spacing-7)` |
| `--c-notification-title-margin-bottom` | `var(--c-spacing-2)` |
| `--c-notification-footer-margin-top` | `var(--c-spacing-7)` |
| `--c-notification-box-shadow` | `0 4px 12px rgba(0, 0, 0, 0.15)` |
| `--c-notification-border-width` | `1px` |
| `--c-notification-border-style` | `solid` |
| `--c-notification-close-icon-color` | `var(--c-sys-color-content-secondary)` |
| `--c-notification-close-icon-font-size` | `12px` |
| `--c-notification-close-icon-top` | `var(--c-spacing-6)` |
| `--c-notification-close-icon-right` | `var(--c-spacing-6)` |
| `--c-notification-close-icon-hover-size` | `20px` |
| `--c-notification-normal-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-normal-icon-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-normal-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-normal-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-normal-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-info-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-info-icon-color` | `var(--c-sys-color-content-info)` |
| `--c-notification-info-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-info-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-info-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-success-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-success-icon-color` | `var(--c-sys-color-content-success)` |
| `--c-notification-success-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-success-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-success-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-warning-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-warning-icon-color` | `var(--c-sys-color-content-warning)` |
| `--c-notification-warning-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-warning-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-warning-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-error-bg` | `var(--c-sys-color-surface-overlay)` |
| `--c-notification-error-icon-color` | `var(--c-sys-color-content-danger)` |
| `--c-notification-error-title-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-error-content-color` | `var(--c-sys-color-content-primary)` |
| `--c-notification-error-border-color` | `var(--c-sys-color-border-default)` |
| `--c-notification-transition-duration` | `var(--c-transition-duration-2)` |
| `--c-notification-transition-duration-enter` | `var(--c-transition-duration-4)` |
| `--c-notification-transition-duration-leave` | `var(--c-transition-duration-3)` |
| `--c-notification-transition-timing-function` | `var(--c-transition-timing-function-linear)` |
| `--c-notification-transition-timing-function-enter` | `var(--c-transition-timing-function-overshoot)` |
| `--c-notification-transition-timing-function-leave` | `var(--c-transition-timing-function-standard)` |

After Teleport, theme variables follow actual DOM ancestors. Variables inside content do not propagate upward to service-created containers.

A throwing close/closed notification cannot retain the closed item or its empty manager host. Resources are released independently of notification callbacks.

---

Document: llms/en-US/components/overflow-list.md

<!-- Source: src/overflow-list/README.en-US.md; locale: en-US; page: /en/components/overflow-list/ -->

# Overflow List

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `auto-label-width`, `:min="0"`, `:max="20"`, `:max="800"`.

Example source: src/overflow-list/__demos__/basic.vue

```vue
<template>
  <c-form auto-label-width>
    <c-form-item label="Tag Number">
      <c-input-number v-model="number" :min="0" :max="20" style="width: 200px" />
    </c-form-item>
    <c-form-item label="List Width">
      <c-slider v-model="width" :min="0" :max="800" />
    </c-form-item>
  </c-form>
  <div :style="{ width: `${width}px`, marginTop: '20px' }">
    <c-overflow-list>
      <div>DIV Element</div>
      <c-tag v-for="item of tags" :key="item">Tag{{ item }}</c-tag>
    </c-overflow-list>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'

const width = ref(500)
const number = ref(10)
const tags = computed(() => Array.from({ length: number.value }, (_, idx) => idx + 1))
</script>
```

## Layout and arrangement

### From

- `from`: Overflow From

Example source: src/overflow-list/__demos__/from.vue

```vue
<template>
  <c-form auto-label-width>
    <c-form-item label="Tag Number">
      <c-input-number v-model="number" :min="0" :max="20" style="width: 200px" />
    </c-form-item>
    <c-form-item label="List Width">
      <c-slider v-model="width" :min="0" :max="800" />
    </c-form-item>
  </c-form>
  <div :style="{ width: `${width}px`, marginTop: '20px' }">
    <c-overflow-list from="start">
      <div>DIV Element</div>
      <c-tag v-for="item of tags" :key="item">Tag{{ item }}</c-tag>
    </c-overflow-list>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'

const width = ref(500)
const number = ref(10)
const tags = computed(() => Array.from({ length: number.value }, (_, idx) => idx + 1))
</script>
```

## API

### `<overflow-list>` Props

| Parameter | Description | Type | Default |
| ------ | ------------------ | ------------------ | :-----: |
| min | Minimum number of elements to display | `number` | `0` |
| margin | Item Margin | `number` | `8` |
| from | Overflow From | `'start' \| 'end'` | `'end'` |

### `<overflow-list>` Events

| Event | Description | Arguments |
| ------ | ------------------ | --------------- |
| change | Emitted when the overflow count changes | value: `number` |

### `<overflow-list>` Slots

| Slot | Description | Arguments |
| -------- | :------: | ---------------- |
| overflow | Collapsed elements | number: `number` |

### Type definitions

The component exports the following types

```ts
import type { BadgeInstance } from '@cedar-design/ui'
```

---

Document: llms/en-US/components/overlay.md

<!-- Source: src/overlay/README.en-US.md; locale: en-US; page: /en/components/overlay/ -->

# Overlay

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `v-model:open="open"`.

Example source: src/overlay/__demos__/basic.vue

```vue
<template>
  <c-button status="primary" @click="open = true">打开背景层</c-button>
  <c-overlay v-model:open="open">
    <div class="overlay-demo-content">背景层内容</div>
  </c-overlay>
</template>

<script setup lang="ts">
import { ref } from "vue";

const open = ref(false);
</script>

<style scoped>
.overlay-demo-content {
  padding: 24px;
  background: var(--c-color-bg-2);
  border-radius: var(--c-border-radius-md);
}
</style>
```

## API

### Props

| Arguments | Description | Type | Default |
| ------------------ | -------------------------------------------- | -------------------------------- | -------- |
| `v-model:open` | Visible state | `boolean` | `false` |
| `default-open` | Whether to display by default in uncontrolled mode | `boolean` | `false` |
| `overlay-closable` | Whether clicking the backdrop closes the Overlay | `boolean` | `true` |
| `lock-scroll` | Lock scrolling on the host | `boolean` | `true` |
| `unmount-on-close` | Whether to unmount slot content after closing | `boolean` | `true` |
| `esc-to-close` | Whether Escape closes the overlay | `boolean` | `true` |
| `popup-container` | Teleport target; `false` renders in place | `string \| HTMLElement \| false` | `'body'` |
| `z-index` | Custom z-index | `number` | `-` |

### Events

| Event | Description | Arguments |
| ------------- | ------------ | --------------- |
| `update:open` | Open state changed | `boolean` |
| `open` | Opening starts | `-` |
| `opened` | Opening transition completes | `-` |
| `close` | Closing starts | `-` |
| `closed` | Closing transition completes | `-` |
| `click` | Click on the background area | `MouseEvent` |
| `key-escape` | Escape was pressed | `KeyboardEvent` |

### Slots

| Slot | Description |
| --------- | ---------------- |
| `default` | Content above the background layer |

## Public CSS variables

These are actual :root defaults. Prefer component variables for business customization; internal positioning variables are not public API.

| Variable | Default | Meaning and use case |
| --- | --- | --- |
| `--c-overlay-background-color` | `var(--c-sys-color-scrim)` | Scrim background only; does not change foreground-content opacity |
| `--c-overlay-animation-duration` | `var(--c-sys-motion-duration-slow)` | Enter/leave duration; reduced motion may override it |
| `--c-overlay-content-z-index` | `var(--c-sys-layer-raised)` | Local stacking level of content above the scrim |

### Reduced motion

Built-in CSS transitions follow `prefers-reduced-motion: reduce`. Removing transitions does not change final visibility, selected/expanded state or event semantics. Applications control custom animations inside slots.

---

Document: llms/en-US/components/page-header.md

<!-- Source: src/page-header/README.en-US.md; locale: en-US; page: /en/components/page-header/ -->

# Page Header

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `show-back`: Whether to show the back button
- `title`: Main title
- `subtitle`: Subtitle

Example source: src/page-header/__demos__/basic.vue

```vue
<template>
  <c-card variant="outline" size="md">
    <c-page-header
      show-back
      title="设计系统"
      subtitle="项目概览"
      @back="onBack"
    >
      <template #extra>
        <c-space size="sm" wrap>
          <c-button @click="onFollow">关注</c-button>
          <c-button status="primary" @click="onCreate">创建任务</c-button>
        </c-space>
      </template>
    </c-page-header>
  </c-card>
</template>

<script setup lang="ts">
import { Message } from "@cedar-design/ui";

const onBack = () => Message.info("点击返回");
const onFollow = () => Message.success("已关注项目");
const onCreate = () => Message.info("点击创建任务");
</script>
```

## Content and presentation

### Breadcrumbs and transparent surfaces

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Main title | Breadcrumbs and transparent surfaces, Content |
| `subtitle` | Subtitle | Breadcrumbs and transparent surfaces, Content |
| `show-back` | Whether to show back | Content |
<!-- demo-config-notes:end -->


Compare breadcrumb navigation and title hierarchy on transparent surfaces.

Example source: src/page-header/__demos__/surface-comparison.vue

```vue
<script setup lang="ts">
import { Message } from "@cedar-design/ui"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


const onFollow = () => Message.success("已关注项目");
return { onFollow }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="breadcrumb">
    <h4><span lang="zh-CN">页头上方内容</span><span lang="en-US">breadcrumb</span></h4>
    <c-card variant="outline" size="md">
        <c-page-header title="设计系统" subtitle="项目概览">
          <template #header>
            <c-breadcrumb>
              <c-breadcrumb-item>工作台</c-breadcrumb-item>
              <c-breadcrumb-item>项目</c-breadcrumb-item>
              <c-breadcrumb-item>设计系统</c-breadcrumb-item>
            </c-breadcrumb>
          </template>
        </c-page-header>
      </c-card>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="transparent">
    <h4><span lang="zh-CN">透明底色</span><span lang="en-US">transparent</span></h4>
    <c-card variant="tonal" size="md">
        <c-page-header title="设计系统" subtitle="项目概览">
          <template #extra><c-button @click="scene2.onFollow">关注</c-button></template>
          <span>页头默认透明，可以融入页面背景。</span>
        </c-page-header>
      </c-card>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Content

- `show-back`: Whether to show the back button
- `title`: Main title
- `subtitle`: Subtitle

Example source: src/page-header/__demos__/content.vue

```vue
<template>
  <c-card variant="outline" size="md">
    <c-page-header
      show-back
      title="设计系统"
      subtitle="项目概览"
      @back="onBack"
    >
      <template #header>
        <c-breadcrumb>
          <c-breadcrumb-item>工作台</c-breadcrumb-item>
          <c-breadcrumb-item>项目</c-breadcrumb-item>
        </c-breadcrumb>
      </template>
      <template #avatar
        ><c-avatar shape="square" :size="40">D</c-avatar></template
      >
      <template #extra>
        <c-space size="sm" wrap>
          <c-button @click="onFollow">关注</c-button>
          <c-button status="primary" @click="onCreate">创建任务</c-button>
        </c-space>
      </template>
      <c-row :gutter="[24, 24]" align="center" justify="space-between">
        <c-col :xs="24" :lg="14">
          <c-space direction="column" size="lg">
            <span>统一设计规范与组件资源，帮助团队高效协作。</span>
            <c-descriptions :column="2" size="sm">
              <c-descriptions-item label="负责人">林晓</c-descriptions-item>
              <c-descriptions-item label="所属团队"
                >设计平台</c-descriptions-item
              >
            </c-descriptions>
          </c-space>
        </c-col>
        <c-col :xs="24" :lg="8">
          <c-grid :cols="3" :col-gap="24">
            <c-grid-item
              ><c-statistic title="组件" :value="48" tabular-nums
            /></c-grid-item>
            <c-grid-item
              ><c-statistic title="进行中" :value="12" tabular-nums
            /></c-grid-item>
            <c-grid-item
              ><c-statistic title="成员" :value="8" tabular-nums
            /></c-grid-item>
          </c-grid>
        </c-col>
      </c-row>
      <template #footer>
        <c-divider :spacing="[0, 16]" />
        <c-space justify="space-between" size="sm" wrap>
          <small>项目编号 DS-001</small>
          <small>最近更新：今天</small>
        </c-space>
      </template>
    </c-page-header>
  </c-card>
</template>

<script setup lang="ts">
import { Message } from "@cedar-design/ui";

const onBack = () => Message.info("点击返回");
const onFollow = () => Message.success("已关注项目");
const onCreate = () => Message.info("点击创建任务");
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. The back action sits at reading start and its default icon points right in RTL. Titles and extras follow reading order. Custom back slots are not automatically mirrored.

## API

### PageHeader Props

| Prop | Description | Type | Default |
| -------- | ---------------- | --------- | ------- |
| show-back | Whether to show back | `boolean` | `false` |
| title | Main title | `string` | `-` |
| subtitle | Subtitle | `string` | `-` |
| extra | Extra content on the right | `string` | `-` |

### PageHeader Events

| Event | Description | Arguments |
| ------ | ------------------ | -------------- |
| back | Emitted when the back button is clicked | event: `Event` |

### PageHeader Slots

| Slot | Description | Arguments |
| -------- | -------------- | ---- |
| header | Content above the page header | - |
| back | Custom back icon | - |
| avatar | Avatar | - |
| title | Main title | - |
| subtitle | Subtitle | - |
| extra | Additional right-side content | - |
| default | Main page-header content | - |
| footer | Footer content | - |

## Type definitions

```ts
import type { PageHeaderProps } from '@cedar-design/ui'
```

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

The back control is a native button with keyboard activation and back(MouseEvent). Cedar classes change from c-page-header-xxx to c-page-header__xxx. Icons remain locally supplied.

### Back-interaction variables

`--c-page-header-back-hover-size` (30px) sets the feedback-circle size without moving title layout. `--c-page-header-back-hover-bg` (`var(--c-sys-color-state-hover)`) sets its background. Hover applies only to hover-capable fine pointers; all input modes retain keyboard focus-visible feedback.

---

Document: llms/en-US/components/pagination.md

<!-- Source: src/pagination/README.en-US.md; locale: en-US; page: /en/components/pagination/ -->

# Pagination

Pagination with a shared API and container-responsive layout.

## Basic examples

### Basic and two-way binding

Example source: src/pagination/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const current = ref(1)
</script>
<template>
  <div class="pagination-demo">
    <c-pagination v-model="current" :total="50" />
    <span>Current: {{ current }}</span>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## Appearance and states

### Five sizes and elevation

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `total` | Total item count; required | Five sizes and elevation, Disabled and hide on single page |
| `show-page-size` | Show page size selector | Five sizes and elevation, Disabled and hide on single page |
| `show-jumper` | Show separate jumper in full mode; simple mode includes input | Five sizes and elevation, Disabled and hide on single page |
| `size` | Size of all controls | Five sizes and elevation |
| `elevation` | Page button shadow; true uses level 2 | Five sizes and elevation |
| `disabled` | Disable all interactions | Disabled and hide on single page |
<!-- demo-config-notes:end -->


Example source: src/pagination/__demos__/size.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const size = ref<'xs' | 'sm' | 'md' | 'lg' | 'xl'>('md')
const elevation = ref(false)
</script>
<template>
  <div class="pagination-demo">
    <c-radio-group v-model="size"><c-radio v-for="value in ['xs', 'sm', 'md', 'lg', 'xl']" :key="value" :value="value">{{ value }}</c-radio></c-radio-group>
    <div class="pagination-demo-controls"><c-switch v-model="elevation" /> Elevation</div>
    <c-pagination :size="size" :elevation="elevation" :total="50" show-page-size show-jumper />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### Disabled and hide on single page

Example source: src/pagination/__demos__/disabled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const disabled = ref(true)
const single = ref(false)
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-switch v-model="disabled" /> Disabled<c-switch v-model="single" /> Single page</div>
    <c-pagination :total="single ? 5 : 200" :disabled="disabled" hide-on-single-page show-jumper show-page-size show-total />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## Pagination modes and information

### Simple mode

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `total` | Total item count; required | Simple mode, Page window and ellipsis, Totals, page sizes and jumpers |
| `show-total` | Show total | Simple mode, Totals, page sizes and jumpers |
| `show-page-size` | Show page size selector | Simple mode, Totals, page sizes and jumpers |
| `responsive` | Automatically use simple mode by container width | Page window and ellipsis, Totals, page sizes and jumpers |
| `simple` | Explicit simple mode | Simple mode |
| `default-value` | Initial uncontrolled page | Page window and ellipsis |
<!-- demo-config-notes:end -->


Example source: src/pagination/__demos__/simple.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const current = ref(3)
</script>
<template>
  <div class="pagination-demo">
    <c-pagination v-model="current" :total="200" simple show-total show-page-size />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### Page window and ellipsis

Example source: src/pagination/__demos__/more-page-size.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const buffer = ref(2)
const more = ref(false)
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-radio-group v-model="buffer"><c-radio v-for="value in [0, 1, 2]" :key="value" :value="value">Buffer {{ value }}</c-radio></c-radio-group><c-switch v-model="more" /> Show more</div>
    <c-pagination :total="500" :default-value="12" :buffer-size="buffer" :show-more="more" :responsive="false" />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### Totals, page sizes and jumpers

Compare total labels, page-size selection and page jumpers. Change the available controls and observe their output.

Example source: src/pagination/__demos__/auxiliary-controls-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {

const pageSize = ref(10)

const current = ref(5)
return { pageSize, current }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="show-total">
    <h4><span lang="zh-CN">自定义总数插槽</span><span lang="en-US">Custom total slot</span></h4>
    <div class="pagination-demo">
        <c-pagination :total="200" show-total><template #total="{ total }">{{ total }} records</template></c-pagination>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="show-page-size">
    <h4><span lang="zh-CN">每页条数与公共选择器配置</span><span lang="en-US">Page size and shared selector options</span></h4>
    <div class="pagination-demo">
        <c-pagination v-model="scene2.current" v-model:page-size="scene2.pageSize" :total="200" show-page-size :page-size-options="[10, 20, 50, 100]" :page-size-props="{
      placement: 'bottom-start'
    }" />
        <span>Current: {{ scene2.current }} · Page size: {{ scene2.pageSize }}</span>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="show-jumper">
    <h4><span lang="zh-CN">跳转与前后缀插槽</span><span lang="en-US">Jumper and prefix/suffix slots</span></h4>
    <div class="pagination-demo">
        <c-pagination :total="200" show-jumper :responsive="false">
          <template #jumper-prepend>Go to</template><template #jumper-append>page</template>
        </c-pagination>
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }
.demo-comparison-case--1 {

.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }

}
.demo-comparison-case--2 {

.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }

}
.demo-comparison-case--3 {

.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }

}
</style>
```

## Page size, navigation and buttons

### Custom page slots and styles

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `total` | Total item count; required | Custom page slots and styles |
| `default-value` | Initial uncontrolled page | Custom page slots and styles |
| `buffer-size` | Pages on either side of current page | Custom page slots and styles |
| `responsive` | Automatically use simple mode by container width | Custom page slots and styles |
| `page-item-style` | Base numeric page style | Custom page slots and styles |
| `active-page-item-style` | Additional active numeric page style | Custom page slots and styles |
<!-- demo-config-notes:end -->


Example source: src/pagination/__demos__/custom-page-button.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

</script>
<template>
  <div class="pagination-demo">
    <c-pagination :total="300" :default-value="10" :buffer-size="0" :responsive="false" :page-item-style="{ borderRadius: '8px' }" :active-page-item-style="{ fontWeight: '700' }">
      <template #page-item="{ page }">{{ page }}</template>
      <template #page-item-step="{ type }">{{ type === 'previous' ? 'Prev' : 'Next' }}</template>
      <template #page-item-ellipsis>✦</template>
    </c-pagination>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## Responsive layout and data changes

### Container width and compact layout

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `total` | Total item count; required | Container width and compact layout, Data changes and auto adjustment, Full feature controls |
| `show-total` | Show total | Container width and compact layout, Data changes and auto adjustment, Full feature controls |
| `show-page-size` | Show page size selector | Container width and compact layout, Data changes and auto adjustment, Full feature controls |
| `show-jumper` | Show separate jumper in full mode; simple mode includes input | Container width and compact layout, Full feature controls |
| `responsive` | Automatically use simple mode by container width | Container width and compact layout |
| `auto-adjust` | Preserve first record on size change; clamp after total shrinks | Data changes and auto adjustment |
<!-- demo-config-notes:end -->


Example source: src/pagination/__demos__/responsive.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const width = ref(360)
const responsive = ref(true)
</script>
<template>
  <div class="pagination-demo">
    <c-radio-group v-model="width" wrap><c-radio v-for="value in [280, 360, 480, 640]" :key="value" :value="value">{{ value }}px</c-radio></c-radio-group>
    <div class="pagination-demo-controls"><c-switch v-model="responsive" /> Responsive</div>
    <div :style="{ width: width + 'px', maxWidth: '100%' }"><c-pagination :total="250" :responsive="responsive" show-total show-jumper show-page-size /></div>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; grid-template-columns: minmax(0, 1fr); gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### Data changes and auto adjustment

Example source: src/pagination/__demos__/auto-adjust.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const total = ref(200)
const current = ref(18)
const autoAdjust = ref(true)
function reset() { total.value = 200; current.value = 18 }
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-switch v-model="autoAdjust" /> Auto adjust<c-button @click="total = 25">Reduce total</c-button><c-button @click="reset">Reset</c-button></div>
    <c-pagination v-model="current" :total="total" :auto-adjust="autoAdjust" show-total show-page-size />
    <span>Current: {{ current }} · Total: {{ total }}</span>
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

### Full feature controls

Example source: src/pagination/__demos__/all.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const total = ref(true)
const jumper = ref(true)
const pageSize = ref(true)
</script>
<template>
  <div class="pagination-demo">
    <div class="pagination-demo-controls"><c-switch v-model="total" /> Total<c-switch v-model="jumper" /> Jumper<c-switch v-model="pageSize" /> Page size</div>
    <c-pagination :total="125" :show-total="total" :show-jumper="jumper" :show-page-size="pageSize" />
  </div>
</template>
<style scoped>
.pagination-demo { display: grid; gap: 16px; min-width: 0; }
.pagination-demo-controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
</style>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Page numbers and previous/next semantics remain unchanged. Default navigation icons follow reading direction; page input, disabled boundaries and selection are preserved. Custom icon slots own their direction.

## API

Use ordinary `v-model`: `modelValue` is the current page, starting at 1; pageSize independently controls items per page. `defaultValue` initializes uncontrolled state once without later resets or initialization `update:modelValue`. When `modelValue` is supplied, the parent value controls the display.

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| total | Total item count; required | `number` | `—` |
| model-value | Current page; v-model | `number` | `—` |
| default-value | Initial uncontrolled page | `number` | `1` |
| page-size | Page size; v-model:page-size | `number` | `—` |
| default-page-size | Initial uncontrolled page size | `number` | `10` |
| disabled | Disable all interactions | `boolean` | `false` |
| hide-on-single-page | Hide with at most one page | `boolean` | `false` |
| simple | Explicit simple mode | `boolean` | `false` |
| show-total | Show total | `boolean` | `false` |
| show-more | Append forward jump in full mode | `boolean` | `false` |
| show-jumper | Show separate jumper in full mode; simple mode includes input | `boolean` | `false` |
| show-page-size | Show page size selector | `boolean` | `false` |
| page-size-options | Positive integer size options | `number[]` | `[10, 20, 30, 40, 50]` |
| page-size-props | Optional restricted configuration for the page-size Select. Placement defaults to bottom-start and reaches Trigger through Select.triggerProps for automatic positioning; cannot override pagination values, options or size | `PaginationPageSizeProps` | `—` |
| size | Size of all controls | `'xs' / 'sm' / 'md' / 'lg' / 'xl'` | `'md'` |
| page-item-style | Base numeric page style | `CSSProperties` | `—` |
| active-page-item-style | Additional active numeric page style | `CSSProperties` | `—` |
| base-size | Base threshold for ellipsis in full mode | `number` | `6` |
| buffer-size | Pages on either side of current page | `number` | `2` |
| elevation | Page button shadow; true uses level 2 | `boolean / number` | `false` |
| responsive | Automatically use simple mode by container width | `boolean` | `true` |
| compact-breakpoint | Maximum container width for compact mode, in px | `number` | `480` |
| auto-adjust | Preserve first record on size change; clamp after total shrinks | `boolean` | `true` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:model-value | Request current page update | `number` |
| change | Committed page change; paired with update:modelValue | `number` |
| update:page-size | Request page size update | `number` |
| page-size-change | Committed size change; paired with update:page-size | `number` |

### Slots

| Slot | Description | Scope |
| --- | --- | --- |
| total | Total | `{ total: number }` |
| page-item | Numeric page | `{ page: number }` |
| page-item-step | Previous / next | `{ type: 'previous' / 'next' }` |
| page-item-ellipsis | Ellipsis jump | `—` |
| jumper-prepend | Separate jumper prefix | `—` |
| jumper-append | Separate jumper suffix | `—` |

### Methods

| Method | Description |
| --- | --- |

<!-- same-source-api:end -->

## Behavior

Containers at or below `compact-breakpoint` automatically use compact mode, consistently in desktop sidebars and mobile. Totals/page-size selectors remain; auxiliary controls wrap. Previous/next sizes follow size without forced narrow-screen enlargement (formerly 36px). `responsive=false` retains full page numbers; extremely narrow page lists scroll internally without widening the page.

The compact current-page input also serves as the jumper, so no duplicate jumper appears. `page-item`, `page-item-ellipsis`, `jumper-prepend` and `jumper-append` render only in their full-mode controls.

Page buttons support Tab/Enter/Space, with `aria-current=page` on the current page. The jumper requests a numeric keyboard and submits on Enter/blur. Empty, nonnumeric or fractional values do not navigate; out-of-range integers clamp to valid pages. Disabled blocks all commits.

`auto-adjust` tries to preserve the previous page's first item when page size changes, clamps to the last page after total reductions and returns to page 1 for zero items. Controlled mode proposes updates only; the parent decides the display. An explicit parent modelValue in the same update batch takes precedence.

Both full and compact jumper inputs show the current page. Navigation, external modelValue changes and page-size adjustments update them together. Invalid input restores the current page number.

### PaginationPageSizeProps

The page-size selector fits its selected text and arrow with only item spacing between them, updating on option/language changes. `--c-pagination-select-width` overrides its width. Popup menus size independently from option content.

Both platforms support `disabled?: boolean`, `placement?: 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'`, `popupContainer?: string | HTMLElement | false`, `class?: string` and `style?: CSSProperties`. Outer disabled takes precedence. Default placement is bottom-start.

This configuration no longer forwards arbitrary SelectProps/MenuProps. page-size, page-size-options and size control the pagination value, options and dimensions.

## Type definitions

```ts
import type { PaginationProps, PaginationInstance, PaginationPageSizeProps } from '@cedar-design/ui'
```

## Style variables

| Token | Default |
| --- | --- |
| `--c-pagination-text-color` | `var(--c-color-text-1)` |
| `--c-pagination-font-size` | `var(--c-sys-font-size-md)` |
| `--c-pagination-gap` | `var(--c-sys-space-5)` |
| `--c-pagination-item-gap` | `var(--c-sys-space-2)` |
| `--c-pagination-focus-space` | `3px` |
| `--c-pagination-size-xs` | `24px` |
| `--c-pagination-size-sm` | `28px` |
| `--c-pagination-size-md` | `36px` |
| `--c-pagination-size-lg` | `44px` |
| `--c-pagination-size-xl` | `52px` |
| `--c-pagination-item-padding` | `var(--c-sys-space-4)` |
| `--c-pagination-item-border-radius` | `var(--c-sys-radius-md)` |
| `--c-pagination-icon-size` | `16px` |
| `--c-pagination-input-width` | `32px` |
| `--c-pagination-select-width` | `max-content` |
| `--c-pagination-touch-size` | `44px` |
| `--c-pagination-focus-width` | `2px` |
| `--c-pagination-focus-offset` | `1px` |
| `--c-pagination-focus-color` | `var(--c-color-primary)` |
| `--c-pagination-item-background` | `transparent` |
| `--c-pagination-hover-background` | `var(--c-color-fill-1)` |
| `--c-pagination-active-background` | `var(--c-color-primary-light-1)` |
| `--c-pagination-active-color` | `var(--c-color-primary)` |
| `--c-pagination-disabled-color` | `var(--c-color-text-4)` |
| `--c-pagination-disabled-background` | `var(--c-color-fill-1)` |


### Placement semantics and configuration

No placement configuration is required for normal use: bottom-start is preferred and the underlying Trigger automatically flips/constrains the popup. pageSizeProps.placement is only a restricted override for the page-size Select: Pagination → Select.triggerProps.placement → Trigger. It does not position the pagination itself.

---

Document: llms/en-US/components/palette.md

<!-- Source: src/style/palette/README.en-US.md; locale: en-US; page: /en/components/palette/ -->

# Style Palette

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Colors

Example source: src/style/palette/__demos__/colors.vue

```vue
<template>
  <div class="palette-demo">
    <div class="section-title">功能色阶</div>
    <div class="hue-grid">
      <div v-for="hue in functionalHues" :key="hue.name" class="hue-block">
        <div class="hue-label">{{ hue.label }}</div>
        <div class="swatch-row">
          <div
            v-for="step in steps"
            :key="`${hue.name}-${step}`"
            class="swatch"
            :style="{
              background: `rgb(var(--c-${hue.name}-${step}))`,
              color: step > 5 ? '#fff' : '#000',
            }"
            :title="`--c-${hue.name}-${step}`"
          >
            <span class="swatch-name">{{ step }}</span>
          </div>
        </div>
      </div>
    </div>

    <div class="section-title">色相色阶</div>
    <div class="hue-grid">
      <div v-for="hue in chromaticHues" :key="hue.name" class="hue-block">
        <div class="hue-label">{{ hue.label }}</div>
        <div class="swatch-row">
          <div
            v-for="step in steps"
            :key="`${hue.name}-${step}`"
            class="swatch"
            :style="{
              background: `rgb(var(--c-${hue.name}-${step}))`,
              color: step > 5 ? '#fff' : '#000',
            }"
            :title="`--c-${hue.name}-${step}`"
          >
            <span class="swatch-name">{{ step }}</span>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<script lang="ts" setup>
const steps = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

const functionalHues = [
  { name: "primary", label: "Primary（主色）" },
  { name: "success", label: "Success" },
  { name: "warning", label: "Warning" },
  { name: "danger", label: "Danger" },
  { name: "link", label: "Link" },
  { name: "gray", label: "Gray" },
];

const chromaticHues = [
  { name: "brand", label: "Brand" },
  { name: "red", label: "Red" },
  { name: "orangered", label: "Orangered" },
  { name: "orange", label: "Orange" },
  { name: "gold", label: "Gold" },
  { name: "yellow", label: "Yellow" },
  { name: "lime", label: "Lime" },
  { name: "green", label: "Green" },
  { name: "cyan", label: "Cyan" },
  { name: "blue", label: "Blue" },
  { name: "purple", label: "Purple" },
  { name: "pinkpurple", label: "Pinkpurple" },
  { name: "magenta", label: "Magenta" },
];
</script>

<style lang="less" scoped>
.palette-demo {
  color: var(--c-color-text-1);
}

.section-title {
  margin: 16px 0 12px;
  font-size: 16px;
  font-weight: 600;
}

.hue-grid {
  display: grid;
  grid-template-columns: repeat(3, minmax(0, 1fr));
  gap: 16px 20px;
  margin-bottom: 8px;
}

.hue-block {
  min-width: 0;
}

.hue-label {
  margin-bottom: 6px;
  font-size: 13px;
  color: var(--c-color-text-3);
}

.swatch-row {
  display: flex;
  gap: 2px;
  overflow: hidden;
  border-radius: var(--c-border-radius-md, 4px);
}

.swatch {
  flex: 1;
  min-width: 0;
  height: 36px;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 11px;
  font-variant-numeric: tabular-nums;
}

.swatch-name {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
  padding: 0 2px;
}

@media (max-width: 991px) {
  .hue-grid {
    grid-template-columns: repeat(2, minmax(0, 1fr));
  }
}

@media (max-width: 767px) {
  .hue-grid {
    grid-template-columns: 1fr;
  }
}
</style>
```

---

Document: llms/en-US/components/paper.md

<!-- Source: src/paper/README.en-US.md; locale: en-US; page: /en/components/paper/ -->

# Paper

Paper is a low-level surface with background, radius, optional border and elevation. It has no variant, status, structural slots or default padding. Use Card for structured content. Paper does not manage popup positioning, focus or button semantics.

## Basic examples

### Examples

Example source: src/paper/__demos__/basic.vue

```vue
<template>
  <c-space wrap>
    <c-paper :width="120" :height="80">Surface</c-paper>
    <c-paper bordered :width="120" :height="80">Border</c-paper>
    <c-paper bordered :elevation="2" style="padding: 16px">Border + shadow</c-paper>
    <c-paper :radius="12" :width="120" :height="80" :elevation="2">Radius</c-paper>
    <c-paper round :width="80" :height="80" bordered />
    <c-paper inline bordered>Inline</c-paper>
    <c-paper ripple bordered :width="120" :height="80">Ripple</c-paper>
  </c-space>
</template>
```

## Interaction and control

### Live properties

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `bordered` | Show a border independently of elevation | Live properties |
| `round` | 50% radius; a circle only with equal width and height | Live properties |
| `radius` | Explicit radius, taking priority over round | Live properties |
| `elevation` | false disables; true uses level 2; numeric levels 0–24 | Live properties |
| `width` | Width | Live properties |
| `height` | Surface height | Live properties |
<!-- demo-config-notes:end -->


Border and shadow are independent. An explicit radius overrides round; removing it restores round. The inner native button provides keyboard semantics, and its click bubbles to Paper to update parent-owned feedback.

Example source: src/paper/__demos__/live-properties.vue

```vue
<script setup>
import { ref } from "vue";

const bordered = ref(false);
const round = ref(false);
const explicitRadius = ref(false);
const elevated = ref(false);
const clicks = ref(0);
</script>

<template>
  <section class="paper-live-demo">
    <div class="controls">
      <c-checkbox v-model="bordered"> Paper border</c-checkbox>
      <c-checkbox v-model="round"> Round paper</c-checkbox>
      <c-checkbox v-model="explicitRadius"> Explicit radius</c-checkbox>
      <c-checkbox v-model="elevated"> Paper shadow</c-checkbox>
    </div>
    <p role="status">Surface clicks: {{ clicks }}</p>
    <c-paper
      data-testid="live-paper"
      :bordered="bordered"
      :round="round"
      :radius="explicitRadius ? '12' : undefined"
      :elevation="elevated ? 2 : false"
      width="160"
      :height="100"
      @click="clicks++"
    >
      <c-button html-type="button">Surface action</c-button>
    </c-paper>
  </section>
</template>

<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
}
.controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
[data-testid="live-paper"] {
  display: flex;
  align-items: center;
  justify-content: center;
}
</style>
```

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| bordered | Show a border independently of elevation | boolean | false |
| elevation | false disables; true uses level 2; numeric levels 0–24 | boolean / number | false |
| ripple | Opt-in ripple; does not add button semantics | boolean | false |
| radius | Explicit radius, taking priority over round | number / string | — |
| width | Width | number / string | — |
| height | Surface height | number / string | — |
| round | 50% radius; a circle only with equal width and height | boolean | false |
| inline | Use inline-flex | boolean | false |

Numbers and numeric strings for radius/width/height use px. Other strings pass through as CSS lengths, such as 1rem, 50% and calc(100% - 8px). Classes, native attributes and styles fall through to the root.

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| click | Triggered when the paper is clicked | MouseEvent |

### Slots

| Slot | Description |
| --- | --- |
| default | Paper content |

### Style variables

| Variable | Default |
| --- | --- |
| --c-paper-background | `var(--c-sys-color-surface-default)` |
| --c-paper-border-radius | `4px` |
| --c-paper-border-width | `1px` |
| --c-paper-border-color | `var(--c-sys-color-border-default)` |
| --c-paper-transition-duration | `var(--c-sys-motion-duration-slow)` |

Built-in themes can override backgrounds/radii. bordered=false reserves no border space; enabled borders use border-box and count within fixed dimensions. Background, border and shadow are independent.

### Types

```ts
import type { PaperProps, PaperInstance } from '@cedar-design/ui'
```

## Independent source copies

Each platform maintains its own component body, props, styles, tokens and contract tests, adapting prefixes/local imports without a cross-library core or shared instances/state.

Maple migration: the default background becomes the theme surface, and the default pointer cursor is removed. The inline class becomes mp-paper--inline. Existing dimensions, radii, elevation and ripple APIs remain.

---

Document: llms/en-US/components/people-select.md

<!-- Source: src/people-select/README.en-US.md; locale: en-US; page: /en/components/people-select/ -->

# PeopleSelect

`options` accepts an array or a loader. Each component owns loading, cancellation and stale-result isolation. `fallback-option` synchronously reads independent reactive display data; update that data after a business request to refresh the label and avatar. Avatars come from `avatar`. Optional phone/chat buttons provide consistent presentation while all actions remain application functions.

## Global defaults and local overrides

```ts
import { PeopleSelect, type PeopleSelectProps } from "@cedar-design/ui";
PeopleSelect.setPropsDefaults({
  options: (query, { signal }) => peopleService.search(query, signal),
  fallbackOption: (id) => personCache.value[id] ?? { value: id, label: id },
  showPhone: true,
  showChat: true,
  call: (person) => businessPhone.call(person.mobile),
  chat: (person) => businessChat.open(person.value),
} satisfies PeopleSelectProps);
```

```vue
<c-people-select v-model="personId" />
<c-people-select
  v-model="personId"
  :options="loadMyTeam"
  :chat="openTeamChat"
  :show-phone="false"
  read-pretty
/>
<c-people-select v-model="personId" :options="[]" />
```

Local props override global defaults. Arrays, including [], replace a global loader. Phone/chat buttons appear only in read mode and are hidden by default. Without an action function, without a selected person, or when disabled, the action cannot run. Returned Promises drive button loading; rejection emits action-error(error, call|chat). The UI never opens tel: links or imports a chat SDK.

Configure setPropsDefaults once before mounting. It changes the component definition, not an app/tenant-isolated context. For SSR or dynamic tenant defaults, use an application wrapper and props.

## Custom actions

```vue
<c-people-select v-model="personId" read-pretty>
  <template #actions="{ person, disabled }">
    <business-person-actions :person="person" :disabled="disabled" />
  </template>
</c-people-select>
```

Priority: actions slot → render-actions → built-in phone/chat buttons. Actions do not open the field editor or change its model.

## Basic examples

### Complete example

Example source: src/people-select/__demos__/en-US/injected-services.vue

```vue
<script setup lang="ts">
import { onMounted, ref } from 'vue'
const personId = ref<string | null>('alice')
const log = ref('')
const people = [
 { value: 'alice', label: 'Alice', mobile: '13800000000', avatar: 'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" width="24" height="24"%3E%3Ccircle cx="12" cy="12" r="12" fill="%236579af"/%3E%3C/svg%3E' },
 { value: 'bob', label: 'Bob', mobile: '13900000000' },
]
const displayed = ref<Record<string, (typeof people)[number]>>({})
// Simulated detail request: update display data without changing candidates.
onMounted(() => { setTimeout(() => { displayed.value.alice = people[0] }, 600) })
const fallbackOption = (id: string) => displayed.value[id] ?? { value: id, label: id }
async function options(query: string, { signal }: { signal: AbortSignal }) {
 await new Promise(resolve => setTimeout(resolve, 200))
 if (signal.aborted) return []
 return people.filter(person => person.label.toLowerCase().includes(query.toLowerCase()))
}
async function call(person: { value: string; mobile?: string }) { log.value = `Call: ${person.mobile || person.value}` }
async function chat(person: { value: string }) { log.value = `Chat: ${person.value}` }
</script>
<template>
 <c-space direction="column">
  <c-people-select v-model="personId" :options="options" :fallback-option="fallbackOption" clearable :empty-value="null" />
  <c-people-select v-model="personId" :fallback-option="fallbackOption" show-phone show-chat :call="call" :chat="chat" read-pretty />
  <p role="status">{{ log }}</p>
 </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

| Prop                    | Description                                                  | Default |
| ----------------------- | ------------------------------------------------------------ | ------- |
| v-model / default-value | String ID; null explicitly clears the model                  | — / ''  |
| options                 | Array or (query, { signal }) => array/Promise                | —       |
| fallback-option         | boolean / (id) => PeopleSelectOption                         | true    |
| show-avatar             | Render avatar                                                | true    |
| show-phone / show-chat  | Read-mode phone/chat buttons                                 | false   |
| call / chat             | Application (person) => void/Promise                         | —       |
| render-actions          | ({ person, disabled }) => VNodeChild                         | —       |
| is-label / read-pretty  | Read mode; uses reactive fallback without loading candidates | false   |
| disabled / readonly     | Inherit form state when omitted                              | —       |
| empty-value             | Clear result; accepts null or a factory returning null       | ''      |

Person data is `{ value: string, label: string, avatar?: string, mobile?: string, disabled?: boolean }`.

Optionally pass signal to fetch to cancel stale requests. It is not an HTTP parameter and cannot roll back server operations. Even if signal is ignored, the component isolates stale results. Function results skip secondary local filtering by default; filter-option configures only local matching.

Events: update:model-value, change, clear, search, load-error(error, options), action-error(error, call|chat). Methods: refresh(), focus(), blur(). No separate request prop, external useAsyncData or special provider key is needed.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

`fallback-option` is independent of options, returns no Promise and sends no requests. Display prefers a current option, then fallback; false disables display of unmatched values.

### Receiving cancellation signals in business requests

The component creates an AbortController per operation and passes signal to the loader. Business code must forward it through request layers. fetch supports AbortSignal natively; Axios 0.22+ supports signal; ofetch/Ky forward or merge it into fetch. Other wrappers must adapt abort events to their own cancellation methods. Client cancellation cannot undo completed server operations.

```ts
async function loadPeople(query, { signal }) {
  const response = await fetch(`/api/people?q=${encodeURIComponent(query)}`, {
    signal,
  });
  if (!response.ok) throw new Error("People request failed");
  return response.json();
}

// Axios: preserve signal through your service wrapper.
async function loadWithAxios(query, { signal }) {
  const { data } = await axios.get("/api/people", {
    params: { q: query },
    signal,
  });
  return data;
}

// Other fetch wrappers:
const loadWithOfetch = (query, { signal }) =>
  ofetch("/api/people", { query: { q: query }, signal });
const loadWithKy = (query, { signal }) =>
  ky.get("/api/people", { searchParams: { q: query }, signal }).json();
```

[AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) · [Axios cancellation](https://axios-http.com/docs/cancellation) · [ofetch](https://github.com/unjs/ofetch) · [Ky](https://github.com/sindresorhus/ky#cancellation)

---

Document: llms/en-US/components/popconfirm.md

<!-- Source: src/popconfirm/README.en-US.md; locale: en-US; page: /en/components/popconfirm/ -->

# Popconfirm

A confirmation popup with before-confirm and before-cancel hooks.

## Basic examples

### Basic

Example source: src/popconfirm/__demos__/basic.vue

```vue
<template>
  <c-popconfirm content="Are you sure you want to delete?">
    <c-button>Click To Delete</c-button>
  </c-popconfirm>
</template>

<script lang="ts" setup>
</script>
```

## Appearance and states

### Type

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Content | Type |
| `type` | Confirmation status type | Type |
<!-- demo-config-notes:end -->


Example source: src/popconfirm/__demos__/type.vue

```vue
<template>
  <c-space>
    <c-popconfirm content="Are you sure you want to delete?" type="info">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
    <c-popconfirm content="Are you sure you want to delete?" type="success">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
    <c-popconfirm content="Are you sure you want to delete?" type="warning">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
    <c-popconfirm content="Are you sure you want to delete?" type="error">
      <c-button>Click To Delete</c-button>
    </c-popconfirm>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

### Api Review

## Layout and arrangement

### Placement

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Content | Placement |
| `placement` | Preferred popup side relative to the trigger, default top. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Placement |
<!-- demo-config-notes:end -->


Example source: src/popconfirm/__demos__/placement.vue

```vue
<template>
  <div :style="{ position: 'relative', width: '440px', height: '280px' }">
    <c-popconfirm content="This is a Popconfirm" placement="top-start">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '70px' }">TL</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="top">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '180px' }">TOP</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="top-end">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '290px' }">TR</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="bottom-start">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '70px' }">BL</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="bottom">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '180px' }">BOTTOM</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="bottom-end">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '290px' }">BR</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="left-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '10px' }">LT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="left">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '10px' }">LEFT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="left-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '10px' }">LB</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="right-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '350px' }">RT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="right">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '350px' }">RIGHT</c-button>
    </c-popconfirm>
    <c-popconfirm content="This is a Popconfirm" placement="right-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '350px' }">RB</c-button>
    </c-popconfirm>
  </div>
</template>

<script lang="ts" setup>
</script>
```

## Content and presentation

### Guard Protocol

Example source: src/popconfirm/__demos__/en-US/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { PopconfirmBeforeConfirm } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(false);
const status = ref("");
const check: PopconfirmBeforeConfirm = (payload, done, { signal }) => {
  status.value = `Waiting: ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "Allowed" : "Rejected";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-switch v-model="allowed" />
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done callback' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">Open</c-button>
    <c-popconfirm
      v-model:open="open"
      :before-confirm="check"
      @guard-error="status = 'Error'"
    >
      <template #default
        ><c-button v-if="true" @click="open = true">Confirm action</c-button
        ><span v-else>Close with beforeClose</span></template
      >
    </c-popconfirm>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

### `<popconfirm>` Props

| Name | Description | Type | Default |
| --------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | :------: |
| content | Content | `string` | `-` |
| placement | Preferred popup side relative to the trigger, default top. Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | `'top'` |
| open **(v-model)** | Controlled confirmation popup visibility | `boolean` | `-` |
| default-open | Initial uncontrolled popup visibility | `boolean` | `false` |
| type | Confirmation status type | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` |
| confirm-button-text | Confirm button text | `string` | `-` |
| cancel-text | Cancel button text | `string` | `-` |
| confirm-button-loading | Confirm button loading state | `boolean` | `false` |
| confirm-button-props | Confirm button props | `ButtonProps` | `-` |
| cancel-button-props | Cancel button props | `ButtonProps` | `-` |
| content-class | Popup content class | `ClassName` | `-` |
| content-style | Popup content style | `CSSProperties` | `-` |
| arrow-class | Arrow class | `ClassName` | `-` |
| arrow-style | Arrow style | `CSSProperties` | `-` |
| popup-container | Portal container | `string \| HTMLElement \| false` | `-` |
| `before-confirm` | Return a boolean/Promise or call done; the first completion wins | `PopconfirmBeforeConfirm` | — |
| `before-cancel` | Return a boolean/Promise or call done; the first completion wins | `PopconfirmBeforeConfirm` | — |

### `<popconfirm>` Events

| Event | Description | Arguments |
| -------------------- | ------------------------------ | ------------------ |
| open-change | Popup visibility changes | open: `boolean` |
| confirm | Accepted confirm action | - |
| cancel | Accepted cancel action | - |

### `<popconfirm>` Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| icon | Icon | - |
| content | Content | - |


Promise and done share a single completion state: false/done(false) rejects; true/done() allows; a resolved Promise&lt;void&gt; allows. The first completion wins. Errors emit guard-error; cancellation/unmount invalidates late completion. Synchronous void retains the callback protocol and waits for done on these close/confirm guards.


Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

## Customization and slots

### Custom

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Content | Custom |
| `confirm-button-text` | Confirm button text | Custom |
| `cancel-text` | Cancel button text | Custom |
<!-- demo-config-notes:end -->


Example source: src/popconfirm/__demos__/custom.vue

```vue
<template>
  <c-popconfirm content="Do you want to discard the draft?" confirmButtonText="Discard" cancelText="No">
    <c-button>Discard</c-button>
  </c-popconfirm>
</template>

<script lang="ts" setup>
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Content and actions use logical alignment. Confirm/cancel actions follow reading order, and switching direction triggers neither action. Explicit popup placement retains its documented physical or logical meaning.

## API

### `<popconfirm>` Props

| Parameter | Description | Type | Default |
| --------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | :------: |
| content | Content | `string` | `-` |
| placement | Preferred popup side relative to the trigger, default top. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | `'top'` |
| open **(v-model)** | Controlled confirmation popup visibility | `boolean` | `-` |
| default-open | Initial uncontrolled popup visibility | `boolean` | `false` |
| type | Confirmation status type | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` |
| confirm-button-text | Confirm button text | `string` | `-` |
| cancel-text | Cancel button text | `string` | `-` |
| confirm-button-loading | Confirm button loading state | `boolean` | `false` |
| confirm-button-props | Confirm button props | `ButtonProps` | `-` |
| cancel-button-props | Cancel button props | `ButtonProps` | `-` |
| content-class | Popup content class | `ClassName` | `-` |
| content-style | Popup content style | `CSSProperties` | `-` |
| arrow-class | Arrow class | `ClassName` | `-` |
| arrow-style | Arrow style | `CSSProperties` | `-` |
| popup-container | Portal container | `string \| HTMLElement \| false` | `-` |
| `before-confirm` | Return a boolean/Promise or call done; the first completion wins | `PopconfirmBeforeConfirm` | — |
| `before-cancel` | Return a boolean/Promise or call done; the first completion wins | `PopconfirmBeforeConfirm` | — |

### `<popconfirm>` Events

| Event | Description | Arguments |
| -------------------- | ------------------------------ | ------------------ |
| open-change | Popup visibility changes | open: `boolean` |
| confirm | Accepted confirm action | - |
| cancel | Accepted cancel action | - |

### `<popconfirm>` Slots

| Slot | Description | Arguments |
| ------- | :--: | ---- |
| icon | Icon | - |
| content | Content | - |

### Type definitions

The component exports the following types

```ts
import type { PopconfirmInstance } from '@cedar-design/ui'
```


### Placement semantics and configuration

placement directly uses TriggerPlacement / triggerPlacements. Legacy TriggerPosition / TRIGGER_POSITIONS aliases have been removed; placement values are unchanged.

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading.

---

Document: llms/en-US/components/popover.md

<!-- Source: src/popover/README.en-US.md; locale: en-US; page: /en/components/popover/ -->

# Popover

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `title="设备状态"`.

Example source: src/popover/__demos__/basic.vue

```vue
<template>
  <c-popover title="设备状态">
    <c-button>点击查看</c-button>
    <template #content>
      <p>设备：生产线 A-03</p>
      <p>状态：运行中</p>
    </template>
  </c-popover>
</template>
```

## Interaction and control

### Interactive

Preview configuration: `v-model:open="open"`, `title="快速备注"`, `placeholder="关闭后再次打开，草稿仍会保留"`.

Example source: src/popover/__demos__/interactive.vue

```vue
<template>
  <c-popover v-model:open="open" title="快速备注">
    <c-button>编辑备注</c-button>
    <template #content>
      <c-space direction="column">
        <c-input v-model="draft" placeholder="关闭后再次打开，草稿仍会保留" />
        <c-button status="primary" @click="open = false">完成</c-button>
      </c-space>
    </template>
  </c-popover>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
const draft = ref('')
</script>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Content defaults to reading start and portals inherit their source direction. Logical start/end alignment follows direction, while explicit left/right placement remains physical.

## API

Popover inherits Trigger positioning, containers, controlled state, close policies and public methods.

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| title | Title | `string` | — |
| content | Body | `string` | — |
| trigger | Interaction | `TriggerEvent \| TriggerEvent[]` | `click` |
| placement | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `TriggerPlacement` | `bottom` |
| show-arrow | Show the arrow | `boolean` | `true` |
| popup-offset | Main-axis distance | `number` | `10` |
| unmount-on-close | Unmount content after closing; interaction drafts are retained by default | `boolean` | `false` |
| close-on-click-reference | Close when the trigger is clicked again | `boolean` | `true` |

Events: `update:open`, `open-change`, `open`, `opened`, `close`, `closed`, `click-outside`. Slots: `default`, `title`, `content`. Slots override same-name `content` props.

Panels have consistent content/title/body layers. Triggers are associated through `aria-controls`/`aria-expanded`; external references and SVG are also supported.

## Shared-source contract

Cedar and Maple independently maintain the same component body, props, appearance mapping and structural styles. Use Trigger directly for unstyled positioning. Popover has no `defaultStyle`, `popoverClass` or `elevation`; customize appearance through component tokens, `content-class` or `content-style`.

## Public CSS variables

These are actual :root defaults. Prefer component variables for business customization; internal positioning variables are not public API.

| Variable | Default | Meaning and use case |
| --- | --- | --- |
| `--c-popover-background` | `var(--c-sys-color-surface-overlay)` | Content and arrow background |
| `--c-popover-text-color` | `var(--c-sys-color-content-secondary)` | Body foreground |
| `--c-popover-border-color` | `var(--c-sys-color-border-default)` | Content and arrow border color |
| `--c-popover-border-width` | `1px` | Content and arrow border width |
| `--c-popover-border-radius` | `var(--c-sys-radius-md)` | Content border radius |
| `--c-popover-box-shadow` | `var(--c-shadow2-down)` | Content shadow; retains platform differences |
| `--c-popover-arrow-z-index` | `1` | Arrow stacking within the current popup |
| `--c-popover-padding-horizontal` | `var(--c-sys-space-7)` | Horizontal content padding |
| `--c-popover-padding-vertical` | `var(--c-sys-space-6)` | Vertical content padding |
| `--c-popover-font-size` | `var(--c-sys-font-size-md)` | Content font size |
| `--c-popover-line-height` | `var(--c-line-height)` | Content line height |
| `--c-popover-title-text-color` | `var(--c-sys-color-content-primary)` | Title foreground |
| `--c-popover-title-font-size` | `var(--c-sys-font-size-lg)` | Title font size |
| `--c-popover-title-font-weight` | `var(--c-sys-font-weight-medium)` | Title font weight |
| `--c-popover-title-content-gap` | `var(--c-sys-space-2)` | Title-to-body gap |
| `--c-popover-animation-duration` | `var(--c-sys-motion-duration-standard)` | Enter/leave duration; reduced motion may override it |

Maple dark mode retains a 2px radius and platform-specific shadows. Content and arrows share background/border variables, independent of Trigger style-loading order.

With Teleport, variables must be in the actual popup scope, for example through `popup-style`. Trigger-button variables do not automatically inherit into popups.

---

Document: llms/en-US/components/progress-group.md

<!-- Source: src/progress-group/README.en-US.md; locale: en-US; page: /en/components/progress-group/ -->

# Progress Group

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `max`: Sets the upper bound.

Example source: src/progress-group/__demos__/basic.vue

```vue
<script setup lang="ts">
import type { ProgressGroupItem } from '@cedar-design/ui'

const items: ProgressGroupItem[] = [
  { label: '系统', value: 24, color: '#64748b' },
  { label: '应用', value: 8, color: '#f53f3f' },
  { label: '多媒体', value: 42, color: '#00b42a' },
]
</script>

<template>
  <c-progress-group :items="items" :max="128" show-text style="max-width: 520px" />
</template>
```

## Appearance and states

### Progress group sizes and colors

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `items` | Segment data | Progress group sizes and colors |
| `size` | Track size | Progress group sizes and colors |
| `color` | Default color for segments without their own color | Progress group sizes and colors |
| `show-text` | Show the summed percentage | Progress group sizes and colors |
<!-- demo-config-notes:end -->


Compare segment sizes and color overrides separately from orientation, circular layouts, overflow and keyboard interaction.

Example source: src/progress-group/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const items = [
  { value: 24 },
  { value: 18, color: "#722ed1" },
  { value: 30, color: "#0fc6c2" },
];

const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
return { items, sizes }
})())

const scene2 = demoProxyRefs((() => {

const inheritedColorItems = [
  { label: "文档", value: 20 },
  { label: "测试", value: 35 },
];

const trackOnlyItems = [
  { value: 16 },
  { value: 22, color: "#722ed1" },
  { value: 28, color: "#0fc6c2" },
];
return { inheritedColorItems, trackOnlyItems }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="sizes">
    <h4><span lang="zh-CN">尺寸</span><span lang="en-US">sizes</span></h4>
    <c-space direction="column" size="16px" style="max-width: 520px">
        <div
          v-for="size in scene1.sizes"
          :key="size"
          style="
            display: grid;
            grid-template-columns: 24px 1fr;
            align-items: center;
            gap: 12px;
          "
        >
          <span>{{ size }}</span>
          <c-progress-group :items="scene1.items" :size="size" />
        </div>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="color">
    <h4><span lang="zh-CN">颜色与纯进度轨</span><span lang="en-US">color</span></h4>
    <c-space direction="column" size="24px" style="max-width: 520px">
        <c-progress-group :items="scene2.inheritedColorItems" color="#ff7d00" show-text />
        <c-progress-group :items="scene2.trackOnlyItems" size="lg" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Layout and arrangement

### Orientation

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `items` | Segment data | Orientation |
| `show-text` | Show the summed percentage | Orientation |
| `orientation` | Horizontal/vertical orientation of the linear progress track, default horizontal; only used for mode=line | Orientation |
| `size` | Track size | Orientation |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.

Example source: src/progress-group/__demos__/orientation.vue

```vue
<script setup lang="ts">
const items = [
  { label: "系统", value: 24, color: "#64748b" },
  { label: "应用", value: 18, color: "#f53f3f" },
  { label: "媒体", value: 32, color: "#00b42a" },
];
</script>

<template>
  <c-space wrap size="64px" align="flex-start">
    <c-progress-group :items="items" show-text style="width: 420px" />
    <c-progress-group
      :items="items"
      orientation="vertical"
      size="lg"
      show-text
      style="height: 220px"
    />
  </c-space>
</template>
```

## Content and presentation

### Circle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `mode` | Display mode | Circle |
| `items` | Segment data | Circle |
| `show-text` | Show the summed percentage | Circle |
| `circle-size` | Diameter in circle mode | Circle |
| `stroke-width` | Track width in circle mode | Circle |
<!-- demo-config-notes:end -->


Preview configuration: `mode="circle"`, `:items="items"`, `show-text`, `:circle-size="168"`.

Example source: src/progress-group/__demos__/circle.vue

```vue
<script setup lang="ts">
const items = [
  { label: "系统", value: 24, color: "#64748b" },
  { label: "应用", value: 18, color: "#f53f3f" },
  { label: "媒体", value: 32, color: "#00b42a" },
];
</script>

<template>
  <c-space wrap size="48px" align="flex-start">
    <c-progress-group mode="circle" :items="items" show-text />
    <c-progress-group
      mode="circle"
      :items="items"
      :circle-size="168"
      :stroke-width="12"
      show-text
    >
      <template #text="{ value, max }">
        <div style="text-align: center">
          <strong>{{ value }}</strong
          ><br /><small>/ {{ max }} GB</small>
        </div>
      </template>
    </c-progress-group>
  </c-space>
</template>
```

## Interaction and control

### Overflow Keyboard

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `items` | Segment data | Overflow Keyboard |
| `max` | Total used to calculate segment proportions | Overflow Keyboard |
| `tooltip` | Whether to show segment hover/focus hints | Overflow Keyboard |
| `show-text` | Show the summed percentage | Overflow Keyboard |
| `aria-label` | Accessible group name | Overflow Keyboard |
| `mode` | Display mode | Overflow Keyboard |
<!-- demo-config-notes:end -->


- `max`: Sets the upper bound.

Example source: src/progress-group/__demos__/overflow-keyboard.vue

```vue
<script setup>
import { ref } from "vue";

const initialItems = [
  { label: "A", value: 70 },
  { label: "B", value: 50, color: "#722ed1" },
  { label: "C", value: 10, color: "#0fc6c2" },
];
const items = ref(initialItems);
const max = ref(100);
const tooltip = ref(true);
</script>
<template>
  <c-space direction="column" size="24px" data-demo-capacity>
    <c-space wrap>
      <c-button @click="max = max === 100 ? 200 : 100"
        >Capacity: {{ max }}</c-button
      >
      <c-button @click="items = items.length ? [] : initialItems">{{
        items.length ? "Clear data" : "Restore data"
      }}</c-button>
      <c-button @click="tooltip = !tooltip"
        >Tooltips: {{ tooltip ? "on" : "off" }}</c-button
      >
    </c-space>
    <c-progress-group
      :items="items"
      :max="max"
      :tooltip="tooltip"
      show-text
      aria-label="Capacity line"
    />
    <c-progress-group
      mode="circle"
      :items="items"
      :max="max"
      :tooltip="tooltip"
      show-text
      aria-label="Capacity circle"
    />
    <p aria-live="polite">
      Items: {{ items.length }}; capacity: {{ max }}; tooltips:
      {{ tooltip ? "on" : "off" }}
    </p>
  </c-space>
</template>
```

Example source: src/progress-group/__demos__/slots.vue

```vue
<script setup lang="ts">
const items = [
  { label: '设计稿', value: 18, color: '#165dff', tip: '设计稿占用 18 GB' },
  { label: '组件', value: 36, color: '#722ed1' },
  { label: '测试', value: 20, color: '#0fc6c2' },
]
</script>

<template>
  <c-progress-group :items="items" show-text style="max-width: 520px">
    <template #text="{ value, max }">已使用 {{ value }} / {{ max }} GB</template>
    <template #item-trailing="{ item }">{{ item.value }} GB</template>
    <template #tooltip="{ item, percent }">{{ item.label }} · {{ item.value }} GB · {{ Math.round(percent) }}%</template>
  </c-progress-group>
</template>
```

## Reading direction

Horizontal segments, highlights and tooltips share a logical start. Vertical progress stays top to bottom; circular angles and data order are preserved.

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| aria-label | Accessible group name | `string` | — |
| items | Segment data | `ProgressGroupItem[]` | `[]` |
| mode | Display mode | `'line' \| 'circle'` | `'line'` |
| max | Total used to calculate segment proportions | `number` | `100` |
| show-text | Show the summed percentage | `boolean` | `false` |
| size | Track size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| color | Default color for segments without their own color | `string` | `content-brand` |
| circle-size | Diameter in circle mode | `number \| string` | `120` |
| stroke-width | Track width in circle mode | `number` | `8` |
| tooltip | Whether to show segment hover/focus hints | `boolean` | `true` |
| orientation | Horizontal/vertical orientation of the linear progress track, default horizontal; only used for mode=line | `'horizontal' \| 'vertical'` | `'horizontal'` |

### Item

| Prop | Description | Type |
| --- | --- | --- |
| label | Legend label | `string` |
| value | Segment value | `number` |
| color | Segment color | `string` |
| icon | Legend icon component | `Component` |
| slot | Custom slot-name prefix | `string` |
| tip | Custom hint text | `string` |

### Slots

| Name | Slot arguments |
| --- | --- |
| text | `{ percent, value, max }` |
| tooltip | `{ item, index, percent }` |
| item / item-leading / item-label / item-trailing | `{ item, index, percent }` |

### Style variables

| Variable | Default |
| --- | --- |
| `--c-progress-group-gap` | `var(--c-sys-space-3)` |
| `--c-progress-group-item-gap` | `var(--c-sys-space-2)` |
| `--c-progress-group-dot-size` | `var(--c-sys-space-4)` |
| `--c-progress-group-radius` | `9999px` |
| `--c-progress-group-track-color` | `var(--c-sys-color-state-hover)` |
| `--c-progress-group-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-progress-group-muted-color` | `var(--c-sys-color-content-secondary)` |
| `--c-progress-group-font-size` | `var(--c-sys-font-size-sm)` |
| `--c-progress-group-tooltip-bg` | `var(--c-sys-color-surface-tooltip)` |
| `--c-progress-group-tooltip-color` | `var(--c-sys-color-content-on-dark)` |

Graphic markers default to system content-brand. Color precedence: item.color → component color → default. Check custom-color contrast; geometry tokens retain platform differences.

### Geometry and motion variables

Built-in effects respect `prefers-reduced-motion: reduce`. Track thickness applies to both horizontal and vertical layouts; circle geometry remains prop-driven.

| Token | Default |
| --- | --- |
| `--c-progress-group-transition-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-progress-group-tooltip-duration` | `var(--c-sys-motion-duration-fast)` |
| `--c-progress-group-tooltip-max-width` | `240px` |
| `--c-progress-group-tooltip-padding` | `5px var(--c-sys-space-4)` |
| `--c-progress-group-tooltip-radius` | `var(--c-sys-radius-md)` |
| `--c-progress-group-tooltip-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-progress-group-tooltip-line-height` | `1.4` |
| `--c-progress-group-tooltip-offset` | `var(--c-sys-space-4)` |
| `--c-progress-group-text-font-weight` | `var(--c-sys-font-weight-medium)` |
| `--c-progress-group-size-xs-thickness` | `2px` |
| `--c-progress-group-size-sm-thickness` | `4px` |
| `--c-progress-group-size-md-thickness` | `8px` |
| `--c-progress-group-size-lg-thickness` | `12px` |
| `--c-progress-group-size-xl-thickness` | `16px` |

---

Document: llms/en-US/components/progress.md

<!-- Source: src/progress/README.en-US.md; locale: en-US; page: /en/components/progress/ -->

# Progress

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:percent="20"`, `:percent="30"`.

Example source: src/progress/__demos__/basic.vue

```vue
<template>
  <c-progress :percent="20" :style="{ width: '50%' }" />
  <br />
  <br />
  <c-progress :percent="30" :style="{ width: '50%' }">
    <template v-slot:text="scope">进度 {{ scope.percent }}%</template>
  </c-progress>
</template>
```

## Appearance and states

### Progress sizes and states

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | xs/sm/md/lg/xl or CSS length; line thickness / circle diameter | Progress sizes and states |
| `percent` | Decimal 0–100; numeric strings supported; invalid values become zero, out-of-range values clamp | Progress sizes and states |
| `mode` | Line or circle | Progress sizes and states |
| `stroke-width` | Overrides thickness, numbers in px | Progress sizes and states |
| `status` | default/primary/secondary/tertiary/info/success/warning/danger; default becomes success at 100 unless indeterminate | Progress sizes and states |
<!-- demo-config-notes:end -->


Compare sizes and semantic states independently of circular, stepped and indeterminate models.

Example source: src/progress/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
return { sizes }
})())

const scene2 = demoProxyRefs((() => {

const statuses = [
  "default",
  "primary",
  "secondary",
  "tertiary",
  "info",
  "success",
  "warning",
  "danger",
] as const;
return { statuses }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">五档与自定义尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column" size="16px">
        <c-space wrap size="16px" align="center" v-for="size in scene1.sizes" :key="size">
          <span>{{ size }}</span
          ><c-progress :size="size" :percent="42" /><c-progress
            mode="circle"
            :size="size"
            :percent="42"
          />
        </c-space>
        <c-progress :size="10" :percent="12.5" />
        <c-progress size="0.75rem" :stroke-width="6" :percent="60" />
        <c-progress mode="circle" size="6rem" :percent="75" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="status">
    <h4><span lang="zh-CN">八种状态</span><span lang="en-US">status</span></h4>
    <c-space direction="column" size="16px">
        <c-progress
          v-for="status in scene2.statuses"
          :key="status"
          :status="status"
          :percent="60"
          ><template #text>{{ status }}</template></c-progress
        >
        <c-progress :percent="100" />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Content and presentation

### Circle

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `percent` | Decimal 0–100; numeric strings supported; invalid values become zero, out-of-range values clamp | Circle, Step, Loop |
| `mode` | Line or circle | Circle, Loop, Advanced |
| `status` | default/primary/secondary/tertiary/info/success/warning/danger; default becomes success at 100 unless indeterminate | Circle, Step |
| `steps` | Line segments, floored and clamped to 0–1000; ignored when indeterminate | Step |
| `size` | xs/sm/md/lg/xl or CSS length; line thickness / circle diameter | Step |
| `indeterminate` | Unknown progress; omits aria-valuenow | Loop |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/progress/__demos__/circle.vue

```vue
<template>
  <c-space wrap size="lg">
    <c-progress mode="circle" :percent="percent" />
    <c-progress mode="circle" status="warning" :percent="percent" />
    <c-progress mode="circle" status="danger" :percent="percent" />
    <c-progress mode="circle" status="success" :percent="percent" />
  </c-space>
  <div :style="{ marginTop: '20px' }">
    <c-slider v-model="percent" :max="100" :step="10" :style="{ width: '150px' }" />
  </div>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const percent = ref(20)
</script>
```

### Step

- `status`: Selects the semantic state.
- `size`: Controls the component size.

Example source: src/progress/__demos__/step.vue

```vue
<template>
  <c-space direction="column" size="16px">
    <c-progress :steps="5" :percent="40" />
    <c-progress :steps="10" :percent="75" status="warning" size="lg" />
    <c-progress :steps="5" :percent="100" />
  </c-space>
</template>
```

### Loop

Preview configuration: `indeterminate`, `aria-label="Loading"`, `mode="circle"`, `:percent="60"`.

Example source: src/progress/__demos__/loop.vue

```vue
<template>
  <c-space direction="column" size="16px">
    <c-progress indeterminate aria-label="Loading" />
    <c-progress mode="circle" indeterminate aria-label="Loading" />
    <c-progress :percent="60" animation />
  </c-space>
</template>
```

### Advanced

- `color`: Overrides the color.

Example source: src/progress/__demos__/advanced.vue

```vue
<script setup>
import { ref } from "vue";

const gradient = ref(false);
</script>
<template>
  <c-space direction="column" size="16px">
    <c-switch v-model="gradient" aria-label="Gradient" />
    <c-progress
      :percent="65"
      :color="gradient ? { '0%': '#722ed1', '100%': '#0fc6c2' } : '#722ed1'"
      buffer-color="#eee5ff"
    />
    <c-space wrap size="24px">
      <c-progress
        mode="circle"
        :percent="65"
        :rotate="90"
        :color="gradient ? { '0%': '#722ed1', '100%': '#0fc6c2' } : '#722ed1'"
      />
      <c-progress mode="circle" :percent="65" :track="false"
        ><template #text="{ percent }"
          >{{ percent }} / 100</template
        ></c-progress
      >
    </c-space>
  </c-space>
</template>
```

## Reading direction

Linear progress grows from reading start and activity motion follows reading direction. Values and circular angles remain unchanged, and reduced-motion settings still apply.

## API

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| mode | Line or circle | `line \| circle` | `line` |
| percent | Decimal 0–100; numeric strings supported; invalid values become zero, out-of-range values clamp | `number \| string` | `0` |
| size | xs/sm/md/lg/xl or CSS length; line thickness / circle diameter | `ProgressSize` | `md` |
| stroke-width | Overrides thickness, numbers in px | `number \| string` | Follows size |
| steps | Line segments, floored and clamped to 0–1000; ignored when indeterminate | `number` | `0` |
| status | default/primary/secondary/tertiary/info/success/warning/danger; default becomes success at 100 unless indeterminate | `ProgressStatus` | `default` |
| color | Solid or gradient stops; overrides status | `string \| Record<string, string>` | — |
| track-color | Background track color | `string` | — |
| buffer-color | Remaining line track decoration, not a second progress value | `ProgressColor` | — |
| track | Show track and buffer decoration | `boolean` | `true` |
| show-text | Show text; xs circle hides text | `boolean` | `true` |
| text-class | Text container class | `string` | — |
| rotate | Clockwise angle from twelve o'clock | `number` | `0` |
| animation | Determinate continuous line shimmer | `boolean` | `false` |
| indeterminate | Unknown progress; omits aria-valuenow | `boolean` | `false` |

### Size semantics

| size | xs | sm | md | lg | xl |
| --- | --- | --- | --- | --- | --- |
| Linear thickness / default circular stroke in px | 2 | 3 | 4 | 6 | 8 |
| Circular diameter in px | 16 | 48 | 64 | 80 | 96 |

`size=12` / `size="12"` means 12px; `size="2rem"`, `"50%"` and `"calc(100% - 2px)"` retain CSS lengths. Custom linear size controls thickness; custom circular size controls diameter. stroke-width always takes precedence for thickness. Invalid/nonpositive lengths fall back to md. Percentage circular diameters require a definite parent width. All five presets are implemented; xs circular progress hides text. Cedar inherits omitted size from ConfigProvider; Maple defaults to md.

### Slots

| Slot | Arguments | Description |
| --- | --- | --- |
| text | `{ percent: number }` | Takes precedence over default |
| default | `{ percent: number }` | Custom display text |

Indeterminate progress shows an ellipsis by default; use the text slot for business text. The component does not mutate values or emit updates. Provide `aria-label` for the business task. All built-in animations respect reduced-motion settings.

### Type definitions

Exports `ProgressProps`, `ProgressInstance`, `ProgressSize`, `ProgressMode`, `ProgressStatus`, `ProgressColor` and runtime `progressProps`.

## Style variables

| Variable | Default |
| --- | --- |
| `--c-progress-font-size` | `var(--c-sys-font-size-sm)` |
| `--c-progress-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-progress-track-color` | `var(--c-sys-color-state-hover)` |
| `--c-progress-default-color` | `var(--c-sys-color-content-brand)` |
| `--c-progress-primary-color` | `var(--c-sys-color-content-brand)` |
| `--c-progress-secondary-color` | `var(--c-sys-color-content-secondary)` |
| `--c-progress-tertiary-color` | `var(--c-sys-color-content-tertiary)` |
| `--c-progress-info-color` | `var(--c-sys-color-content-info)` |
| `--c-progress-success-color` | `var(--c-sys-color-content-success)` |
| `--c-progress-warning-color` | `var(--c-sys-color-content-warning)` |
| `--c-progress-danger-color` | `var(--c-sys-color-content-danger)` |
| `--c-progress-line-border-radius` | `9999px` |
| `--c-progress-text-gap` | `var(--c-sys-space-4)` |
| `--c-progress-steps-gap` | `var(--c-sys-space-2)` |
| `--c-progress-transition-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-progress-animation-duration` | `1.5s` |

Determinate circular success/danger states show completion/failure icons, including xs. The text slot overrides these; ARIA numeric values remain.

---

Document: llms/en-US/components/radio.md

<!-- Source: src/radio/README.en-US.md; locale: en-US; page: /en/components/radio/ -->

# Radio

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Reading direction

Radio groups inherit source dir. Horizontal keys follow visible direction in RTL and skip disabled options; vertical keys and Home/End keep logical order. Radio and button variants retain one Tab entry. Changing direction does not change the selected value.

## Basic examples

### Basic usage

- `disabled`: Prevents user interaction.

Example source: src/radio/__demos__/basic.vue

```vue
<template>
  <c-space wrap size="lg" fill>
    <c-radio value="radio">Radio</c-radio>
    <c-radio value="disabled radio" default-value="disabled radio" disabled>Disabled Radio </c-radio>
    <c-radio-group v-model="type" variant="button">
      <c-radio value="rounded1">Rounded1</c-radio>
      <c-radio value="rounded">Rounded</c-radio>
      <c-radio value="capsule">Capsule</c-radio>
    </c-radio-group>
  </c-space>
</template>

<script lang="ts">
</script>
```

## Groups and layout

### Radio group declarations

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                   | Related examples                                       |
| ------------- | --------------------------------------------------------- | ------------------------------------------------------ |
| `value`       | Option `value`                                            | Radio group declarations, Group Direction, Button Type |
| `disabled`    | Disabled state; inherits from the form/group when omitted | Radio group declarations, Grid Layout                  |

<!-- demo-config-notes:end -->

Compare child and options declarations, then select items to inspect the group model.

Example source: src/radio/__demos__/group-declaration-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene2 = demoProxyRefs((() => {


    const value1 = ref('plain 1')


    const plainOptions = ['plain 1', 'plain 2', 'plain 3']



    const value2 = ref('1')


    const options = [
      { label: 'option 1', value: '1' },
      { label: 'option 2', value: '2' },
      { label: 'option 3', value: '3', disabled: true },
    ]
return { value1, plainOptions, value2, options }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="group">
    <h4><span lang="zh-CN">单选框组</span><span lang="en-US">group</span></h4>
    <c-space direction="column" size="lg">
        <c-radio-group>
          <c-radio value="A">A</c-radio>
          <c-radio value="B">B</c-radio>
          <c-radio value="C">C</c-radio>
          <c-radio value="D">D</c-radio>
        </c-radio-group>
        <c-radio-group>
          <c-radio value="A">A</c-radio>
          <c-radio value="B">B</c-radio>
          <c-radio value="C">C</c-radio>
          <c-radio value="D" disabled>D</c-radio>
        </c-radio-group>
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="group-options">
    <h4><span lang="zh-CN">单选框组选项</span><span lang="en-US">group options</span></h4>
    <c-space direction="column" size="lg">
        <c-radio-group v-model="scene2.value1" :options="scene2.plainOptions" />
        <c-radio-group v-model="scene2.value2" :options="scene2.options" />
        <c-radio-group v-model="scene2.value2" :options="scene2.options">
          <template #label="{ data }">
            <c-tag>{{ data.label }}</c-tag>
          </template>
        </c-radio-group>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Group Direction

Preview configuration: `orientation="vertical"`, `value="A"`, `value="B"`, `value="C"`.

Example source: src/radio/__demos__/group-direction.vue

```vue
<template>
  <c-radio-group orientation="vertical">
    <c-radio value="A">A</c-radio>
    <c-radio value="B">B</c-radio>
    <c-radio value="C">C</c-radio>
    <c-radio value="D">D</c-radio>
  </c-radio-group>
</template>
<script lang="ts">
</script>
```

### Button Type

Preview configuration: `variant="button"`, `value="Beijing"`, `value="Shanghai"`, `value="Guangzhou"`.

Example source: src/radio/__demos__/button-type.vue

```vue
<template>
  <c-radio-group variant="button">
    <c-radio value="Beijing">Beijing</c-radio>
    <c-radio value="Shanghai">Shanghai</c-radio>
    <c-radio value="Guangzhou">Guangzhou</c-radio>
    <c-radio value="Shenzhen">Shenzhen</c-radio>
  </c-radio-group>
</template>
<script lang="ts">
</script>
```

### Grid Layout

- `disabled`: Prevents user interaction.

Example source: src/radio/__demos__/grid-layout.vue

```vue
<template>
  <c-radio-group v-model="checkedValue">
    <c-grid :cols="3" :colGap="24" :rowGap="16">
      <c-grid-item>
        <c-radio value="1">Option 1</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="2" disabled>Option 2</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="3">Option 3</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="4">Option 4</c-radio>
      </c-grid-item>
      <c-grid-item>
        <c-radio value="5">Option 5</c-radio>
      </c-grid-item>
    </c-grid>
  </c-radio-group>
</template>

<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const checkedValue = ref('1')

    return {
      checkedValue,
    }
  },
}
</script>
```

### Group State

Preview configuration: `:default-value="'a'"`, `:options="options"`, `:readonly="readonly"`, `:model-value="''"`.

Example source: src/radio/__demos__/group-state.vue

```vue
<script setup>
import { ref } from 'vue'

const accepted = ref('a')
const proposed = ref('')
const readonly = ref(false)
const options = [{ label: '设备 A', value: 'a' }, { label: '设备 B', value: 'b' }]
</script>

<template>
  <c-space direction="column">
    <div>
      <p>非受控：default-value 只用于初始值</p>
      <c-radio-group :default-value="'a'" :options="options" />
    </div>
    <div>
      <p>受控：父级接受更新 {{ accepted }}</p>
      <c-radio-group v-model="accepted" :options="options" :readonly="readonly" />
      <c-button size="sm" @click="readonly = !readonly">{{ readonly ? '解除只读' : '设为只读' }}</c-button>
    </div>
    <div>
      <p>父级拒绝更新：仅记录提议 {{ proposed }}</p>
      <c-radio-group :model-value="''" :options="options" @update:model-value="proposed = $event" />
    </div>
  </c-space>
</template>
```

### Button Sizes

Preview configuration: `variant="button"`, `:size="size"`, `default-value="week"`, `:options="options"`.

Example source: src/radio/__demos__/button-sizes.vue

```vue
<script setup lang="ts">
const sizes = ['xs', 'sm', 'md', 'lg', 'xl'] as const
const options = [
  { label: '日', value: 'day' },
  { label: '周', value: 'week' },
  { label: '月', value: 'month' },
]
</script>
<template>
  <section class="radio-demo">
    <div v-for="size in sizes" :key="size">
      <p>{{ size }}</p>
      <c-radio-group variant="button" :size="size" default-value="week" :options="options" :aria-label="size" />
    </div>
    <p>纵向与只读</p>
    <c-radio-group variant="button" orientation="vertical" readonly default-value="day" :options="options" aria-label="只读周期" />
  </section>
</template>
<style scoped>
.radio-demo { display: flex; flex-direction: column; align-items: flex-start; gap: 12px; }
.radio-demo p { margin: 0 0 8px; }
</style>
```

## Options and value model

### Control Value

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                   | Related examples          |
| --------------- | --------------------------------------------------------- | ------------------------- |
| `default-value` | Initial uncontrolled value                                | Control Value, Controlled |
| `value`         | Option `value`                                            | Control Value             |
| `readonly`      | Readonly state; inherits from the form/group when omitted | Control Value             |
| `disabled`      | Disabled state; inherits from the form/group when omitted | Control Value             |

<!-- demo-config-notes:end -->

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/radio/__demos__/control-value.vue

```vue
<script setup>
import { ref } from 'vue'
const control = ref()
const value = ref(null)

</script>
<template>
  <c-space direction="column">
    <p>null 表示未选中；重复选择不会取消。 当前值：{{ value }}</p>
    <c-radio ref="control" v-model="value" :value="false">选择 false 选项</c-radio>
    <c-space wrap>
      <c-button size="sm" @click="control?.select()">选中</c-button>
      <c-button size="sm" @click="control?.focus()">聚焦</c-button>
      <c-button size="sm" @click="value = null">重置</c-button>
    </c-space>
    
    <p>只读允许聚焦，禁用不允许操作；Enter/空格只影响当前控件。</p>
    <c-radio :default-value="true" readonly>只读</c-radio>
    <c-radio :default-value="true" disabled>禁用</c-radio>
  </c-space>
</template>
```

### Option Data

Preview configuration: `:options="options"`, `:field-names="fields"`, `orientation="vertical"`, `:options="renderOptions"`.

Example source: src/radio/__demos__/option-data.vue

```vue
<script setup lang="ts">
import { h, ref } from 'vue'

const value = ref<string | number | boolean | null>(null)
const fields = { value: 'id', label: 'name', disabled: 'unavailable', readonly: 'locked' }
const options = ref([
  { id: false, name: '布尔 false' },
  { id: 0, name: '数字 0' },
  { id: '', name: '空字符串' },
  { id: 'locked', name: '只读选项', locked: true },
  { id: 'disabled', name: '禁用选项', unavailable: true },
])
const renderOptions = [
  { value: 'render', label: (_data: unknown, checked: boolean) => h('strong', checked ? '已选择' : '渲染函数标签') },
]
</script>

<template>
  <section class="option-demo">
    <p>字段映射与标签插槽；只读可聚焦，禁用不可操作。</p>
    <c-radio-group v-model="value" :options="options" :field-names="fields" orientation="vertical">
      <template #label="{ data, checked }">{{ data.label }} {{ checked ? '✓' : '' }}</template>
    </c-radio-group>
    <p>当前值：{{ JSON.stringify(value) }}</p>
    <c-button @click="value = null">清空</c-button>
    <p>标签也支持渲染函数；不传 options 时使用默认插槽，传入 [] 时保持空组。</p>
    <c-radio-group :options="renderOptions" />
  </section>
</template>

<style scoped>
.option-demo { display: flex; flex-direction: column; gap: 12px; }
.option-demo p { margin: 0; }
</style>
```

### Controlled

Preview configuration: `:model-value="true"`, `:model-value="checked2"`, `:default-value="true"`.

Example source: src/radio/__demos__/controlled.vue

```vue
<template>
  <c-space wrap size="lg">
    <c-radio v-model="checked1">v-model</c-radio>
    <c-radio :model-value="true">binding "true"</c-radio>
    <c-radio :model-value="checked2">binding value2</c-radio>
    <c-radio :default-value="true">uncontrolled state</c-radio>
  </c-space>
  <div :style="{ marginTop: '20px' }">
    <c-space wrap size="lg">
      <c-button status="primary" @click="handleSetCheck"> {{ checked2 ? 'uncheck' : 'check' }} value2 </c-button>
      <c-button @click="handleReset"> reset all</c-button>
    </c-space>
  </div>
</template>

<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const checked1 = ref(false)
    const checked2 = ref(false)

    const handleSetCheck = () => {
      checked2.value = !checked2.value
    }

    const handleReset = () => {
      checked1.value = false
      checked2.value = false
    }

    return {
      checked1,
      checked2,
      handleSetCheck,
      handleReset,
    }
  },
}
</script>
```

## Interaction and keyboard

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                   | Related examples |
| ------------- | --------------------------------------------------------- | ---------------- |
| `value`       | Option `value`                                            | State Lab        |
| `disabled`    | Disabled state; inherits from the form/group when omitted | State Lab        |
| `readonly`    | Readonly state; inherits from the form/group when omitted | State Lab        |
| `error`       | Error state; inherits from the form/group when omitted    | State Lab        |

<!-- demo-config-notes:end -->

Preview configuration: `value="design"`.

Example source: src/radio/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("design");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-radio v-model="value" value="design" v-bind="__demoState">设计</c-radio>
  </c-space>
</template>
```

### Keyboard Navigation

Preview configuration: `:options="options"`, `aria-label="通知方式"`.

Example source: src/radio/__demos__/keyboard-navigation.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string | number | boolean | null>('email')
const options = [
  { label: '邮件', value: 'email' },
  { label: '只读', value: 'locked', readonly: true },
  { label: '禁用', value: 'disabled', disabled: true },
  { label: '短信', value: 'sms' },
]
</script>
<template>
  <section class="radio-demo">
    <p>Tab 进入分组；方向键循环，Home / End 跳到首尾。只读项可聚焦，不改变选值。</p>
    <c-radio-group v-model="value" :options="options" aria-label="通知方式" />
    <p>当前值：{{ value }}</p>
    <c-button @click="value = null">清空</c-button>
  </section>
</template>
<style scoped>
.radio-demo { display: flex; flex-direction: column; gap: 12px; }
.radio-demo p { margin: 0; }
</style>
```

## Control and content customization

### Native Control

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                   | Related examples             |
| ------------- | --------------------------------------------------------- | ---------------------------- |
| `value`       | Option `value`                                            | Native Control, Custom Radio |
| `readonly`    | Readonly state; inherits from the form/group when omitted | Native Control               |

<!-- demo-config-notes:end -->

- `readonly`: Displays the current value without allowing edits.

Example source: src/radio/__demos__/native-control.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string | number | boolean | null>('email')
</script>
<template>
  <section class="native-radio-demo">
    <p>图标与原生 input 属性</p>
    <c-radio-group v-model="value" name="channel" aria-label="通知方式">
      <c-radio value="email" :icon-size="24" checked-color="rebeccapurple" :input-attrs="{ id: 'radio-email' }">
        <template #checked-icon><span aria-hidden="true">●</span></template>
        <template #unchecked-icon><span aria-hidden="true">○</span></template>
        邮件
      </c-radio>
      <c-radio value="sms">短信</c-radio>
      <c-radio value="readonly" readonly>只读</c-radio>
    </c-radio-group>
    <p>当前值：{{ value }}</p>
  </section>
</template>
<style scoped>
.native-radio-demo { display: flex; flex-direction: column; gap: 12px; }
.native-radio-demo p { margin: 0; }
</style>
```

### Custom Radio

Preview configuration: `default-value="1"`, `value="1"`, `:model-value="checked"`, `checkable`.

Example source: src/radio/__demos__/custom-radio.vue

```vue
<template>
  <c-radio-group default-value="1">
    <c-radio value="1">
      <template #radio="{ checked }">
        <c-tag :model-value="checked" checkable>This is a tag radio 1</c-tag>
      </template>
    </c-radio>
    <c-radio value="2">
      <template #radio="{ checked }">
        <c-tag :model-value="checked" checkable>This is a tag radio 2</c-tag>
      </template>
    </c-radio>
    <c-radio value="3">
      <template #radio="{ checked }">
        <c-tag :model-value="checked" checkable>This is a tag radio 3</c-tag>
      </template>
    </c-radio>
  </c-radio-group>

  <div :style="{ marginTop: '20px' }">
    <c-radio-group>
      <template v-for="item in 2" :key="item">
        <c-radio :value="item">
          <template #radio="{ checked }">
            <c-space wrap align="flex-start" class="custom-radio-card" :class="{ 'custom-radio-card-checked': checked }">
              <div class="custom-radio-card-mask">
                <div class="custom-radio-card-mask-dot" />
              </div>
              <div>
                <div class="custom-radio-card-title">radio Card {{ item }}</div>
                <div>this is a text</div>
              </div>
            </c-space>
          </template>
        </c-radio>
      </template>
    </c-radio-group>
  </div>
</template>

<script lang="ts">
</script>
<style scoped>
.custom-radio-card {
  padding: 10px 16px;
  border: 1px solid var(--color-border-2);
  border-radius: 4px;
  width: 250px;
  box-sizing: border-box;
}

.custom-radio-card-mask {
  height: 14px;
  width: 14px;
  display: inline-flex;
  align-items: center;
  justify-content: center;
  border-radius: 100%;
  border: 1px solid var(--color-border-2);
  box-sizing: border-box;
}

.custom-radio-card-mask-dot {
  width: 8px;
  height: 8px;
  border-radius: 100%;
}

.custom-radio-card-title {
  color: var(--color-text-1);
  font-size: 14px;
  font-weight: bold;
  margin-bottom: 8px;
}

.custom-radio-card:hover,
.custom-radio-card-checked,
.custom-radio-card:hover .custom-radio-card-mask,
.custom-radio-card-checked .custom-radio-card-mask {
  border-color: rgb(var(--primary-6));
}

.custom-radio-card-checked {
  background-color: var(--color-primary-light-1);
}

.custom-radio-card:hover .custom-radio-card-title,
.custom-radio-card-checked .custom-radio-card-title {
  color: rgb(var(--primary-6));
}

.custom-radio-card-checked .custom-radio-card-mask-dot {
  background-color: rgb(var(--primary-6));
}
</style>
```

## Async options

### Async Options

Preview configuration: `edit-mode="direct"`, `:options="options"`.

Example source: src/radio/__demos__/async-options.vue

```vue
<script setup>
import { onDeactivated, onUnmounted, ref, shallowRef } from "vue";

const value = ref("remote");
const options = ref([]);
const loading = ref(false);
const changeCount = ref(0);
let pendingTimer;
const manual = ref(false);
const waiting = shallowRef([]);
const applied = ref(0);
const ignored = ref(0);
let version = 0;
let sequence = 0;

function cancelPending() {
  version++;
  if (pendingTimer !== undefined) {
    clearTimeout(pendingTimer);
  }
  pendingTimer = undefined;
  loading.value = false;
}

function load() {
  cancelPending();
  loading.value = true;
  const ticket = version;
  const id = ++sequence;
  const complete = () => {
    if (ticket !== version) {
      ignored.value++;
      return;
    }
    applied.value = id;
    options.value = [
      { label: "异步设备", value: "remote" },
      { label: "设备 A", value: "a" },
      { label: "停用设备", value: "locked", disabled: true },
    ];
    pendingTimer = undefined;
    loading.value = false;
  };
  if (manual.value) {
    new Promise((resolve) => {
      waiting.value = [...waiting.value, { id, resolve }];
    }).then(complete);
  } else {
    pendingTimer = setTimeout(complete, 800);
  }
}

function settle(latest) {
  const jobs = [...waiting.value];
  const job = latest ? jobs.pop() : jobs.shift();
  waiting.value = jobs;
  job?.resolve();
}

function cleanup() {
  cancelPending();
  const jobs = waiting.value;
  waiting.value = [];
  jobs.forEach((job) => job.resolve());
}

function remove() {
  cancelPending();
  options.value = [];
}

onDeactivated(cleanup);
onUnmounted(cleanup);
</script>

<template>
  <c-space class="radio-async-demo" direction="column">
    <p>业务值独立于当前选项，加载或移除选项不会清空已选值：{{ value }}</p>
    <c-checkbox v-model="manual" edit-mode="direct" @change="remove"
      >Manual responses / 手动返回</c-checkbox
    >
    <c-space wrap>
      <c-button size="sm" @click="load">加载选项</c-button>
      <c-button size="sm" @click="remove">移除选项</c-button>
      <c-button size="sm" @click="value = 'a'">设为设备 A</c-button>
      <c-button size="sm" @click="value = null">清空选择</c-button>
      <c-button
        size="sm"
        :disabled="waiting.length === 0"
        @click="settle(false)"
        >返回最早加载</c-button
      >
      <c-button size="sm" :disabled="waiting.length === 0" @click="settle(true)"
        >返回最新加载</c-button
      >
    </c-space>
    <p aria-live="polite">
      {{
        loading
          ? "加载中，可在完成前移除选项以取消本次加载。"
          : "加载完成后保留当前选值和键盘焦点。"
      }}
    </p>
    <c-radio-group
      v-model="value"
      edit-mode="direct"
      :options="options"
      @change="changeCount++"
    />
    <p>用户变更次数：{{ changeCount }}</p>
    <p role="status">
      Applied: {{ applied }} · Ignored: {{ ignored }} · Pending:
      {{ waiting.length }}
    </p>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

`ChoiceValue = string | number | boolean`；`CheckboxModel = boolean | ChoiceValue[]`；`RadioModel = ChoiceValue | null`。

### Radio Props

| Prop                  | Description                                               | Type                      | Default   |
| --------------------- | --------------------------------------------------------- | ------------------------- | --------- |
| model-value (v-model) | Controlled value                                          | ChoiceValue \| null       | undefined |
| default-value         | Initial uncontrolled value                                | ChoiceValue \| null       | null      |
| value                 | Option `value`                                            | `string\|number\|boolean` | `true`    |
| variant               | Radio variant                                             | `'radio'\|'button'`       | `'radio'` |
| disabled              | Disabled state; inherits from the form/group when omitted | boolean                   | undefined |
| readonly              | Readonly state; inherits from the form/group when omitted | boolean                   | undefined |
| error                 | Error state; inherits from the form/group when omitted    | boolean                   | undefined |

### Radio Events

| Event              | Description          | Arguments                         |
| ------------------ | -------------------- | --------------------------------- |
| update:model-value | Proposes a new value | value: ChoiceValue                |
| change             | Value change         | value: ChoiceValue, event?: Event |
| focus              | Focus                | event: FocusEvent                 |
| blur               | Blur                 | event: FocusEvent                 |

### Radio Methods

| Method | Arguments              | Returns |
| ------ | ---------------------- | ------- |
| select | -                      | void    |
| focus  | options?: FocusOptions | void    |
| blur   | -                      | void    |

### Radio Slots

| Slot  | Description          | Arguments                                |
| ----- | -------------------- | ---------------------------------------- |
| radio | Custom radio control | `checked:boolean`<br/>`disabled:boolean` |

### RadioGroup Props

| Prop                  | Description                                                                                            | Type                                                                                                    | Default        |
| --------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | -------------- |
| model-value (v-model) | Controlled value                                                                                       | RadioModel                                                                                              | undefined      |
| default-value         | Initial uncontrolled value                                                                             | RadioModel                                                                                              | null           |
| variant               | Radio-group variant                                                                                    | `'radio'\|'button'`                                                                                     | `'radio'`      |
| size                  | Radio-group size                                                                                       | `'xs'\|'sm'\|'md'\|'lg'\|'xl'`                                                                          | `-`            |
| options               | Options; replaces default slot when supplied                                                           | Array<ChoiceValue \| RadioOption \| Record<string, unknown>> / `(query, { signal }) => Array / Promise` | `undefined`    |
| orientation           | Horizontal/vertical arrangement of radio-group options, default horizontal; not text reading direction | `'horizontal'\|'vertical'`                                                                              | `'horizontal'` |
| disabled              | Disabled state; inherits from the form/group when omitted                                              | boolean                                                                                                 | undefined      |
| readonly              | Readonly state; inherits from the form/group when omitted                                              | boolean                                                                                                 | undefined      |
| error                 | Error state; inherits from the form/group when omitted                                                 | boolean                                                                                                 | undefined      |
| field-names           | Option field mapping                                                                                   | ChoiceFieldNames                                                                                        | undefined      |
| aria-label            | Accessible group name                                                                                  | string                                                                                                  | ''             |

### RadioGroup Events

| Event              | Description                          | Arguments                                      |
| ------------------ | ------------------------------------ | ---------------------------------------------- |
| update:model-value | Proposes a new value                 | value: string \| number \| boolean             |
| change             | Value change; notified once by Group | value: string \| number \| boolean, ev?: Event |

### RadioGroup Slots

| Slot  | Description          | Arguments                                |
| ----- | -------------------- | ---------------------------------------- |
| radio | Custom radio control | `checked:boolean`<br/>`disabled:boolean` |
| label | Radio label content  | `data: RadioOption, checked: boolean`    |

### RadioOption

| Field    | Description              | Type                                                              |
| -------- | ------------------------ | ----------------------------------------------------------------- |
| value    | Option identity          | ChoiceValue                                                       |
| label    | Label or render function | VNodeChild \| (data: RadioOption, checked: boolean) => VNodeChild |
| disabled | Disable interaction      | boolean                                                           |
| readonly | Read-only interaction    | boolean                                                           |

## Type definitions

The component exports the following types

```ts
import type { RadioProps } from "@cedar-design/ui";
```

### ChoiceFieldNames

`{ label?: string; value?: string; disabled?: string; readonly?: string; indeterminate?: string }`

Exported types：`RadioOption`、`ChoiceFieldNames`。

### Native attributes and appearance

| Component          | Prop                            | Description                                                       | Type                | Default   |
| ------------------ | ------------------------------- | ----------------------------------------------------------------- | ------------------- | --------- |
| Radio / RadioGroup | name                            | Native field name; child overrides group                          | string              | undefined |
| Radio              | aria-label                      | Native control accessible name                                    | string              | undefined |
| Radio              | input-attrs                     | Native input attributes                                           | InputHTMLAttributes | undefined |
| Radio              | checked-color / unchecked-color | Instance checked/unchecked colors; error/disabled take precedence | string              | undefined |
| Radio              | icon-size                       | Icon dimension; numbers are px, strings are CSS lengths           | number \| string    | undefined |
| Radio              | ripple                          | Touch ripple feedback                                             | boolean             | true      |

### Icons and default slot

checked-icon and unchecked-icon are supported on both platforms. default and radio slots receive { checked, disabled }. click emits the original MouseEvent once. Disabled emits no click; readonly may emit click without changing the value.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

The `options` prop accepts an array or `(query, { signal }) => array/Promise`. The component manages loading, cancellation and stale-result isolation; failures emit load-error. Single/multiple groups initialize with an empty-string query, searchable fields reload when the query changes, and root loading for tree fields remains independent of existing load-more child loading.

---

Document: llms/en-US/components/rate.md

<!-- Source: src/rate/README.en-US.md; locale: en-US; page: /en/components/rate/ -->

# Rate

Keyboard and pointer rating selection.

## Basic examples

### Basic usage

Example source: src/rate/__demos__/basic.vue

```vue
<template>
  <c-rate  />
</template>

<script lang="ts" setup>
</script>
```

## Appearance and states

### Readonly

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                        | Related examples |
| --------------- | -------------------------------------------------------------- | ---------------- |
| `default-value` | Initial uncontrolled value; subsequent changes do not reset it | Readonly         |
| `readonly`      | Focusable but not editable; inherits Form when omitted         | Readonly         |
| `color`         | Active color or increasing per-icon threshold color map        | Color            |

<!-- demo-config-notes:end -->

- `readonly`: Displays the current value without allowing edits.

Example source: src/rate/__demos__/readonly.vue

```vue
<template>
  <c-rate :default-value="4" readonly />
</template>

<script lang="ts" setup>
</script>
```

### Color

- `color`: Overrides the color.

Example source: src/rate/__demos__/color.vue

```vue
<template>
  <c-space direction="column">
    <c-rate color="red" />
    <c-rate :color="color" />
  </c-space>
</template>

<script lang="ts" setup>
const color = {
  2: 'red',
  4: 'green',
  5: 'blue',
}
</script>
```

## Content and presentation

### Sizes And Symbols

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                           | Related examples                                   |
| --------------- | ----------------------------------------------------------------- | -------------------------------------------------- |
| `default-value` | Initial uncontrolled value; subsequent changes do not reset it    | Sizes And Symbols, Half, Rating count and clearing |
| `allow-half`    | Enable half-point steps                                           | Sizes And Symbols, Half                            |
| `grading`       | Fixed five-face rating; overrides slots and icon props            | Sizes And Symbols, Grading                         |
| `size`          | Icon dimension: number/numeric string in px, otherwise CSS length | Sizes And Symbols                                  |
| `aria-label`    | Accessible business label                                         | Sizes And Symbols                                  |
| `gap`           | Icon spacing: number/numeric string in px, otherwise CSS length   | Sizes And Symbols                                  |

<!-- demo-config-notes:end -->

- `size`: Controls the component size.

Example source: src/rate/__demos__/sizes-and-symbols.vue

```vue
<template>
  <c-space direction="column">
    <c-rate :default-value="3" :size="20" aria-label="20 像素评分" />
    <c-rate :default-value="3.5" size="2rem" gap="0.5rem" allow-half aria-label="自定义尺寸评分" />
    <c-rate :default-value="4" grading aria-label="表情评分" />
    <c-rate :default-value="3" aria-label="自定义字符评分">
      <template #character="{ value, active }"><span>{{ active ? '♥' : '♡' }}{{ value }}</span></template>
    </c-rate>
  </c-space>
</template>
```

### Half

Example source: src/rate/__demos__/half.vue

```vue
<template>
  <c-rate :default-value="2.5" allow-half />
</template>

<script lang="ts" setup>
</script>
```

### Rating count and clearing

Compare rating totals and clearing the current selection, separately from half steps, keyboards and controlled values.

Example source: src/rate/__demos__/value-rules-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="clear">
    <h4><span lang="zh-CN">支持清除</span><span lang="en-US">clear</span></h4>
    <c-rate :default-value="3" clearable />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="count">
    <h4><span lang="zh-CN">任意长度的评分</span><span lang="en-US">count</span></h4>
    <c-rate :count="10" />
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Grading

Example source: src/rate/__demos__/grading.vue

```vue
<template>
  <c-rate grading />
</template>

<script lang="ts" setup>
</script>
```

## Customization and slots

### Character

Example source: src/rate/__demos__/character.vue

```vue
<template>
  <c-rate :default-value="2">
    <template #character="index">
      <c-icon-check v-if="index < 3" />
      <c-icon-close v-else />
    </template>
  </c-rate>
</template>

<script lang="ts" setup>
</script>
```

## Interaction and control

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                  | Related examples    |
| --------------- | ------------------------------------------------------------------------ | ------------------- |
| `disabled`      | Disable interaction; inherits Form when omitted                          | State Lab, Keyboard |
| `readonly`      | Focusable but not editable; inherits Form when omitted                   | State Lab, Keyboard |
| `allow-half`    | Enable half-point steps                                                  | Keyboard            |
| `clearable`     | Click the current score again to clear; keyboard boundaries do not clear | Keyboard            |
| `aria-label`    | Accessible business label                                                | Keyboard            |
| `default-value` | Initial uncontrolled value; subsequent changes do not reset it           | Keyboard            |

<!-- demo-config-notes:end -->

Example source: src/rate/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(3);
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-rate v-model="value" v-bind="__demoState"></c-rate>
  </c-space>
</template>
```

### Keyboard

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/rate/__demos__/keyboard.vue

```vue
<script setup>
import { ref } from 'vue'
const score = ref(2.5)
</script>

<template>
  <c-space direction="column">
    <p>Tab 聚焦；方向键按半分调整；Home 清零，End 满分。重复点击当前分数可清空。</p>
    <c-rate v-model="score" allow-half clearable aria-label="服务评分" />
    <span>当前评分：{{ score }}</span>
    <c-rate :default-value="3" readonly aria-label="只读评分" />
    <c-rate :default-value="3" disabled aria-label="禁用评分" />
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Prop           | Description                                                              | Type                             | Default       |
| -------------- | ------------------------------------------------------------------------ | -------------------------------- | ------------- |
| model-value    | Controlled value, including zero; external updates emit no events        | number                           | undefined     |
| default-value  | Initial uncontrolled value; subsequent changes do not reset it           | number                           | 0             |
| count          | Positive finite number, rounded down; invalid values fall back to 5      | number \| string                 | 5             |
| allow-half     | Enable half-point steps                                                  | boolean                          | false         |
| clearable      | Click the current score again to clear; keyboard boundaries do not clear | boolean                          | false         |
| grading        | Fixed five-face rating; overrides slots and icon props                   | boolean                          | false         |
| disabled       | Disable interaction; inherits Form when omitted                          | boolean                          | undefined     |
| readonly       | Focusable but not editable; inherits Form when omitted                   | boolean                          | undefined     |
| aria-label     | Accessible business label                                                | string                           | undefined     |
| size           | Icon dimension: number/numeric string in px, otherwise CSS length        | number \| string                 | Style default |
| gap            | Icon spacing: number/numeric string in px, otherwise CSS length          | number \| string                 | Style default |
| color          | Active color or increasing per-icon threshold color map                  | string \| Record<string, string> | undefined     |
| empty-color    | Inactive color                                                           | string                           | undefined     |
| disabled-color | Disabled color, overriding active/inactive colors                        | string                           | undefined     |
| icon           | Checked icon                                                             | string \| Component              | Filled star   |
| half-icon      | Half icon                                                                | string \| Component              | Half star     |
| empty-icon     | Unchecked icon                                                           | string \| Component              | Empty star    |
| ripple         | Click ripple                                                             | boolean                          | true          |

size/gap do not accept xs/sm/md/lg/xl presets. Omitted, invalid or nonpositive values retain style defaults. CSS var/calc/min/max/clamp lengths are supported. Ratings normalize to 0–count in steps of 1 or 0.5. Nonfinite ratings display 0 without rewriting the external value.

### Events

| Event              | Arguments     | Description                                                   |
| ------------------ | ------------- | ------------------------------------------------------------- |
| update:model-value | value: number | User produces a new value                                     |
| change             | value: number | Confirmed new value; no duplicate for equal values            |
| hover-change       | value: number | Hover preview; resets to zero on leave/blur/disabled/readonly |

### Slots

| Slot      | Arguments                | Description                                                   |
| --------- | ------------------------ | ------------------------------------------------------------- |
| character | { index, value, active } | index starts at 0; value starts at 1. Replaces rating symbols |

Precedence: grading > character > icon/half-icon/empty-icon > default icon. String icons require global registration; component values do not.

### Methods

focus() focuses the rating; blur() removes focus. Readonly remains focusable, while disabled leaves the Tab sequence. Arrow keys adjust, Home clears and End selects the maximum. Keyboard events from interactive children and Alt/Ctrl/Meta combinations are not intercepted. Touch and mouse share half-selection/clearing rules.

### Type definitions

Exports RateProps, RateColor, RateIcon, RateInstance, RateExpose, RateEmits and RateCharacterSlotProps.

### Style variables

| Token                                 | Default                                        |
| ------------------------------------- | ---------------------------------------------- |
| `--c-rate-disabled-color`             | `var(--c-sys-color-content-disabled)`          |
| `--c-rate-error-color`                | `var(--c-sys-color-content-danger)`            |
| `--c-rate-active-scale`               | `1.2`                                          |
| `--c-rate-focus-color`                | `var(--c-sys-color-content-brand)`             |
| `--c-rate-focus-width`                | `2px`                                          |
| `--c-rate-focus-offset`               | `2px`                                          |
| `--c-rate-size`                       | `var(--c-font-size-title-3)`                   |
| `--c-rate-gap`                        | `var(--c-spacing-4)`                           |
| `--c-rate-min-height`                 | `var(--c-size-md)`                             |
| `--c-rate-action-padding`             | `0px`                                          |
| `--c-rate-empty-color`                | `var(--c-color-fill-3)`                        |
| `--c-rate-active-color`               | `rgb(var(--c-gold-6))`                         |
| `--c-rate-transition-duration`        | `var(--c-transition-duration-2)`               |
| `--c-rate-scale-duration`             | `var(--c-transition-duration-4)`               |
| `--c-rate-transition-timing-function` | `var(--c-transition-timing-function-standard)` |

Public token suffixes/meanings match across platforms. Cedar retains gold stars and compact spacing; Maple retains primary-color stars and touch padding. Defaults are recorded in the theme contract. Sources are maintained independently without a shared runtime.

`transition-duration` controls hover/color transitions, `scale-duration` controls selection animation, and `transition-timing-function` controls easing. Reduced motion disables these animations. `size` and `gap` props override the corresponding tokens for a single instance.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/resize-box.md

<!-- Source: src/resize-box/README.en-US.md; locale: en-US; page: /en/components/resize-box/ -->

# Resize Box

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `directions`: Can be stretched side, there are up, down, left and right can be used

Example source: src/resize-box/__demos__/basic.vue

```vue
<template>
  <div>
    <c-resize-box
      :directions="['right', 'bottom']"
      :style="{ width: '500px', minWidth: '100px', maxWidth: '100%', height: '200px', textAlign: 'center' }"
    >
      <c-typography-paragraph>We are building the future of content discovery and creation.</c-typography-paragraph>
      <c-divider  />
      <c-typography-paragraph>
        ByteDance's content platforms enable people to enjoy content powered by AI technology. We inform, entertain, and
        inspire people across language, culture and geography.
      </c-typography-paragraph>
      <c-divider>ByteDance</c-divider>
      <c-typography-paragraph>Yiming Zhang is the founder and CEO of ByteDance.</c-typography-paragraph>
    </c-resize-box>
  </div>
</template>

<script lang="ts" setup>
</script>
```

## Layout and arrangement

### Layout

Preview configuration: `:resize-directions="['right']"`.

Example source: src/resize-box/__demos__/layout.vue

```vue
<template>
  <div class="layout-demo">
    <c-layout>
      <c-layout-header>Header</c-layout-header>
      <c-layout>
        <c-layout-sider :resize-directions="['right']"> Sider </c-layout-sider>
        <c-layout-content>Content</c-layout-content>
      </c-layout>
      <c-layout-footer>Footer</c-layout-footer>
    </c-layout>
  </div>
</template>

<script lang="ts" setup>
</script>

<style scoped>
.layout-demo :deep(.c-layout-header),
.layout-demo :deep(.c-layout-footer),
.layout-demo :deep(.c-layout-sider-children),
.layout-demo :deep(.c-layout-content) {
  display: flex;
  flex-direction: column;
  justify-content: center;
  color: var(--color-white);
  font-size: 16px;
  font-stretch: condensed;
  text-align: center;
}

.layout-demo :deep(.c-layout-header),
.layout-demo :deep(.c-layout-footer) {
  height: 64px;
  background-color: var(--color-primary-light-4);
}

.layout-demo :deep(.c-layout-sider) {
  width: 206px;
  background-color: var(--color-primary-light-3);
  min-width: 150px;
  max-width: 500px;
  height: 200px;
}

.layout-demo :deep(.c-layout-content) {
  background-color: rgb(var(--brand-6));
}
</style>
```

## Interaction and control

### Controlled

- `directions`: Can be stretched side, there are up, down, left and right can be used
- `width`: Width
- `height`: Height

Example source: src/resize-box/__demos__/controlled.vue

```vue
<template>
  <div>
    <c-resize-box
      :directions="['right', 'bottom']"
      :style="{ minWidth: '100px', maxWidth: '100%', textAlign: 'center' }"
      v-model:width="width"
      v-model:height="height"
    >
      <c-typography-paragraph>We are building the future of content discovery and creation.</c-typography-paragraph>
      <c-divider  />
      <c-typography-paragraph>
        ByteDance's content platforms enable people to enjoy content powered by AI technology. We inform, entertain, and
        inspire people across language, culture and geography.
      </c-typography-paragraph>
      <c-divider>ByteDance</c-divider>
      <c-typography-paragraph>Yiming Zhang is the founder and CEO of ByteDance.</c-typography-paragraph>
    </c-resize-box>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const width = ref(500)
const height = ref(200)
</script>
```

### Custom Triggers

- `directions`: Can be stretched side, there are up, down, left and right can be used

Example source: src/resize-box/__demos__/custom-triggers.vue

```vue
<template>
  <c-resize-box
    :directions="['right', 'bottom']"
    style="width: 500px; min-width: 100px; max-width: 100%; height: 200px; text-align: center"
  >
    <template #resize-trigger="{ direction }">
      <div :class="[`resizebox-demo`, `resizebox-demo-${direction === 'right' ? 'vertical' : 'horizontal'}`]">
        <div class="resizebox-demo-line" />
      </div>
    </template>
    <c-typography-paragraph>We are building the future of content discovery and creation.</c-typography-paragraph>
    <c-divider  />
    <c-typography-paragraph>
      ByteDance's content platforms enable people to enjoy content powered by AI technology. We inform, entertain, and
      inspire people across language, culture and geography.
    </c-typography-paragraph>
    <c-divider>ByteDance</c-divider>
    <c-typography-paragraph>Yiming Zhang is the founder and CEO of ByteDance.</c-typography-paragraph>
  </c-resize-box>
</template>

<script lang="ts" setup>
</script>

<style scoped>
.resizebox-demo {
  position: relative;
  display: flex;
  align-items: center;
  justify-content: center;
  width: 100%;
  height: 100%;
  background-color: var(--c-color-bg-white);
}

.resizebox-demo::before,
.resizebox-demo::after {
  width: 6px;
  height: 6px;
  border: 1px solid rgb(var(--brand-6));
  content: '';
}

.resizebox-demo-line {
  flex: 1;
  background-color: rgb(var(--brand-6));
}

.resizebox-demo-vertical {
  flex-direction: column;
}

.resizebox-demo-vertical .resizebox-demo-line {
  width: 1px;
  height: 100%;
}

.resizebox-demo-horizontal .resizebox-demo-line {
  height: 1px;
}
</style>
```

## API

### `<resize-box>` Props

| Parameter | Description | Type | Default |
| -------------------- | ------------------------------------------ | -------------------------------------------- | :---------: |
| width **(v-model)** | Width | `number` | `-` |
| height **(v-model)** | Surface height | `number` | `-` |
| component | The html tag of the telescopic box | `string` | `'div'` |
| directions | Edges with enabled resize handles, right only by default. Any combination of top/right/bottom/left; describes neither pointer movement nor popup placement | `('left' \| 'right' \| 'top' \| 'bottom')[]` | `['right']` |

### `<resize-box>` Events

| Event | Description | Arguments |
| ------------ | -------------- | -------------------------------------------------------------- |
| moving-start | Emitted when dragging starts | ev: `MouseEvent` |
| moving | Emitted during dragging | size: `{ width: number; height: number; }`<br>ev: `MouseEvent` |
| moving-end | Emitted when dragging ends | ev: `MouseEvent` |

### `<resize-box>` Slots

| Slot | Description | Arguments |
| ------------------- | :----------: | --------------------------------------------------- |
| resize-trigger | Resize-handle content | direction: `'left' \| 'right' \| 'top' \| 'bottom'` |
| resize-trigger-icon | Resize-handle icon | direction: `'left' \| 'right' \| 'top' \| 'bottom'` |

### Type definitions

The component exports the following types

```ts
import type { ResizeBoxInstance } from '@cedar-design/ui'
```


### Placement semantics and configuration

directions means edges with enabled resize handles; the existing name is retained. Only the right edge is enabled by default; multiple edges can be combined. It is neither an orientation axis nor popup placement. Edges is a more direct name for a new design, but this update does not rename the API.


## Reading direction and interaction

ResizeBox directions name physical edges: left/right/top/bottom retain their sides in RTL. Handles support the corresponding axis arrow keys, mouse and touch pointers; Shift increases the step from 10px to 50px. Dimensions clamp at zero. Direction changes, edge removal and teardown cancel active gestures and release cursor ownership.

---

Document: llms/en-US/components/result.md

<!-- Source: src/result/README.en-US.md; locale: en-US; page: /en/components/result/ -->

# Result

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `status`: Selects the semantic state.

Example source: src/result/__demos__/basic.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
const statuses = ['info', 'success', 'warning', 'danger', 'question', 'empty'] as const
const index = ref(0)
const status = computed(() => statuses[index.value])
</script>

<template>
  <c-result data-demo-result :status="status" :title="'Result: ' + status" subtitle="Local state preview">
    <template #extra>
      <c-space wrap>
        <c-button status="primary" @click="index = (index + 1) % statuses.length">Next status</c-button>
        <c-button @click="index = 0">Reset status</c-button>
      </c-space>
      <p aria-live="polite">Current status: {{ status }}</p>
    </template>
  </c-result>
</template>
```

## Content and presentation

### Success, warning and failure

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Result-page status | Success, warning and failure, HTTP result states, All |
| `title` | Title content | Success, warning and failure, All |
| `subtitle` | Subtitle content | HTTP result states |
<!-- demo-config-notes:end -->


Compare how semantic states affect the icon, title and actions. HTTP statuses and custom artwork remain separate.

Example source: src/result/__demos__/status-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="success">
    <h4><span lang="zh-CN">成功状态</span><span lang="en-US">success</span></h4>
    <c-result status="success" title="This is title content">
        <template #subtitle> This is subtitle content </template>
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="warning">
    <h4><span lang="zh-CN">警告状态</span><span lang="en-US">warning</span></h4>
    <c-result status="warning" title="This is title content">
        <template #subtitle> This is subtitle content </template>
    
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="error">
    <h4><span lang="zh-CN">错误状态</span><span lang="en-US">error</span></h4>
    <c-result status="danger" title="This is title content">
        <template #subtitle> This is subtitle content </template>
    
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### HTTP result states

Compare permission, missing-resource and server-error content, with recovery actions appropriate to each case.

Example source: src/result/__demos__/http-status-comparison.vue

```vue
<script setup lang="ts">


</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="403">
    <h4><span lang="zh-CN">HTTP状态码 403</span><span lang="en-US">403</span></h4>
    <c-result status="403" subtitle="Access to this resource on the server is denied.">
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="404">
    <h4><span lang="zh-CN">HTTP状态码 404</span><span lang="en-US">404</span></h4>
    <c-result status="404" subtitle="Whoops, that page is gone.">
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="500">
    <h4><span lang="zh-CN">HTTP状态码 500</span><span lang="en-US">500</span></h4>
    <c-result status="500" subtitle="This page isn’t working.">
        <template #extra>
          <c-space>
            <c-button status="primary">Back</c-button>
          </c-space>
        </template>
      </c-result>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### All

- `status`: Selects the semantic state.

Example source: src/result/__demos__/all.vue

```vue
<template>
  <c-result status="danger" title="No internet ">
    <template #icon>
      <c-icon-face-frown-fill />
    </template>
    <template #subtitle> DNS_PROBE_FINISHED_NO_INTERNET</template>

    <template #extra>
      <c-button status="primary">Refresh</c-button>
    </template>
    <c-typography style="background: var(--color-fill-2); padding: 24px">
      <c-typography-paragraph>Try:</c-typography-paragraph>
      <ul>
        <li>Checking the network cables, modem, and router</li>
        <li>Reconnecting to Wi-Fi</li>
      </ul>
    </c-typography>
  </c-result>
</template>

<script lang="ts" setup>
</script>
```

## Customization and slots

### Custom

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Title content | Custom |
| `subtitle` | Subtitle content | Custom |
<!-- demo-config-notes:end -->


Preview configuration: `title="This is title content"`, `subtitle="This is subtitle content"`.

Example source: src/result/__demos__/custom.vue

```vue
<template>
  <c-result title="This is title content" subtitle="This is subtitle content">
    <template #icon>
      <c-icon-face-smile-fill />
    </template>
    <template #extra>
      <c-space>
        <c-button status="secondary">Again</c-button>
        <c-button status="primary">Back</c-button>
      </c-space>
    </template>
  </c-result>
</template>

<script lang="ts" setup>
</script>
```

## API

### `<result>` Props

| Parameter | Description | Type | Default |
| -------- | ---------------- | -------------------------------------------------------------------------------- | :------: |
| status | Result-page status | `'info' \| 'success' \| 'warning' \| 'danger' \| 'question' \| 'empty' \| '403' \| '404' \| '500'` | `'info'` |
| title | Title content | `string` | `-` |
| subtitle | Subtitle content | `string` | `-` |
| image-size | Status graphic size; numbers are px | `string \| number` | `-` |
| animation | Whether status-graphic animation is enabled | `boolean` | `true` |

### `<result>` Slots

| Slot | Description | Arguments | Version |
| -------- | :------: | ---- | :---- |
| icon | Custom status graphic | `{ size?: string }` |  |
| title | Title | - |  |
| subtitle | Subtitle | - |  |
| extra | Actions | - | 2.8.0 |
| default | Default slot | - | 2.8.0 |

### Type definitions

The component exports the following types

```ts
import type { ResultInstance } from '@cedar-design/ui'
```

---

Document: llms/en-US/components/ripple.md

<!-- Source: src/ripple/README.en-US.md; locale: en-US; page: /en/components/ripple/ -->

# Ripple

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/ripple/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import { Ripple } from "@cedar-design/ui";
import "@cedar-design/ui/ripple/style";

const vRipple = Ripple;
const disabled = ref(false);
</script>

<template>
  <c-space wrap>
    <div role="button" tabindex="0" v-ripple="{ disabled }" class="ripple-demo"
      >Ripple</div
    >
    <div
      role="button" tabindex="0"
      v-ripple="{ disabled }"
      class="ripple-demo ripple-demo--long"
      >600ms 扩散／800ms 消退</div
    >
    <c-button @click="disabled = !disabled">{{
      disabled ? "启用水波" : "禁用水波"
    }}</c-button>
  </c-space>
</template>

<style scoped>
.ripple-demo--long {
  --c-ripple-expand-duration: 600ms;
  --c-ripple-fade-duration: 800ms;
}
.ripple-demo {
  position: relative;
  overflow: hidden;
  padding: 8px 20px;
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-sm);
  color: var(--c-sys-color-action-primary);
  background: var(--c-sys-color-surface-overlay);
  cursor: pointer;
}
</style>
```

## Options

| Options | Description | Type | Default |
| --- | --- | --- | --- |
| color | Ripple color | `string` | `currentColor` |
| disabled | Prevent ripples and cancel pending animation | `boolean` | `false` |

Use `v-ripple="{ color, disabled }"`. Unmount cancels animations/timers and removes listeners; each element maintains independent keyboard state.

## Styles

For direct directive registration, import `@cedar-design/ui/ripple/style`. Runtime imports no CSS, supporting SSR package imports. Variables use `--c-ripple-*` and are declared in `style/token.less`. Theme defaults may differ from mobile while motion/consumption protocols stay aligned.

| Variable | Default | Responsibility |
| --- | --- | --- |
| --c-ripple-color | currentColor | Ripple background; color option takes precedence |
| --c-ripple-cubic-bezier | cubic-bezier(0.68, 0.01, 0.62, 0.6) | Transform expansion easing |
| --c-ripple-expand-duration | 200ms | Transform expansion duration |
| --c-ripple-fade-duration | 140ms | Linear opacity appear/fade duration |

Variables belong on the actual directive host and inherit into ripples. Defaults currently match across platforms. 250ms is the minimum postcreation display/postfade removal wait, not visual duration or the entire lifecycle. Runtime reads computed transition duration/delay. Fade waits until the later of creation+250ms or activation+expansion duration; removal waits max(250ms, fade duration). Long overrides are not truncated. 0ms/unstyled retain cleanup floors. Reduced motion hides decoration. Expansion samples on creation/activation, fade on fade start; arbitrary midphase CSS changes/animations are not guaranteed.

Repeated release queues once. Disabling/unmounting cleans owned timers/direct ripples without deleting nested instances. Document listeners bind/remove against mount-time ownerDocument, without automatic cross-document rebinding. Only host Enter/Space and matching keyup/blur participate. The directive does not supply button semantics, accessible names or business clicking to plain divs. Real touch/OS preferences need separate validation.

---

Document: llms/en-US/components/row.md

<!-- Source: src/row/README.en-US.md; locale: en-US; page: /en/components/row/ -->

# Row

24-column Flex layout. Row manages gutters and alignment; Col manages spans, offsets, ordering and breakpoints. Use Grid for CSS Grid collapse and suffix items.

> **Choosing a layout**
>
> - Grid + GridItem: Use for form columns and card grids with consistent column widths, spans, responsive column counts, or collapsed rows and suffix items.
> - Row + Col: Use for 24-column Flex layouts that need horizontal/vertical alignment, wrapping control, fixed and flexible widths together, or responsive ordering. Row controls the row; Col controls width, offset and order.
> - Space: Use for simple groups of buttons, tags or text that only need spacing, direction and alignment. Use native Flex for more flexible width allocation.

## Basic examples

### 24-column layout

Example source: src/row/__demos__/basic.vue

```vue
<template><div>
  <c-row :gutter="12"><c-col :span="12"><div class="cell">12</div></c-col><c-col :span="12"><div class="cell soft">12</div></c-col></c-row>
  <c-row :gutter="12"><c-col v-for="i in 3" :key="i" :span="8"><div class="cell">8</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

## Layout and arrangement

### Two-axis and responsive gutters

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `gutter` | Gutter: number, responsive object or [horizontal, vertical] | Two-axis and responsive gutters, Horizontal and vertical alignment, Wrapping and plain container mode |
| `justify` | Horizontal alignment | Horizontal and vertical alignment, Layout Lab |
| `align` | Vertical alignment | Horizontal and vertical alignment, Layout Lab |
| `wrap` | Wrap columns | Wrapping and plain container mode |
| `div` | Use Row and Col as plain divs without layout styles | Wrapping and plain container mode |
<!-- demo-config-notes:end -->


Example source: src/row/__demos__/gutter.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const gap = ref(16)
const vertical = ref(true)
</script>
<template><div>
  <div class="controls"><c-radio-group v-model="gap"><c-radio v-for="value in [0, 8, 16, 24]" :key="value" :value="value">{{ value }}px</c-radio></c-radio-group><c-switch v-model="vertical" aria-label="Vertical gutter" />Vertical gap</div>
  <c-row :gutter="[gap, vertical ? gap : 0]"><c-col v-for="i in 6" :key="i" :span="8"><div class="cell">{{ i }}</div></c-col></c-row>
  <c-row :gutter="[{ xs: 8, md: 24 }, { xs: 8, md: 16 }]"><c-col v-for="i in 4" :key="i" :span="12"><div class="cell soft">Responsive gap</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### Horizontal and vertical alignment

Example source: src/row/__demos__/alignment.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const justifies = ['start', 'center', 'end', 'space-around', 'space-between'] as const
const aligns = ['start', 'center', 'end', 'stretch'] as const
const justify = ref<typeof justifies[number]>('space-between')
const align = ref<typeof aligns[number]>('center')
</script>
<template><div>
  <c-radio-group v-model="justify"><c-radio v-for="value in justifies" :key="value" :value="value">{{ value }}</c-radio></c-radio-group>
  <c-radio-group v-model="align"><c-radio v-for="value in aligns" :key="value" :value="value">{{ value }}</c-radio></c-radio-group>
  <c-row :gutter="12" :justify="justify" :align="align"><c-col v-for="i in 3" :key="i" :span="6"><div class="cell" :style="{ minHeight: `${36 + i * 24}px`, height: '100%' }">{{ i }}</div></c-col></c-row>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### Wrapping and plain container mode

Example source: src/row/__demos__/wrap.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const wrap = ref(true)
const div = ref(false)
</script>
<template><div>
  <div class="controls"><c-switch v-model="wrap" aria-label="Wrap" />Wrap<c-switch v-model="div" aria-label="Plain div" />Plain div</div>
  <div style="overflow: auto; padding: 8px"><c-row :gutter="12" :wrap="wrap" :div="div"><c-col v-for="i in 3" :key="i" :span="12"><div class="cell">{{ i }}</div></c-col></c-row></div>
</div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

### Nested rows and isolated gutters

Example source: src/row/__demos__/nested.vue

```vue
<template><div><c-row :gutter="24"><c-col :span="16"><c-row :gutter="8"><c-col :span="12"><div class="cell">Inner 12</div></c-col><c-col :span="12"><div class="cell soft">Inner 12</div></c-col></c-row></c-col><c-col :span="8"><div class="cell">Outer 8</div></c-col></c-row></div></template>

<style scoped>
.controls { display: flex; flex-wrap: wrap; align-items: center; gap: 12px; }
.cell { box-sizing: border-box; padding: 12px; min-width: 0; border-radius: 4px; background: var(--c-color-primary); color: var(--c-color-white); text-align: center; overflow-wrap: anywhere; }
.soft { opacity: .7; }
</style>
```

<!-- same-source-api:start -->

### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| gutter | Gutter: number, responsive object or [horizontal, vertical] | `RowGutter` | `0` |
| justify | Horizontal alignment | `start / center / end / space-around / space-between` | `start` |
| align | Vertical alignment | `start / center / end / stretch` | `start` |
| wrap | Wrap columns | `boolean` | `true` |
| div | Use Row and Col as plain divs without layout styles | `boolean` | `false` |

### Events

| Event | Description |
| --- | --- |
| click | Native MouseEvent, emitted once per click |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

The wrap example toggles wrapping and plain `div` mode independently. Plain mode removes Row layout styles and child Col spacing; gutter controls distinguish horizontal spacing from vertical spacing. Row uses Flex, not CSS Grid.

### Layout Lab

Example source: src/row/__demos__/layout-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoLayout = __demoReactive({ align: "start", justify: "start" });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="align">
        <c-radio-group
          v-model="__demoLayout['align']"
          aria-label="align"
          :options="[
            { label: 'start', value: 'start' },
            { label: 'center', value: 'center' },
            { label: 'end', value: 'end' },
            { label: 'stretch', value: 'stretch' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="justify">
        <c-radio-group
          v-model="__demoLayout['justify']"
          aria-label="justify"
          :options="[
            { label: 'start', value: 'start' },
            { label: 'center', value: 'center' },
            { label: 'end', value: 'end' },
            { label: 'space-around', value: 'space-around' },
            { label: 'space-between', value: 'space-between' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <c-row :gutter="12" v-bind="__demoLayout"
      ><c-col v-for="i in 3" :key="i" :span="8"
        ><div class="cell">8</div></c-col
      ></c-row
    >
  </c-space>
</template>
<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
}
.cell {
  box-sizing: border-box;
  padding: 12px;
  min-width: 0;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: var(--c-color-white);
  text-align: center;
  overflow-wrap: anywhere;
}
.soft {
  opacity: 0.7;
}
</style>
```

## API

<!-- same-source-api:start -->
### Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| gutter | Gutter: number, responsive object or [horizontal, vertical] | `RowGutter` | `0` |
| justify | Horizontal alignment | `start / center / end / space-around / space-between` | `start` |
| align | Vertical alignment | `start / center / end / stretch` | `start` |
| wrap | Wrap columns | `boolean` | `true` |
| div | Use Row and Col as plain divs without layout styles | `boolean` | `false` |

### Events

| Event | Description |
| --- | --- |
| click | Native MouseEvent, emitted once per click |

### Slots

| Slot | Description |
| --- | --- |
| default | Layout content |

### Methods

| Method | Description |
| --- | --- |
<!-- same-source-api:end -->

Wrapping examples compare wrapped and ordinary `div` modes. Ordinary mode removes Row layout and child Col spacing. Gap examples distinguish horizontal/vertical spacing. Row uses Flex, not CSS Grid.

## Responsiveness and accessibility

Breakpoints use the browser viewport: xs is the base; sm ≥576, md ≥768, lg ≥992, xl ≥1200 and xxl ≥1600px. Configured values resolve downward from the largest matching breakpoint. SSR starts with xs and responds to the viewport after mounting. Grid collapsing and dynamic ordering are calculated after mounting. These layout containers add no keyboard shortcuts; callers supply content semantics and focusable elements. There are no public methods or dedicated theme tokens.

## Imports

Grid contains only Grid.Item. Row and Col are independent components with their own source, styles, navigation, documentation and demos. Grid.Row/Grid.Col, Row/Col re-exports from Grid and GridRowInstance/GridColInstance are removed. Import them from the library root or separate row/col entries. Installing Grid no longer registers Row/Col automatically.

---

Document: llms/en-US/components/scheduler.md

<!-- Source: src/scheduler/README.en-US.md; locale: en-US; page: /en/components/scheduler/ -->

# Scheduler

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Reading direction

Scheduler inherits `dir` from the page, a local container, or ConfigProvider. Use the documentation navigation switch to change LTR/RTL at runtime. Month/week/resource columns and horizontal time follow inline start; vertical time continues downwards. Switching direction preserves dates, event data, selection and the horizontal reading offset, and cancels active drag or resize gestures.

Hourly resource timelines support moving events and resizing both start and end, respecting `snapDuration`, readonly state, milestones and event `resizable`. Zoom preserves the date at the center of the visible time area. Resource labels stick to inline start; virtual rows and their heading scroll together.

Default overlap layouts use inline start. A custom `eventLayout` return value keeps the physical meaning of `left`; callers control that geometry. RTL does not reverse dates, time zones, dependencies or source resource order.

## Basic examples

### Basic usage

Preview configuration: `default-date="2026-09-09"`.

Example source: src/scheduler/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { SchedulerEvent } from '@cedar-design/ui'
const events = ref<SchedulerEvent[]>([
  { id: 'meeting', title: '项目同步', start: '2026-09-09T09:00:00', end: '2026-09-09T10:00:00' },
])
</script>
<template>
  <c-scheduler v-model="events" default-date="2026-09-09" />
</template>
```

## Views and layout

### Layout Groups

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-date` | Initial navigation date | Layout Groups, Without Resources, Resource Week |
| `default-mode` | Default uncontrolled view | Layout Groups, Timeline, Hidden Days |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Resource Week, Timeline, Now Indicator |
| `start-hour` | Time-grid start hour, 0–23 | Layout Groups, Now Indicator, Stacked Events |
| `end-hour` | Time-grid end hour; greater than start and at most 24 | Layout Groups, Now Indicator, Stacked Events |
| `modes` | Views available for switching | Without Resources, Hidden Days, Now Indicator |
<!-- demo-config-notes:end -->


Preview configuration: `:default-date="today"`, `default-mode="day"`, `:event-layout="custom ? layout : 'stack'"`, `:show-sidebar="false"`.

Example source: src/scheduler/__demos__/layout-groups.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >分组仅共享布局位置。业务关联保存在
      metadata，修改单块不会自动修改整组。</c-alert
    >
    <c-space>
      <c-checkbox v-model="grouped">连续日程组成布局组</c-checkbox>
      <c-checkbox v-model="custom">自定义横向留白</c-checkbox>
    </c-space>
    <c-scheduler
      v-model="displayEvents"
      :default-date="today"
      default-mode="day"
      :event-layout="custom ? layout : 'stack'"
      :show-sidebar="false"
      :start-hour="8"
      :end-hour="17"
    >
      <template #event="{ event }">
        <strong>{{ event.title }}</strong>
        <div v-if="event.metadata?.reference">
          关联：{{ event.metadata.reference }}
        </div>
      </template>
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import type { SchedulerEvent, SchedulerEventLayout } from "../core";
const today = new Date();
const grouped = ref(true);
const custom = ref(false);
const at = (hour: number) => {
  const date = new Date(today);
  date.setHours(hour, 0, 0, 0);
  return date;
};
const events = ref<SchedulerEvent[]>([
  {
    id: "a",
    title: "阶段一",
    start: at(9),
    end: at(11),
    metadata: { reference: "A" },
  },
  {
    id: "b",
    title: "阶段二",
    start: at(11),
    end: at(13),
    metadata: { reference: "A" },
  },
  { id: "c", title: "独立日程", start: at(10), end: at(12) },
  {
    id: "d",
    title: "间隔后的阶段",
    start: at(15),
    end: at(16),
    metadata: { reference: "A" },
  },
]);
// Only the application interprets metadata and chooses which blocks share layout.
const displayEvents = computed({
  get: () =>
    events.value.map((event) => ({
      ...event,
      layoutGroupId:
        grouped.value && typeof event.metadata?.reference === "string"
          ? event.metadata.reference
          : undefined,
    })),
  set: (value: SchedulerEvent[]) => {
    events.value = value;
  },
});
// Product-specific percentages stay in the demo. Fractions are relative to one date/resource column.
const layout: SchedulerEventLayout = ({ column, columns }) => {
  const left = (column * 0.9) / columns;
  return {
    left,
    width: Math.min(Math.max(0.45, 1 - 0.1 * columns), 0.9 - left),
  };
};
</script>
```

### Without Resources

Preview configuration: `:modes="['day', 'week', 'month', 'agenda']"`, `default-date="2026-09-09"`.

Example source: src/scheduler/__demos__/without-resources.vue

```vue
<template>
  <p>仅管理发布时间与工作计划，不传人员或设备列表。编辑器不显示资源字段。</p>
  <c-scheduler
    v-model="events"
    :modes="['day', 'week', 'month', 'agenda']"
    default-date="2026-09-09"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent } from "@cedar-design/ui";
const events = ref<SchedulerEvent[]>([
  {
    id: "release",
    title: "产品发布",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
    description: "检查发布清单",
  },
  {
    id: "campaign",
    title: "专题活动",
    start: "2026-09-10",
    end: "2026-09-13",
    allDay: true,
  },
  { id: "draft", title: "下期内容选题", description: "未排期，可拖入时间格" },
]);
</script>
```

### Resource Week

Preview configuration: `default-date="2026-09-09"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/resource-week.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    :resources="resources"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
</script>
```

### Timeline

Preview configuration: `default-date="2026-09-09"`, `default-mode="resource-timeline"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/timeline.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    default-mode="resource-timeline"
    :resources="resources"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
</script>
```

### Hidden Days

Preview configuration: `default-date="2026-09-18"`, `default-mode="month"`, `:modes="['week', 'month', 'agenda']"`, `:hidden-days="hidden"`.

Example source: src/scheduler/__demos__/hidden-days.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >隐藏日期只影响展示，原日程仍保留，并参与容量和冲突校验。跨周末任务会出现在周五及下周一；拖动到周一会按周一的实际日期保存。可切换周、月和议程检查同一份数据。</c-alert
    >
    <c-space wrap>
      <c-checkbox v-model="weekends">隐藏周末</c-checkbox>
      <c-checkbox v-model="wednesday">隐藏周三</c-checkbox>
      <c-tag>完整数据：{{ events.length }} 条</c-tag>
    </c-space>
    <c-scheduler
      key="hidden-days"
      v-model="events"
      default-date="2026-09-18"
      default-mode="month"
      :modes="['week', 'month', 'agenda']"
      :hidden-days="hidden"
      :first-day-of-week="0"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import type { SchedulerEvent } from "../core";
const weekends = ref(true);
const wednesday = ref(false);
const hidden = computed(() => [
  ...(weekends.value ? [0, 6] : []),
  ...(wednesday.value ? [3] : []),
]);
const events = ref<SchedulerEvent[]>([
  {
    id: "cross-weekend",
    title: "跨周末项目",
    start: "2026-09-18",
    end: "2026-09-22",
    allDay: true,
  },
  {
    id: "weekend",
    title: "周末值班",
    start: "2026-09-19T10:00:00",
    end: "2026-09-19T11:00:00",
  },
  {
    id: "wednesday",
    title: "周三评审",
    start: "2026-09-16T14:00:00",
    end: "2026-09-16T15:00:00",
  },
]);
</script>
```

### Now Indicator

Preview configuration: `v-model:date="date"`, `:show-now-indicator="enabled"`, `default-mode="resource-day"`, `:modes="['day', 'week', 'resource-day']"`.

Example source: src/scheduler/__demos__/now-indicator.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >红线标出当前本地时间，每 30
      秒刷新。可以切换日、周和资源日程；日和资源日程查看明天时红线消失。标线不影响新建和拖动。</c-alert
    >
    <c-space wrap>
      <c-checkbox v-model="enabled">显示现在时间线</c-checkbox>
      <c-button @click="date = new Date()">查看今天</c-button>
      <c-button @click="date = addSchedulerDays(new Date(), 1)"
        >查看明天</c-button
      >
    </c-space>
    <c-scheduler
      key="now-indicator"
      v-model:date="date"
      :show-now-indicator="enabled"
      default-mode="resource-day"
      :modes="['day', 'week', 'resource-day']"
      :start-hour="0"
      :end-hour="24"
      :resources="resources"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { addSchedulerDays } from "../core";
const date = ref(new Date());
const enabled = ref(true);
const resources = [
  { id: "a", label: "今日值班 A" },
  { id: "b", label: "今日值班 B" },
];
</script>
```

### Timeline Groups

Preview configuration: `v-model:scale="scale"`, `v-model:expanded-keys="expanded"`, `default-date="2026-09-09"`, `default-mode="resource-timeline"`.

Example source: src/scheduler/__demos__/timeline-groups.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >按部门折叠资源；切换小时刻度可查看定位日的精确排期。资源名称在横向滚动时保持可见。</c-alert
    >
    <c-scheduler
      v-model="events"
      v-model:scale="scale"
      v-model:expanded-keys="expanded"
      default-date="2026-09-09"
      default-mode="resource-timeline"
      :resources="resources"
      :resource-group-by="groupBy"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerResource, SchedulerScale } from "../core";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
const scale = ref<SchedulerScale>("hour");
const expanded = ref(["产品与设计", "研发"]);
const groupBy = (resource: SchedulerResource) =>
  resource.id === resources[0].id ? "产品与设计" : "研发";
</script>
```

### Stacked Events

- `readonly`: Displays the current value without allowing edits.

Example source: src/scheduler/__demos__/stacked-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >重叠卡片按数量等分起点并延伸到最右侧。本例最多直接显示 3
      张，更多日程通过“还有 N
      项”Popover查看。Tab聚焦前置，失焦恢复；单击或Enter打开详情。</c-alert
    >
    <c-space>
      <c-button @click="layout = layout === 'stack' ? 'columns' : 'stack'">{{
        layout === "stack" ? "切换并排布局" : "切换叠放布局"
      }}</c-button>
      <c-checkbox v-model="readonly">只读查看</c-checkbox>
    </c-space>
    <c-scheduler
      v-model="events"
      default-date="2026-09-22"
      default-mode="week"
      :event-layout="layout"
      :overlap-event-limit="3"
      :readonly="readonly"
      selectable
      :show-sidebar="false"
      :start-hour="8"
      :end-hour="16"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent } from "../core";
const layout = ref<"stack" | "columns">("stack");
const readonly = ref(false);
const events = ref<SchedulerEvent[]>([
  {
    id: "a",
    title: "站点巡检",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T12:00:00",
  },
  {
    id: "b",
    title: "设备维护",
    start: "2026-09-22T09:30:00",
    end: "2026-09-22T11:30:00",
  },
  {
    id: "c",
    title: "人员培训",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T12:30:00",
  },
  {
    id: "e",
    title: "安全检查",
    start: "2026-09-22T09:15:00",
    end: "2026-09-22T11:00:00",
  },
  {
    id: "f",
    title: "临时工单",
    start: "2026-09-22T09:45:00",
    end: "2026-09-22T12:00:00",
  },
  {
    id: "d",
    title: "独立任务",
    start: "2026-09-23T13:00:00",
    end: "2026-09-23T14:00:00",
  },
]);
</script>
```

## Resources and assignments

### Resources

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-date` | Initial navigation date | Resources, Resource Cross Groups, Resource Dimensions |
| `default-mode` | Default uncontrolled view | Resources, Resource Cross Groups, Resource Dimensions |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Resources, Resource Cross Groups, Resource Dimensions |
| `resource-dimensions` | Dimension definitions: `{ id, label }[]` | Resource Cross Groups, Resource Dimensions, Independent Assignments |
| `resource-filters` | Combined resource-dimension filters; supports v-model:resource-filters | Resource Cross Groups, Resource Dimensions, Virtual Resources |
| `show-assignment-details` | Edit resource occupancy and roles | Independent Assignments, Assignment Load |
<!-- demo-config-notes:end -->


Preview configuration: `default-date="2026-09-09"`, `default-mode="resource-day"`, `:resources="resources"`, `:start-hour="8"`.

Example source: src/scheduler/__demos__/resources.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    default-mode="resource-day"
    :resources="resources"
    :start-hour="8"
    :end-hour="18"
  />
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
</script>
```

### Resource Cross Groups

Preview configuration: `data-cross-groups-demo`, `v-model:resource-filters="filters"`, `:resource-group-dimensions="groupDimensions"`, `default-date="2026-09-22"`.

Example source: src/scheduler/__demos__/resource-cross-groups.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >按站展开人员，也可切换为按人展开站。联合验收在两个人员行显示，但数据只有一条；拖动会修改整条任务的时间和对应资源。点击空白行可创建同时关联站与人的任务。</c-alert
    >
    <c-space wrap>
      <c-button
        @click="
          filters = { station: ['station:north'], person: ['person:lin'] }
        "
        >北站 + 小林</c-button
      >
      <c-button
        @click="
          filters = {
            station: ['station:north', 'station:south'],
            person: ['person:chen'],
          }
        "
        >两站 + 小陈</c-button
      >
      <c-button @click="filters = {}">清空维度筛选</c-button>
      <c-button @click="groupDimensions = ['station', 'person']"
        >站 → 人</c-button
      >
      <c-button @click="groupDimensions = ['person', 'station']"
        >人 → 站</c-button
      >
      <c-tag>匹配 {{ matching.length }} / {{ events.length }} 条任务</c-tag>
    </c-space>
    <c-scheduler
      data-cross-groups-demo
      key="resource-cross-groups"
      v-model="events"
      v-model:resource-filters="filters"
      :resource-group-dimensions="groupDimensions"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :resource-dimensions="dimensions"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import { filterSchedulerEventsByResources } from "../core";
import type {
  SchedulerEvent,
  SchedulerResource,
  SchedulerResourceFilters,
} from "../core";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources: SchedulerResource[] = [
  { id: "station:north", label: "北站", dimensionId: "station", capacity: 2 },
  { id: "station:south", label: "南站", dimensionId: "station", capacity: 2 },
  { id: "person:lin", label: "小林", dimensionId: "person", capacity: 1 },
  { id: "person:chen", label: "小陈", dimensionId: "person", capacity: 1 },
];
const filters = ref<SchedulerResourceFilters>({});
const groupDimensions = ref(["station", "person"]);
const events = ref<SchedulerEvent[]>([
  {
    id: "north-lin",
    title: "北站巡检",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["station:north", "person:lin"],
  },
  {
    id: "north-chen",
    title: "北站检修",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T11:00:00",
    resourceIds: ["station:north", "person:chen"],
  },
  {
    id: "south-lin",
    title: "南站巡检",
    start: "2026-09-22T11:00:00",
    end: "2026-09-22T12:00:00",
    resourceIds: ["station:south", "person:lin"],
  },
  {
    id: "south-chen",
    title: "南站检修",
    start: "2026-09-22T13:00:00",
    end: "2026-09-22T14:00:00",
    resourceIds: ["station:south", "person:chen"],
  },
  {
    id: "joint",
    title: "北站联合验收",
    start: "2026-09-22T14:00:00",
    end: "2026-09-22T15:00:00",
    resourceIds: ["station:north", "person:lin", "person:chen"],
  },
]);
const matching = computed(() =>
  filterSchedulerEventsByResources(events.value, resources, filters.value),
);
</script>
```

### Resource Dimensions

Preview configuration: `data-dimensions-demo`, `v-model:resource-filters="filters"`, `v-model:resource-dimension="axis"`, `default-date="2026-09-22"`.

Example source: src/scheduler/__demos__/resource-dimensions.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >一条任务同时关联站和人。左侧同一维度可多选，站与人之间组合筛选；上方“展示维度”切换资源行。打开任务详情可分别修改站和人，其他维度的关联会保留。</c-alert
    >
    <c-space wrap>
      <c-button
        @click="
          filters = { station: ['station:north'], person: ['person:lin'] }
        "
        >北站 + 小林</c-button
      >
      <c-button
        @click="
          filters = {
            station: ['station:north', 'station:south'],
            person: ['person:chen'],
          }
        "
        >两站 + 小陈</c-button
      >
      <c-button @click="filters = {}">清空维度筛选</c-button>
      <c-button @click="axis = 'station'">按站展示</c-button>
      <c-button @click="axis = 'person'">按人展示</c-button>
      <c-tag>匹配 {{ matching.length }} / {{ events.length }} 条任务</c-tag>
    </c-space>
    <c-scheduler
      data-dimensions-demo
      key="resource-dimensions"
      v-model="events"
      v-model:resource-filters="filters"
      v-model:resource-dimension="axis"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :resource-dimensions="dimensions"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import { filterSchedulerEventsByResources } from "../core";
import type {
  SchedulerEvent,
  SchedulerResource,
  SchedulerResourceFilters,
} from "../core";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources: SchedulerResource[] = [
  { id: "station:north", label: "北站", dimensionId: "station", capacity: 2 },
  { id: "station:south", label: "南站", dimensionId: "station", capacity: 2 },
  { id: "person:lin", label: "小林", dimensionId: "person", capacity: 1 },
  { id: "person:chen", label: "小陈", dimensionId: "person", capacity: 1 },
];
const filters = ref<SchedulerResourceFilters>({
  station: ["station:north"],
  person: ["person:lin"],
});
const axis = ref("station");
const events = ref<SchedulerEvent[]>([
  {
    id: "north-lin",
    title: "北站巡检",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["station:north", "person:lin"],
  },
  {
    id: "north-chen",
    title: "北站检修",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T11:00:00",
    resourceIds: ["station:north", "person:chen"],
  },
  {
    id: "south-lin",
    title: "南站巡检",
    start: "2026-09-22T11:00:00",
    end: "2026-09-22T12:00:00",
    resourceIds: ["station:south", "person:lin"],
  },
  {
    id: "south-chen",
    title: "南站检修",
    start: "2026-09-22T13:00:00",
    end: "2026-09-22T14:00:00",
    resourceIds: ["station:south", "person:chen"],
  },
  {
    id: "joint",
    title: "北站联合验收",
    start: "2026-09-22T14:00:00",
    end: "2026-09-22T15:00:00",
    resourceIds: ["station:north", "person:lin", "person:chen"],
  },
]);
const matching = computed(() =>
  filterSchedulerEventsByResources(events.value, resources, filters.value),
);
</script>
```

### Independent Assignments

Preview configuration: `:resources="resources"`, `:resource-dimensions="dimensions"`, `:resource-group-dimensions="['station', 'person']"`, `default-date="2026-09-22"`.

Example source: src/scheduler/__demos__/independent-assignments.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >同一业务任务有两个独立分配：北站小林 09:00–10:00、南站小陈
      13:00–15:00。它们共用
      metadata.taskId，各自拥有时间与占用量；修改一个分配不会移动另一个。</c-alert
    >
    <c-scheduler
      v-model="events"
      :resources="resources"
      :resource-dimensions="dimensions"
      :resource-group-dimensions="['station', 'person']"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      show-assignment-details
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { createSchedulerTaskEvents } from "./task-assignments";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources = [
  { id: "north", label: "北站", dimensionId: "station" },
  { id: "south", label: "南站", dimensionId: "station" },
  { id: "lin", label: "小林", dimensionId: "person", capacity: 1 },
  { id: "chen", label: "小陈", dimensionId: "person", capacity: 1 },
];
const events = ref(
  createSchedulerTaskEvents({ id: "inspection", title: "联合巡检" }, [
    {
      id: "north-lin",
      start: "2026-09-22T09:00:00",
      end: "2026-09-22T10:00:00",
      resourceIds: ["north", "lin"],
      resourceDetails: { lin: { units: 1, role: "负责" } },
    },
    {
      id: "south-chen",
      start: "2026-09-22T13:00:00",
      end: "2026-09-22T15:00:00",
      resourceIds: ["south", "chen"],
      resourceDetails: { chen: { units: 0.5, role: "负责" } },
    },
  ]),
);
</script>
```

### Assignment Load

Preview configuration: `default-date="2026-09-22"`, `default-mode="resource-timeline"`, `default-scale="hour"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/assignment-load.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >每条日程可配置资源占用量和角色。两条各占 0.5 的日程恰好占满容量
      1；尝试新增一条可验证阻止或提醒策略。详情中可直接修改分配信息，资源表头显示本日峰值负载。</c-alert
    >
    <c-space
      ><c-button @click="policy = {}">超载时阻止</c-button
      ><c-button @click="policy = { capacity: 'warn' }">超载时提醒</c-button
      ><c-button @click="add">新增 0.5 占用</c-button></c-space
    >
    <c-scheduler
      ref="scheduler"
      v-model="events"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :rule-policy="policy"
      show-assignment-details
      show-resource-load
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerInstance } from "../index";
import type { SchedulerEvent, SchedulerRulePolicy } from "../core";
const scheduler = ref<SchedulerInstance>();
const resources = [{ id: "device", label: "实验设备", capacity: 1 }];
const policy = ref<SchedulerRulePolicy>({});
let sequence = 2;
const events = ref<SchedulerEvent[]>(
  [0, 1].map((i) => ({
    id: `load${i}`,
    title: `任务 ${i + 1}`,
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["device"],
    resourceDetails: { device: { units: 0.5, role: i ? "协作" : "负责" } },
  })),
);
function add() {
  const id = sequence++;
  return scheduler.value?.change({
    type: "create",
    event: { ...events.value[0], id: `load${id}`, title: `任务 ${id + 1}` },
  });
}
</script>
```

### Virtual Resources

Preview configuration: `data-virtual-resources-demo`, `v-model:resource-filters="filters"`, `:resources="resources"`, `:resource-dimensions="dimensions"`.

Example source: src/scheduler/__demos__/virtual-resources.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >100 个站 × 20 位人员，共 2000
      个组合行。滚动时只挂载附近的行；点击空白格新建，或在当前可见行之间拖动任务。编辑后保留滚动位置；拖到边缘可自动滚动到其他组合行。</c-alert
    >
    <c-space wrap>
      <c-button @click="filters = {}">全部 2000 行</c-button>
      <c-button @click="filters = { station: ['s0', 's1', 's2'] }"
        >前 3 个站</c-button
      >
      <c-button @click="filters = { person: ['p0'] }">仅人员 001</c-button>
      <c-tag>{{ events.length }} 条日程</c-tag>
    </c-space>
    <c-scheduler
      key="virtual-resources"
      data-virtual-resources-demo
      v-model="events"
      v-model:resource-filters="filters"
      :resources="resources"
      :resource-dimensions="dimensions"
      :resource-group-dimensions="['station', 'person']"
      :virtual-list-props="{ height: 480, buffer: 10, estimatedSize: 80 }"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type {
  SchedulerResource,
  SchedulerEvent,
  SchedulerResourceFilters,
} from "../core";
const dimensions = [
  { id: "station", label: "站" },
  { id: "person", label: "人" },
];
const resources: SchedulerResource[] = [
  ...Array.from({ length: 100 }, (_, i) => ({
    id: `s${i}`,
    label: `站点 ${String(i + 1).padStart(3, "0")}`,
    dimensionId: "station",
  })),
  ...Array.from({ length: 20 }, (_, i) => ({
    id: `p${i}`,
    label: `人员 ${String(i + 1).padStart(3, "0")}`,
    dimensionId: "person",
  })),
];
const filters = ref<SchedulerResourceFilters>({});
const events = ref<SchedulerEvent[]>(
  Array.from({ length: 100 }, (_, i) => ({
    id: `task${i}`,
    title: `巡检 ${String(i + 1).padStart(3, "0")}`,
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: [`s${i}`, `p${i % 20}`],
  })),
);
</script>
```

## Working hours and capacity

### Recurring and date-specific working hours

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-date` | Initial navigation date | Recurring and date-specific working hours, Maintenance, Resource Capacity |
| `default-mode` | Default uncontrolled view | Recurring and date-specific working hours, Maintenance, Resource Capacity |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Recurring and date-specific working hours, Maintenance, Resource Capacity |
| `resource-label` | Resource field name, such as equipment or meeting room | Recurring and date-specific working hours, Maintenance |
| `allow-overlap` | Allow overlapping times for the same resource | Recurring and date-specific working hours |
<!-- demo-config-notes:end -->


Compare recurring hours with date-specific overrides. Attempt creation or editing inside and outside available periods to inspect full-duration validation.

Example source: src/scheduler/__demos__/working-hours-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import type { SchedulerEvent } from "../core"
import type { SchedulerWorkingHours } from "../core"
import type { SchedulerDateWorkingHours } from "../core"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const rooms = [
  { id: "room-a", label: "会议室 A" },
  { id: "room-b", label: "会议室 B" },
];

const hours: SchedulerWorkingHours[] = [
  { daysOfWeek: [1, 2, 3, 4, 5], startMinute: 540, endMinute: 720 },
  { daysOfWeek: [1, 2, 3, 4, 5], startMinute: 780, endMinute: 1080 },
];

const events = ref<SchedulerEvent[]>([
  {
    id: "meeting",
    title: "产品评审",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
    resourceIds: ["room-a"],
  },
]);
return { rooms, hours, events }
})())

const scene2 = demoProxyRefs((() => {

const enabled = ref(true);

const resources = [
  { id: "lin", label: "小林" },
  { id: "chen", label: "小陈" },
  { id: "device", label: "设备" },
];

const hours = [
  { daysOfWeek: [1, 2, 3, 4, 5], startMinute: 540, endMinute: 1080 },
];

const overrides: SchedulerDateWorkingHours[] = [
  { date: "2026-09-12", intervals: [{ startMinute: 540, endMinute: 720 }] },
  {
    date: "2026-09-12",
    resourceIds: ["lin"],
    intervals: [
      { startMinute: 600, endMinute: 720 },
      { startMinute: 780, endMinute: 900 },
    ],
  },
  { date: "2026-09-12", resourceIds: ["device"], intervals: [] },
  { date: "2026-09-30", intervals: [{ startMinute: 540, endMinute: 720 }] },
];

const events = ref<SchedulerEvent[]>([
  {
    id: "makeup",
    title: "补班协作任务",
    start: "2026-09-12T10:00:00",
    end: "2026-09-12T11:00:00",
    resourceIds: ["lin", "chen"],
  },
]);
return { enabled, resources, hours, overrides, events }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="working-hours">
    <h4><span lang="zh-CN">工作时间与维护时段</span><span lang="en-US">working hours</span></h4>
    <c-space direction="column" block>
        <c-alert
          >会议室工作日 09:00–12:00、13:00–18:00
          可预约。灰色时段包含午休和非工作时间；新建、拖动和编辑均会校验完整时长。</c-alert
        >
        <c-scheduler
          v-model="scene1.events"
          default-date="2026-09-09"
          default-mode="resource-day"
          resource-label="会议室"
          :resources="scene1.rooms"
          :working-hours="scene1.hours"
          :allow-overlap="false"
        />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="date-working-hours">
    <h4><span lang="zh-CN">指定日期工作时间</span><span lang="en-US">date working hours</span></h4>
    <c-space direction="column" block>
        <c-alert
          >模拟周六补班：公共时段 09:00–12:00；小林改为
          10:00–12:00、13:00–15:00；设备全天关闭。关闭开关后恢复周一至周五规则。已有任务保留，再次保存时重新校验。</c-alert
        >
        <c-checkbox v-model="scene2.enabled">启用指定日期时段</c-checkbox>
        <c-scheduler
          key="date-hours"
          v-model="scene2.events"
          default-date="2026-09-12"
          default-mode="resource-day"
          :resources="scene2.resources"
          :working-hours="scene2.hours"
          :date-working-hours="scene2.enabled ? scene2.overrides : []"
        />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Maintenance

Preview configuration: `default-date="2026-09-09"`, `default-mode="resource-timeline"`, `default-scale="hour"`, `resource-label="设备"`.

Example source: src/scheduler/__demos__/maintenance.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >设备 A 在 10:00–12:00 维护，设备 B
      不受影响。可关闭维护规则，对比可用时段及拖动保存结果。</c-alert
    >
    <c-checkbox v-model="maintenance">启用设备 A 维护时段</c-checkbox>
    <c-scheduler
      v-model="events"
      default-date="2026-09-09"
      default-mode="resource-timeline"
      default-scale="hour"
      resource-label="设备"
      :resources="equipment"
      :disabled-ranges="maintenance ? ranges : []"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerDisabledRange } from "../core";
const maintenance = ref(true);
const equipment = [
  { id: "a", label: "设备 A" },
  { id: "b", label: "设备 B" },
];
const ranges: SchedulerDisabledRange[] = [
  {
    id: "maintenance-a",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T12:00:00",
    resourceIds: ["a"],
    label: "设备 A 定期维护",
  },
];
const events = ref<SchedulerEvent[]>([
  {
    id: "inspection",
    title: "样品检测",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T10:00:00",
    resourceIds: ["a"],
  },
]);
</script>
```

### Resource Capacity

Preview configuration: `:status="span.exceeded ? 'danger' : 'success'"`, `default-date="2026-09-15"`, `default-mode="resource-timeline"`, `default-scale="hour"`.

Example source: src/scheduler/__demos__/resource-capacity.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >检测设备默认可并行处理 2 个任务。09:00–11:00 与 10:00–12:00 的两单已占满
      10:00–11:00；尝试追加第三单，或提高容量后重试。降低容量保留已有日程，并在下方标出超额时段。</c-alert
    >
    <c-space wrap>
      <c-button @click="capacity = 1">容量设为 1</c-button>
      <c-button @click="capacity = 2">容量设为 2</c-button>
      <c-button @click="capacity = 3">容量设为 3</c-button>
      <c-button status="primary" @click="addThird">尝试追加第三单</c-button>
      <c-button @click="reset">重置容量示例</c-button>
      <c-tag>当前容量：{{ capacity }}</c-tag>
      <c-tag v-if="result">{{ result }}</c-tag>
    </c-space>
    <c-space direction="column" block>
      <c-tag
        v-for="span in load"
        :key="+span.start"
        :status="span.exceeded ? 'danger' : 'success'"
      >
        {{ format(span.start) }}–{{ format(span.end) }}：{{ span.load }}/{{
          span.capacity
        }}
        {{ span.exceeded ? "超出容量" : "容量内" }}
      </c-tag>
      <c-tag v-if="!load.length">当前可见范围没有占用</c-tag>
    </c-space>
    <c-scheduler
      key="resource-capacity"
      ref="scheduler"
      v-model="events"
      default-date="2026-09-15"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      history
      @range-change="range = $event"
    >
      <template #resource-header="{ resource }">
        <c-space
          ><span>{{ resource?.label }}</span
          ><c-tag>容量 {{ resource?.capacity }}</c-tag></c-space
        >
      </template>
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import type { SchedulerInstance } from "../index";
import type { SchedulerEvent } from "../core";
import {
  getSchedulerResourceLoad,
  getSchedulerRange,
  schedulerDateKey,
} from "../core";
const scheduler = ref<SchedulerInstance>();
const capacity = ref(2);
const resources = computed(() => [
  { id: "lab", label: "检测设备", capacity: capacity.value },
]);
const initial: SchedulerEvent[] = [
  {
    id: "sample-a",
    title: "样品甲",
    start: "2026-09-15T09:00:00",
    end: "2026-09-15T11:00:00",
    resourceIds: ["lab"],
  },
  {
    id: "sample-b",
    title: "样品乙",
    start: "2026-09-15T10:00:00",
    end: "2026-09-15T12:00:00",
    resourceIds: ["lab"],
  },
];
const events = ref<SchedulerEvent[]>([...initial]);
const range = ref(getSchedulerRange("2026-09-15", "day"));
const load = computed(() =>
  getSchedulerResourceLoad(events.value, resources.value[0], range.value),
);
const result = ref("");
const format = (date: Date) =>
  `${schedulerDateKey(date)} ${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`;
async function addThird() {
  if (events.value.some((event) => event.id === "sample-c")) {
    result.value = "第三单已存在，可撤销或重置后重试";
    return;
  }
  const saved = await scheduler.value?.change({
    type: "create",
    event: {
      id: "sample-c",
      title: "样品丙",
      start: "2026-09-15T10:30:00",
      end: "2026-09-15T11:00:00",
      resourceIds: ["lab"],
    },
  });
  result.value = saved ? "第三单已保存" : "第三单未保存：超出容量";
}
function reset() {
  events.value = [...initial];
  capacity.value = 2;
  result.value = "";
  scheduler.value?.goToDate(new Date(2026, 8, 15));
}
</script>
```

## Recurrence and calendars

### Recurring Events

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-mode` | Default uncontrolled view | Recurring Events, Calendar Recurrence, Business Calendar |
| `default-date` | Initial navigation date | Recurring Events, Business Calendar, Recurrence Following |
| `model-value` | Schedule data; supports v-model and becomes controlled when provided | Calendar Recurrence, Recurrence Following, Zoned Recurrence |
| `readonly` | Viewing/navigation allowed, editing blocked | Calendar Recurrence, Recurrence Following, Zoned Recurrence |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Recurring Events |
| `date` | Navigation date; supports v-model:date | Calendar Recurrence |
<!-- demo-config-notes:end -->


Preview configuration: `:options="frequencies"`, `aria-label="重复频率"`, `:min="1"`, `:max="12"`.

Example source: src/scheduler/__demos__/recurring-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >重复会议按可见范围展开。编辑、拖动或删除卡片只影响这一次；新建日程是独立安排。修改上方规则会重建系列并清除本例中的例外。</c-alert
    >
    <c-space wrap>
      <c-select
        v-model="frequency"
        :options="frequencies"
        aria-label="重复频率"
      />
      <c-input-number
        v-model="interval"
        :min="1"
        :max="12"
        aria-label="重复间隔"
      />
      <c-tag>{{
        frequency === "daily" ? "天一次" : "周一次（周一、三、五）"
      }}</c-tag>
      <c-input-number
        v-model="count"
        :min="1"
        :max="60"
        aria-label="重复次数"
      />
      <c-tag>次后结束</c-tag>
      <c-button :disabled="!exceptions.length" @click="exceptions = []"
        >恢复全部例外</c-button
      >
    </c-space>
    <c-tag
      >{{ exceptions.length }} 条本次例外 ·
      {{ standalone.length }} 条独立安排</c-tag
    >
    <c-scheduler
      v-model="events"
      default-date="2026-09-09"
      default-mode="week"
      :resources="resources"
      :before-transaction="validateChange"
      @range-change="range = $event"
    >
      <template #event="{ event }">
        {{ event.title }}
        <c-tag v-if="occurrenceIds.has(event.id)" size="small"
          >重复 · 仅本次</c-tag
        >
      </template>
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref, watch } from "vue";
import {
  SchedulerError,
  applySchedulerChange,
  diffSchedulerEvents,
  expandSchedulerRecurrences,
  getSchedulerRange,
  setSchedulerRecurrenceException,
} from "../core";
import type {
  SchedulerEvent,
  SchedulerRecurrenceException,
  SchedulerRecurrenceRule,
  SchedulerRecurringEvent,
} from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const validateChange: SchedulerBeforeTransaction = ({ changes }) => {
  if (
    changes.some(
      (change) =>
        occurrenceIds.value.has(change.event.id) &&
        change.type !== "remove" &&
        change.event.start == null,
    )
  ) {
    throw new SchedulerError(
      "invalid-event",
      "重复实例必须保留排期；取消本次请使用删除",
    );
  }
};
const frequencies = [
  { label: "每天", value: "daily" },
  { label: "每周", value: "weekly" },
];
const frequency = ref<SchedulerRecurrenceRule["frequency"]>("weekly");
const interval = ref(1);
const count = ref(12);
const range = ref(getSchedulerRange("2026-09-09", "week"));
const resources = [
  { id: "design", label: "林夏 · 设计" },
  { id: "dev", label: "陈舟 · 前端" },
];
const exceptions = ref<SchedulerRecurrenceException[]>([]);
const standalone = ref<SchedulerEvent[]>([]);
const series = computed<SchedulerRecurringEvent[]>(() => [
  {
    event: {
      id: "weekly-review",
      title: "项目同步会",
      start: "2026-09-07T09:00:00",
      end: "2026-09-07T10:00:00",
      resourceIds: ["design", "dev"],
    },
    rule: {
      frequency: frequency.value,
      interval: interval.value || 1,
      count: count.value || 1,
      daysOfWeek: frequency.value === "weekly" ? [1, 3, 5] : undefined,
    },
  },
]);
watch([frequency, interval, count], () => {
  exceptions.value = [];
});
const occurrences = computed(() =>
  expandSchedulerRecurrences(series.value, range.value, {
    exceptions: exceptions.value,
  }),
);
const occurrenceIds = computed(
  () => new Set(occurrences.value.map((event) => event.id)),
);
const events = computed<SchedulerEvent[]>({
  get: () => [...occurrences.value, ...standalone.value],
  set: (next) => {
    const previous = [...occurrences.value, ...standalone.value];
    const originals = new Map(
      occurrences.value.map((event) => [event.id, event]),
    );
    let nextExceptions = exceptions.value;
    let nextStandalone = standalone.value;
    for (const change of diffSchedulerEvents(previous, next)) {
      const original = originals.get(change.event.id);
      if (original)
        nextExceptions = setSchedulerRecurrenceException(
          nextExceptions,
          original,
          change.type === "remove" ? undefined : change.event,
        );
      else nextStandalone = applySchedulerChange(nextStandalone, change);
    }
    // A real backend saves these series/exception records atomically, not expanded instances.
    exceptions.value = nextExceptions;
    standalone.value = nextStandalone;
  },
});
</script>
```

### Calendar Recurrence

- `readonly`: Displays the current value without allowing edits.

Example source: src/scheduler/__demos__/calendar-recurrence.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >按月、按年安排任务。无效日期可选择跳过或落到月底；“最后一个工作日”仅按周一至周五计算，不包含节假日调休。</c-alert
    >
    <c-space direction="column" align="stretch" wrap>
      <c-form-item layout="vertical" size="sm" label="月年重复规则">
        <c-radio-group
          v-model="preset"
          aria-label="月年重复规则"
          :options="presets"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-input-number
        v-model="interval"
        :min="1"
        :max="12"
        aria-label="月年重复间隔"
      />
      <c-tag>{{ preset === "leap" ? "年一次" : "个月一次" }}</c-tag>
      <c-input-number
        v-model="count"
        :min="1"
        :max="10"
        aria-label="月年重复次数"
      />
      <c-tag>次后结束</c-tag>
      <c-checkbox
        v-if="preset === 'day31' || preset === 'leap'"
        v-model="lastDay"
        >缺少该日期时落到月底</c-checkbox
      >
    </c-space>
    <c-tag>未来 40 年内的前 {{ preview.length }} 次安排（点日期定位）</c-tag>
    <c-space wrap>
      <c-button
        v-for="item in preview"
        :key="item.id"
        @click="date = schedulerDate(item.start!)"
        >{{ schedulerDateKey(item.start!) }}</c-button
      >
    </c-space>
    <c-scheduler
      key="calendar-recurrence-preview"
      v-model:date="date"
      :model-value="events"
      default-mode="month"
      readonly
      @range-change="range = $event"
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref, watch } from "vue";
import {
  expandSchedulerRecurrences,
  getSchedulerRange,
  schedulerDate,
  schedulerDateKey,
} from "../core";
import type { SchedulerDate, SchedulerRecurringEvent } from "../core";
const preset = ref("day31");
const interval = ref(1);
const count = ref(6);
const lastDay = ref(false);
const presets = [
  { label: "每月 31 日", value: "day31" },
  { label: "每月最后一个工作日", value: "weekday" },
  { label: "每月第二个星期一", value: "monday" },
  { label: "每年 2 月 29 日", value: "leap" },
];
const date = ref<SchedulerDate>("2026-01-31");
const range = ref(getSchedulerRange(date.value, "month"));
watch(preset, () => {
  date.value = preset.value === "leap" ? "2024-02-29" : "2026-01-01";
});
const series = computed<SchedulerRecurringEvent[]>(() => {
  const start =
    preset.value === "leap"
      ? "2024-02-29"
      : preset.value === "day31"
        ? "2026-01-31"
        : "2026-01-01";
  return [
    {
      event: {
        id: "calendar-plan",
        title: presets.find((item) => item.value === preset.value)!.label,
        start: `${start}T09:00:00`,
        end: `${start}T10:00:00`,
      },
      rule: {
        frequency: preset.value === "leap" ? "yearly" : "monthly",
        interval: interval.value || 1,
        count: count.value || 1,
        ...(preset.value === "weekday"
          ? { weekOfMonth: -1, daysOfWeek: [1, 2, 3, 4, 5] }
          : preset.value === "monday"
            ? { weekOfMonth: 2, daysOfWeek: [1] }
            : {
                overflow: lastDay.value
                  ? ("last-day" as const)
                  : ("skip" as const),
              }),
      },
    },
  ];
});
const events = computed(() =>
  expandSchedulerRecurrences(series.value, range.value),
);
const preview = computed(() => {
  const start = schedulerDate(series.value[0].event.start!);
  const end = new Date(start);
  end.setFullYear(end.getFullYear() + 40);
  return expandSchedulerRecurrences(series.value, { start, end }).slice(0, 10);
});
</script>
```

### Business Calendar

Preview configuration: `default-date="2026-02-26"`, `default-mode="week"`, `:working-hours="hours"`, `:disabled-ranges="blocked"`.

Example source: src/scheduler/__demos__/business-calendar.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >以下日期均为模拟企业日历，不是官方放假通知。示例包含模拟春节休假、周末补班和月末企业休假；同一配置用于月末工作日计算和预约校验。</c-alert
    >
    <c-checkbox v-model="enabled">启用模拟休假与补班</c-checkbox>
    <c-space wrap
      ><c-tag v-for="item in settlements" :key="item.id"
        >结算日：{{ schedulerDateKey(item.start!) }}</c-tag
      ></c-space
    >
    <c-tag
      >2 月 27 日企业休假、28
      日周六补班。可尝试新增或移动任务，对比开关前后的保存结果。</c-tag
    >
    <c-scheduler
      key="business-calendar-bookings"
      v-model="bookings"
      default-date="2026-02-26"
      default-mode="week"
      :working-hours="hours"
      :disabled-ranges="blocked"
      :before-transaction="validateCalendar"
      @range-change="range = $event"
    />
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref } from "vue";
import {
  expandSchedulerRecurrences,
  getSchedulerAvailabilityIssues,
  getSchedulerRange,
  schedulerDate,
  schedulerDateKey,
  SchedulerError,
} from "../core";
import { getSchedulerCalendarDisabledRanges } from "../core/business-calendar";
import type { SchedulerBusinessCalendar, SchedulerEvent } from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const enabled = ref(true);
const range = ref(getSchedulerRange("2026-02-26", "week"));
const overrides: NonNullable<SchedulerBusinessCalendar["overrides"]> = [
  ...[16, 17, 18, 19, 20].map((day) => ({
    date: `2026-02-${day}`,
    working: false,
    label: "模拟春节休假",
  })),
  { date: "2026-02-14", working: true, label: "模拟补班" },
  { date: "2026-02-27", working: false, label: "企业休假" },
  { date: "2026-02-28", working: true, label: "模拟补班" },
];
const calendar = computed<SchedulerBusinessCalendar>(() => ({
  overrides: enabled.value ? overrides : [],
}));
// Calendar decides which dates work; hours separately decide when those dates work.
const hours = [
  { daysOfWeek: [0, 1, 2, 3, 4, 5, 6], startMinute: 540, endMinute: 1080 },
];
const blocked = computed(() =>
  getSchedulerCalendarDisabledRanges(calendar.value, range.value),
);
const bookings = ref<SchedulerEvent[]>([
  {
    id: "regular-job",
    title: "常规工作日任务",
    start: "2026-02-26T10:00:00",
    end: "2026-02-26T11:00:00",
  },
]);
const settlements = computed(() =>
  expandSchedulerRecurrences(
    [
      {
        event: {
          id: "settlement",
          title: "月末结算",
          start: "2026-02-01T09:00:00",
          end: "2026-02-01T10:00:00",
        },
        rule: {
          frequency: "monthly",
          weekOfMonth: -1,
          businessCalendar: calendar.value,
          count: 3,
        },
      },
    ],
    { start: new Date(2026, 1, 1), end: new Date(2026, 4, 1) },
  ),
);
const validateCalendar: SchedulerBeforeTransaction = ({ changes }) => {
  for (const change of changes) {
    if (
      change.type === "remove" ||
      change.event.start == null ||
      change.event.end == null
    )
      continue;
    // Editor changes can extend outside the visible window: validate the full proposal.
    const disabledRanges = getSchedulerCalendarDisabledRanges(calendar.value, {
      start: schedulerDate(change.event.start),
      end: schedulerDate(change.event.end),
    });
    const issues = getSchedulerAvailabilityIssues(change.event, {
      disabledRanges,
    });
    if (issues.length)
      throw new SchedulerError("unavailable", "日程包含非工作日", issues);
  }
};
</script>
```

### Recurrence Following

- `readonly`: Displays the current value without allowing edits.

Example source: src/scheduler/__demos__/recurrence-following.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >点击会议选择“仅本次”或“本次及以后”。周五预设了一条“客户参会”例外：默认保护它，明确选择清除后才允许拆分。修改日期时需保留原规则的星期。</c-alert
    >
    <c-space wrap>
      <c-button @click="reset">重置示例</c-button>
      <c-checkbox v-model="reject">模拟保存失败</c-checkbox>
      <c-tag
        >{{ state.series.length }} 个系列 ·
        {{ state.exceptions.length }} 条例外</c-tag
      >
    </c-space>
    <c-space wrap>
      <c-tag v-for="item in state.series" :key="item.event.id"
        >{{ item.event.title }} · {{ item.rule.count ?? "不限" }} 次</c-tag
      >
    </c-space>
    <c-tag>{{ status }}</c-tag>
    <c-scheduler
      key="recurrence-following-calendar"
      :model-value="events"
      default-date="2026-09-09"
      default-mode="week"
      readonly
      :editable="false"
      @range-change="range = $event"
      @event-click="openEditor"
    />
    <c-dialog v-model:open="open" title="调整重复安排" :footer="false">
      <c-form
        v-if="draft"
        :model="draft"
        layout="vertical"
        @submit="save(false)"
      >
        <c-form-item label="修改范围">
          <c-select v-model="scope" :options="scopes" aria-label="修改范围" />
        </c-form-item>
        <c-form-item v-if="scope === 'following'" label="后续例外">
          <c-select
            v-model="policy"
            :options="policies"
            aria-label="后续例外处理"
          />
        </c-form-item>
        <c-form-item label="会议标题"
          ><c-input v-model="draft.title" aria-label="会议标题"
        /></c-form-item>
        <c-form-item label="开始时间"
          ><c-date
            v-model="draft.start"
            show-time
            value-format="Date"
            aria-label="会议开始"
        /></c-form-item>
        <c-form-item label="结束时间"
          ><c-date
            v-model="draft.end"
            show-time
            value-format="Date"
            aria-label="会议结束"
        /></c-form-item>
        <c-alert v-if="error" status="danger">{{ error }}</c-alert>
        <c-space wrap>
          <c-button status="primary" @click="save(false)">保存修改</c-button>
          <c-button @click="save(true)">取消所选安排</c-button>
          <c-button @click="open = false">返回</c-button>
        </c-space>
      </c-form>
    </c-dialog>
  </c-space>
</template>
<script setup lang="ts">
import { computed, ref, shallowRef } from "vue";
import {
  cloneSchedulerEvent,
  expandSchedulerRecurrences,
  getSchedulerRange,
  schedulerDate,
  setSchedulerRecurrenceException,
  splitSchedulerRecurrence,
} from "../core";
import type {
  SchedulerEvent,
  SchedulerOccurrence,
  SchedulerRecurringEvent,
  SchedulerRecurrenceException,
} from "../core";
const range = ref(getSchedulerRange("2026-09-09", "week"));
function initialState(): {
  series: SchedulerRecurringEvent[];
  exceptions: SchedulerRecurrenceException[];
} {
  const series: SchedulerRecurringEvent[] = [
    {
      event: {
        id: "team-sync",
        title: "团队同步会",
        start: "2026-09-07T09:00:00",
        end: "2026-09-07T10:00:00",
      },
      rule: { frequency: "weekly", daysOfWeek: [1, 3, 5], count: 9 },
    },
  ];
  const friday = expandSchedulerRecurrences(
    series,
    getSchedulerRange("2026-09-09", "week"),
  )[2];
  return {
    series,
    exceptions: setSchedulerRecurrenceException([], friday, {
      ...friday,
      title: "客户参会",
    }),
  };
}
const state = shallowRef(initialState());
const events = computed(() =>
  expandSchedulerRecurrences(state.value.series, range.value, {
    exceptions: state.value.exceptions,
  }),
);
const open = ref(false);
const reject = ref(false);
const scope = ref<"single" | "following">("single");
const policy = ref<"reject" | "discard">("reject");
const scopes = [
  { label: "仅本次", value: "single" },
  { label: "本次及以后", value: "following" },
];
const policies = [
  { label: "保护已有例外", value: "reject" },
  { label: "清除后续例外", value: "discard" },
];
const selected = shallowRef<SchedulerOccurrence>();
const draft = ref<{ title: string; start: Date; end: Date }>();
const error = ref("");
const status = ref("点击日程调整安排");
let baseline = state.value;
let nextId = 0;
function openEditor(event: SchedulerEvent) {
  const occurrence = events.value.find((item) => item.id === event.id);
  if (!occurrence) return;
  selected.value = { ...occurrence };
  draft.value = {
    title: occurrence.title,
    start: schedulerDate(occurrence.start!),
    end: schedulerDate(occurrence.end!),
  };
  scope.value = "single";
  policy.value = "reject";
  error.value = "";
  baseline = state.value;
  open.value = true;
}
function save(remove: boolean) {
  if (!selected.value || !draft.value) return;
  error.value = "";
  try {
    if (state.value !== baseline)
      throw new Error("安排已变化，请关闭后重新打开。");
    const replacement = {
      ...cloneSchedulerEvent(selected.value),
      ...draft.value,
    };
    let proposal: typeof state.value;
    let discarded = 0;
    if (scope.value === "following") {
      const affected = state.value.exceptions.filter(
        (item) =>
          item.seriesId === selected.value!.seriesId &&
          +schedulerDate(item.originalStart) >=
            +schedulerDate(selected.value!.originalStart),
      );
      if (affected.length && policy.value === "reject")
        throw new Error(
          `后续有 ${affected.length} 条例外，请选择清除后续例外或仅修改本次。`,
        );
      const result = splitSchedulerRecurrence(
        state.value.series,
        state.value.exceptions,
        selected.value,
        {
          nextEvent: remove
            ? undefined
            : { ...replacement, id: `team-sync-part-${nextId + 1}` },
          exceptionPolicy: policy.value,
        },
      );
      proposal = { series: result.series, exceptions: result.exceptions };
      discarded = result.removedExceptions.length;
    } else
      proposal = {
        series: state.value.series,
        exceptions: setSchedulerRecurrenceException(
          state.value.exceptions,
          selected.value,
          remove ? undefined : replacement,
        ),
      };
    // Save this complete canonical proposal atomically before publishing the projection.
    if (reject.value) throw new Error("模拟保存失败，原系列和例外均保留。");
    state.value = proposal;
    nextId++;
    status.value = `${remove ? "已取消" : "已修改"}${scope.value === "following" ? "本次及以后" : "本次"}；清除 ${discarded} 条后续例外`;
    open.value = false;
  } catch (cause) {
    error.value = cause instanceof Error ? cause.message : "保存失败";
  }
}
function reset() {
  state.value = initialState();
  open.value = false;
  status.value = "点击日程调整安排";
  reject.value = false;
}
</script>
```

### Zoned Recurrence

- `readonly`: Displays the current value without allowing edits.

Example source: src/scheduler/__demos__/zoned-recurrence.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >每周一纽约时间 09:00，跨越夏令时切换后 UTC 时间会变化。RRULE
      由独立适配器解析，结果保留真实时间点；议程卡片同时展示所选时区时间。</c-alert
    >
    <c-space
      ><c-button @click="zone = 'America/New_York'">纽约时间</c-button
      ><c-button @click="zone = 'Asia/Shanghai'">上海时间</c-button
      ><c-tag>{{ zone }}</c-tag></c-space
    >
    <c-scheduler
      :model-value="events"
      default-date="2026-03-09"
      default-mode="agenda"
      readonly
    >
      <template #event="{ event }"
        >{{ event.title }} ·
        {{ formatSchedulerZonedDate(event.start, zone) }}</template
      >
    </c-scheduler>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { expandSchedulerRRule, formatSchedulerZonedDate } from "../adapters";
const zone = ref("America/New_York");
const events = expandSchedulerRRule(
  {
    event: {
      id: "ny",
      title: "纽约例会",
      start: "2026-03-02T14:00:00Z",
      end: "2026-03-02T15:00:00Z",
    },
    timeZone: "America/New_York",
    rule: "FREQ=WEEKLY;BYDAY=MO;COUNT=4",
  },
  { start: new Date("2026-03-01"), end: new Date("2026-04-01") },
);
</script>
```

## Editing and interaction

### Drag Feedback

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-date` | Initial navigation date | Drag Feedback, Duplicate Events, Custom Cards |
| `default-mode` | Default uncontrolled view | Drag Feedback, Duplicate Events, Custom Event |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Drag Feedback, Duplicate Events, Custom Cards |
| `before-change` | Return false to cancel; supports asynchronous interception and save APIs | Custom Event, Custom Editor, External Editor |
| `resource-label` | Resource field name, such as equipment or meeting room | Drag Feedback |
| `start-hour` | Time-grid start hour, 0–23 | Drag Feedback |
<!-- demo-config-notes:end -->


- `step`: Controls the allowed increment.

Example source: src/scheduler/__demos__/drag-feedback.vue

```vue
<template>
  <section class="scheduler-drag-demo">
    <p>
      拖动日程主体查看虚影和目标预览；拖上边缘调整开始，拖下边缘调整结束。按
      Escape 取消，松手才提交。
    </p>
    <c-scheduler
      v-model="events"
      default-date="2026-09-09"
      default-mode="resource-day"
      :resources="resources"
      resource-label="工作台"
      :start-hour="8"
      :end-hour="16"
      :step="15"
      :show-sidebar="false"
      style="--c-scheduler-max-height: 560px"
    >
      <template #event="{ event }">
        <strong>{{ event.title }}</strong
        ><br />
        <span>{{ event.description }}</span>
      </template>
    </c-scheduler>
    <c-button @click="events = createEvents()">重置日程</c-button>
    <ul aria-label="已提交日程">
      <li v-for="event in events" :key="event.id" :data-demo-event="event.id">
        {{ event.title }}：{{ event.start }} → {{ event.end }}；资源：{{
          event.resourceIds?.join(", ") || "无"
        }}
      </li>
    </ul>
  </section>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerResource } from "@cedar-design/ui";
const resources: SchedulerResource[] = [
  { id: "a", label: "工作台 A" },
  { id: "b", label: "工作台 B" },
];
function createEvents(): SchedulerEvent[] {
  return [
    {
      id: "design",
      title: "方案制作",
      description: "自定义卡片内容也会出现在虚影中",
      start: "2026-09-09T09:00:00",
      end: "2026-09-09T10:30:00",
      resourceIds: ["a"],
    },
    {
      id: "review",
      title: "验收检查",
      description: "试着拖动上边缘或下边缘",
      start: "2026-09-09T11:00:00",
      end: "2026-09-09T12:00:00",
      resourceIds: ["b"],
    },
  ];
}
const events = ref(createEvents());
</script>
```

### Duplicate Events

Preview configuration: `default-date="2026-09-16"`, `default-mode="week"`, `:resources="resources"`, `:before-transaction="persist"`.

Example source: src/scheduler/__demos__/duplicate-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >点击日程详情中的“复制日程”，或使用下方按钮。副本取自已保存数据，生成新编号，尚未保存的表单修改不会带入。保存前可调整时间和人员；取消不创建日程。会议室容量为
      2，可体验第三条同时预约被拦截。</c-alert
    >
    <c-space wrap>
      <c-button @click="scheduler?.duplicateEvent('review')"
        >复制评审会议</c-button
      >
      <c-button @click="scheduler?.duplicateEvent('all-day')"
        >复制全天任务</c-button
      >
      <c-button @click="scheduler?.duplicateEvent('backlog')"
        >复制未排期任务</c-button
      >
      <c-checkbox v-model="reject">下一次副本保存失败</c-checkbox>
      <c-tag>已保存 {{ events.length }} 条日程</c-tag>
    </c-space>
    <c-scheduler
      key="duplicate-events"
      ref="scheduler"
      v-model="events"
      default-date="2026-09-16"
      default-mode="week"
      :resources="resources"
      :before-transaction="persist"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerInstance } from "../index";
import type { SchedulerEvent } from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const scheduler = ref<SchedulerInstance>();
const reject = ref(false);
const resources = [{ id: "room", label: "协作会议室", capacity: 2 }];
const events = ref<SchedulerEvent[]>([
  {
    id: "review",
    title: "设计方案评审",
    start: "2026-09-16T10:00:00",
    end: "2026-09-16T11:00:00",
    resourceIds: ["room"],
    description: "讨论方案与任务分配",
    metadata: { taskId: "design" },
  },
  {
    id: "all-day",
    title: "资料整理日",
    start: "2026-09-17",
    end: "2026-09-18",
    allDay: true,
  },
  {
    id: "backlog",
    title: "待安排的用户访谈",
    description: "确认参与人员后安排时间",
  },
]);
const persist: SchedulerBeforeTransaction = async () => {
  const shouldReject = reject.value;
  if (shouldReject) reject.value = false;
  await new Promise((resolve) => setTimeout(resolve, 200));
  if (shouldReject) throw new Error("Simulated save failure");
};
</script>
```

### Event Dialog

Example source: src/scheduler/__demos__/event-dialog.vue

```vue
<template><EventDetailsExample /></template>
<script setup lang="ts">
import EventDetailsExample from "./event-details-example.vue";
</script>
```

### Event Popover

Example source: src/scheduler/__demos__/event-popover.vue

```vue
<template><EventDetailsExample preview /></template>
<script setup lang="ts">
import EventDetailsExample from "./event-details-example.vue";
</script>
```

### Custom Cards

Preview configuration: `default-date="2026-09-09"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/custom-cards.vue

```vue
<template>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    :resources="resources"
  >
    <template #sidebar-extra="{ startDrag, cancelDrag, disabled }">
      <strong>自定义卡片</strong>
      <p>拖到右侧日期或时间格，确认后新增。卡片可重复使用。</p>
      <c-button
        v-for="card in cards"
        :key="card.title"
        class="scheduler-template-card"
        :disabled="disabled"
        :draggable="!disabled"
        @dragstart="startDrag(card, $event)"
        @dragend="cancelDrag"
      >
        <strong>{{ card.title }}</strong>
        <span>{{ card.description }} · {{ card.duration }} 分钟</span>
      </c-button>
    </template>
  </c-scheduler>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerEventTemplate } from "@cedar-design/ui";
import { resources } from "./data";
const events = ref<SchedulerEvent[]>([]);
const cards: SchedulerEventTemplate[] = [
  {
    title: "需求评审",
    description: "确认目标和验收标准",
    duration: 60,
    metadata: { taskId: "review" },
  },
  {
    title: "客户沟通",
    description: "记录反馈与后续安排",
    duration: 30,
    metadata: { taskId: "call" },
  },
  {
    title: "专注工作",
    description: "预留不被打扰的时段",
    duration: 90,
    metadata: { taskId: "focus" },
  },
];
</script>
<style scoped>
.scheduler-template-card {
  display: flex;
  flex-direction: column;
  gap: 8px;
  padding: 12px;
  text-align: left;
  border: 1px solid var(--c-color-border);
  border-radius: 8px;
  color: var(--c-color-text-1);
  background: var(--c-color-bg-2);
  cursor: grab;
}
.scheduler-template-card:disabled {
  cursor: not-allowed;
  opacity: 0.5;
}
.scheduler-template-card span {
  color: var(--c-color-text-2);
}
</style>
```

### Custom Event

Preview configuration: `default-date="2026-09-09"`, `default-mode="week"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/custom-event.vue

```vue
<template>
  <c-alert>
    这里的工作、会议、休息和不可用时段都是 Demo 自己定义的业务类型，并非
    Scheduler
    内置枚举。新增时可选择类型，由业务配置映射标题建议、外观和默认权限。
  </c-alert>
  <c-space>
    <c-checkbox v-model="rejectSave">模拟后端保存失败</c-checkbox>
    <span>{{ requestStatus }}</span>
  </c-space>
  <c-loading :loading="loading" style="display: block">
  <c-scheduler
    :readonly="loading"
    v-model="events"
    default-date="2026-09-09"
    default-mode="week"
    :resources="resources"
    :before-change="saveToMockServer"
  >
    <template #event="{ event }">
      <span>{{ event.title }}</span>
      <c-tag size="sm" :status="event.readonly ? 'neutral' : 'info'">
        {{ typeOf(event).label }} · {{ event.readonly ? "只读" : "可编辑" }}
      </c-tag>
    </template>

    <template
      #editor="{
        action,
        event,
        save,
        remove,
        close,
        readonly,
        pending,
        errorMessage,
      }"
    >
      <h3>{{ action === "create" ? "新增日程" : "编辑日程" }}</h3>
      <c-alert v-if="errorMessage" status="danger">
        {{ errorMessage }}
      </c-alert>
      <c-form
        :model="event"
        layout="vertical"
        @submit="prepareAndSave(event, save)"
      >
        <c-form-item label="日程类型">
          <c-select
            :model-value="typeOf(event).id"
            :disabled="readonly || pending"
            @update:model-value="applyType(event, $event)"
          >
            <c-option
              v-for="type in eventTypes"
              :key="type.id"
              :value="type.id"
            >
              {{ type.label }} · {{ type.readonly ? "默认只读" : "默认可编辑" }}
            </c-option>
          </c-select>
        </c-form-item>

        <div class="scheduler-type-preview" :style="previewStyle(event)">
          <strong>{{ typeOf(event).label }}</strong>
          <span>{{ typeOf(event).description }}</span>
        </div>

        <c-form-item label="标题">
          <c-input
            v-model="event.title"
            :disabled="readonly || pending"
            placeholder="请输入日程标题"
          />
        </c-form-item>
        <c-form-item label="开始时间">
          <c-date
            :model-value="
              event.start == null ? undefined : schedulerDate(event.start)
            "
            :disabled="readonly || pending"
            show-time
            value-format="Date"
            @update:model-value="event.start = $event"
          />
        </c-form-item>
        <c-form-item label="结束时间">
          <c-date
            :model-value="
              event.end == null ? undefined : schedulerDate(event.end)
            "
            :disabled="readonly || pending"
            show-time
            value-format="Date"
            @update:model-value="event.end = $event"
          />
        </c-form-item>
        <c-form-item>
          <c-checkbox
            :model-value="!event.readonly"
            :disabled="readonly || pending"
            @update:model-value="event.readonly = !$event"
          >
            创建后允许修改和拖拽
          </c-checkbox>
        </c-form-item>
        <c-space>
          <c-button :disabled="pending" @click="close">取消</c-button>
          <c-button
            v-if="action === 'edit' && !readonly"
            status="danger"
            :disabled="pending"
            @click="remove"
            >删除</c-button
          >
          <c-button
            v-if="!readonly"
            html-type="submit"
            status="primary"
            :loading="pending"
            >保存日程</c-button
          >
        </c-space>
      </c-form>
    </template>
  </c-scheduler>
  </c-loading>
  <c-collapse class="scheduler-mock-log">
    <c-collapse-item name="request" title="查看最近一次 Mock API 请求">
      <pre>{{ lastRequest || "尚未提交" }}</pre>
    </c-collapse-item>
  </c-collapse>
</template>

<script setup lang="ts">
import { onMounted, ref } from "vue";
import { resources } from "./data";
import { cloneSchedulerEvent, schedulerDate } from "../core";
import type {
  SchedulerBeforeChange,
  SchedulerEvent,
  SchedulerEventBackgroundPattern,
} from "../index";

type EventType = {
  id: string;
  label: string;
  description: string;
  title: string;
  color: string;
  backgroundColor: string;
  backgroundPattern: SchedulerEventBackgroundPattern;
  readonly: boolean;
};

const eventTypes: EventType[] = [
  {
    id: "work",
    label: "工作安排",
    description: "普通任务，可继续编辑和拖拽调整时间。",
    title: "工作安排",
    color: "#1677ff",
    backgroundColor: "#e6f4ff",
    backgroundPattern: "solid",
    readonly: false,
  },
  {
    id: "meeting",
    label: "会议",
    description: "用圆点背景区分协作和沟通类日程。",
    title: "会议",
    color: "#d48806",
    backgroundColor: "#fffbe6",
    backgroundPattern: "dots",
    readonly: false,
  },
  {
    id: "rest",
    label: "休息",
    description: "休息时段默认锁定，保存后不允许修改或拖拽。",
    title: "休息",
    color: "#00a854",
    backgroundColor: "#f0fff4",
    backgroundPattern: "diagonal-stripes",
    readonly: true,
  },
  {
    id: "blocked",
    label: "不可用时段",
    description: "用于停机、封场等占用，默认只读。",
    title: "不可用时段",
    color: "#722ed1",
    backgroundColor: "#f9f0ff",
    backgroundPattern: "crosshatch",
    readonly: true,
  },
];

const seedEvents: SchedulerEvent[] = [
  createEvent("work", "work-1", "需求评审", "09:00", "10:30"),
  createEvent("meeting", "meeting-1", "项目周会", "10:00", "11:30"),
  createEvent("rest", "rest-1", "张志强 休息", "13:00", "15:00"),
  createEvent("blocked", "blocked-1", "会议室维护", "15:30", "17:30"),
];
const events = ref<SchedulerEvent[]>([]);
const loading = ref(true);
const rejectSave = ref(false);
const requestStatus = ref("正在从 Mock API 加载…");
const lastRequest = ref("");
let mockDatabase = seedEvents.map(cloneSchedulerEvent);

const wait = (milliseconds: number) =>
  new Promise((resolve) => setTimeout(resolve, milliseconds));
const mockApi = {
  async list() {
    await wait(300);
    return mockDatabase.map(cloneSchedulerEvent);
  },
  async save(next: SchedulerEvent[]) {
    await wait(500);
    if (rejectSave.value) throw new Error("Mock API：保存被拒绝");
    mockDatabase = next.map(cloneSchedulerEvent);
    return {
      revision: Date.now(),
      events: mockDatabase.map(cloneSchedulerEvent),
    };
  },
};

onMounted(async () => {
  events.value = await mockApi.list();
  loading.value = false;
  requestStatus.value = `已加载 ${events.value.length} 条日程`;
});

const saveToMockServer: SchedulerBeforeChange = async (context) => {
  lastRequest.value = JSON.stringify(
    {
      method: "PUT",
      url: "/api/scheduler/events",
      change: context.type,
      event: context.event,
      events: context.value,
    },
    null,
    2,
  );
  requestStatus.value = "正在提交 metadata 和日程数据…";
  try {
    const response = await mockApi.save(context.value);
    requestStatus.value = `保存成功 · revision ${response.revision}`;
    return true;
  } catch (error) {
    requestStatus.value = error instanceof Error ? error.message : "保存失败";
    throw error;
  }
};

function createEvent(
  typeId: string,
  id: string,
  title: string,
  start: string,
  end: string,
): SchedulerEvent {
  const event: SchedulerEvent = {
    id,
    title,
    start: `2026-09-09T${start}:00`,
    end: `2026-09-09T${end}:00`,
    resourceIds: [],
  };
  applyType(event, typeId, false);
  return event;
}

function typeOf(event: SchedulerEvent): EventType {
  return (
    eventTypes.find((type) => type.id === event.metadata?.typeId) ??
    eventTypes[0]
  );
}

function applyType(event: SchedulerEvent, value: unknown, suggestTitle = true) {
  const previous = typeOf(event);
  const type = eventTypes.find((item) => item.id === value) ?? eventTypes[0];
  const replaceTitle =
    suggestTitle && (!event.title.trim() || event.title === previous.title);
  event.color = type.color;
  event.backgroundColor = type.backgroundColor;
  event.backgroundPattern = type.backgroundPattern;
  event.metadata = { ...event.metadata, typeId: type.id };
  event.readonly = type.readonly;
  if (replaceTitle) event.title = type.title;
}

function prepareAndSave(
  event: SchedulerEvent,
  save: (event?: SchedulerEvent) => void,
) {
  const type = typeOf(event);
  event.color ??= type.color;
  event.backgroundColor ??= type.backgroundColor;
  event.backgroundPattern ??= type.backgroundPattern;
  event.metadata = {
    ...event.metadata,
    typeId: type.id,
    clientRequestId: `demo-${Date.now()}`,
  };
  save(event);
}

function previewStyle(event: SchedulerEvent) {
  const color = event.color ?? "#1677ff";
  const background = event.backgroundColor ?? "#e6f4ff";
  const pattern = event.backgroundPattern;
  const images: Record<SchedulerEventBackgroundPattern, string> = {
    solid: `linear-gradient(${background}, ${background})`,
    "diagonal-stripes": `repeating-linear-gradient(135deg, transparent 0 8px, color-mix(in srgb, ${color} 18%, transparent) 8px 16px)`,
    dots: `radial-gradient(circle, color-mix(in srgb, ${color} 28%, transparent) 1.5px, transparent 1.5px)`,
    crosshatch: `repeating-linear-gradient(45deg, transparent 0 9px, color-mix(in srgb, ${color} 14%, transparent) 9px 11px), repeating-linear-gradient(-45deg, transparent 0 9px, color-mix(in srgb, ${color} 14%, transparent) 9px 11px)`,
  };
  return {
    color,
    backgroundColor: background,
    backgroundImage: images[pattern ?? "solid"],
    backgroundSize: pattern === "dots" ? "10px 10px" : undefined,
    borderColor: color,
  };
}
</script>

<style scoped>
.scheduler-type-preview {
  display: grid;
  gap: 4px;
  margin: 0 0 16px;
  padding: 12px 14px;
  border: 1px solid;
  border-radius: 8px;
}

.scheduler-type-preview span {
  font-size: 12px;
  opacity: 0.75;
}

.scheduler-mock-log {
  margin-top: 12px;
}

.scheduler-mock-log pre {
  max-height: 260px;
  overflow: auto;
  padding: 12px;
  border-radius: 8px;
  background: var(--c-color-fill-1);
  font-size: 12px;
}
</style>
```

### Custom Editor

Preview configuration: `default-date="2026-09-09"`, `default-mode="day"`, `:before-change="beforeChange"`, `:model="event"`.

Example source: src/scheduler/__demos__/custom-editor.vue

```vue
<template>
  <c-checkbox v-model="reject">模拟接口拒绝保存</c-checkbox>
  <p>保留内置抽屉，替换全部表单内容；可看到新建/编辑标识及校验、接口错误。</p>
  <c-scheduler
    v-model="events"
    default-date="2026-09-09"
    default-mode="day"
    :before-change="beforeChange"
  >
    <template
      #editor="{
        action,
        event,
        save,
        remove,
        close,
        readonly,
        pending,
        errorMessage,
      }"
    >
      <h3>{{ action === "create" ? "新增工作计划" : "修改工作计划" }}</h3>
      <c-alert v-if="errorMessage" status="danger">{{ errorMessage }}</c-alert>
      <c-form :model="event" layout="vertical" @submit="save(event)">
        <c-form-item label="计划标题">
          <c-input v-model="event.title" :disabled="readonly || pending" />
        </c-form-item>
        <c-form-item label="开始时间">
          <c-date
            :model-value="event.start == null ? undefined : schedulerDate(event.start)"
            @update:model-value="event.start = $event"
            :show-time="!event.allDay"
            value-format="Date"
            :disabled="readonly || pending"
          />
        </c-form-item>
        <c-form-item label="结束时间（不含）">
          <c-date
            :model-value="event.end == null ? undefined : schedulerDate(event.end)"
            @update:model-value="event.end = $event"
            :show-time="!event.allDay"
            value-format="Date"
            :disabled="readonly || pending"
          />
        </c-form-item>
        <c-form-item label="验收说明">
          <c-textarea
            v-model="event.description"
            :disabled="readonly || pending"
          />
        </c-form-item>
        <c-space>
          <c-button :disabled="pending" @click="close">取消</c-button>
          <c-button
            v-if="action === 'edit' && !readonly"
            status="danger"
            :disabled="pending"
            @click="remove"
            >删除</c-button
          >
          <c-button
            v-if="!readonly"
            html-type="submit"
            status="primary"
            :loading="pending"
            >保存计划</c-button
          >
        </c-space>
      </c-form>
    </template>
  </c-scheduler>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { schedulerDate } from "@cedar-design/ui/scheduler/core";
import type { SchedulerEvent, SchedulerBeforeChange } from "@cedar-design/ui";
const events = ref<SchedulerEvent[]>([
  {
    id: "plan",
    title: "交付验收",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T10:00:00",
    description: "确认验收清单",
  },
]);
const reject = ref(false);
const beforeChange: SchedulerBeforeChange = async () => {
  if (reject.value) throw new Error("模拟接口拒绝");
  return true;
};
</script>
```

### External Editor

Preview configuration: `:editable="false"`, `default-date="2026-09-09"`, `default-mode="day"`, `:before-change="beforeChange"`.

Example source: src/scheduler/__demos__/external-editor.vue

```vue
<template>
  <p>
    关闭内置编辑器，统一接收工具栏、日期格、卡片拖入及已有日程请求，使用独立
    Dialog。取消不写入，保存失败保留表单。
  </p>
  <c-checkbox v-model="reject">下一次模拟接口提交失败</c-checkbox>
  <c-scheduler
    ref="scheduler"
    v-model="events"
    :editable="false"
    default-date="2026-09-09"
    default-mode="day"
    :before-change="beforeChange"
    @editor-request="openEditor"
    @change-error="showError"
  >
    <template #sidebar-extra="{ startDrag, cancelDrag, disabled }">
      <c-button
        :draggable="!disabled"
        :disabled="disabled"
        @dragstart="startDrag(card, $event)"
        @dragend="cancelDrag"
        >拖入：现场检查 · 60 分钟</c-button
      >
    </template>
  </c-scheduler>
  <c-dialog
    v-model:open="open"
    :title="request?.action === 'create' ? '业务新增窗口' : '业务详情窗口'"
    :footer="false"
    :closable="!saving"
    :overlay-closable="!saving"
    :esc-to-close="!saving"
  >
    <template v-if="draft">
      <p>请求来源：{{ request?.source }}；业务页面也可接收相同请求。</p>
      <c-alert v-if="errorMessage" status="danger">{{ errorMessage }}</c-alert>
      <c-form :model="draft" layout="vertical" @submit="submit()">
        <c-form-item label="任务名称"
          ><c-input
            v-model="draft.title"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-form-item label="开始"
          ><c-date
            :model-value="draft.start == null ? undefined : schedulerDate(draft.start)"
            @update:model-value="draft.start = $event"
            :show-time="!draft.allDay"
            value-format="Date"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-form-item label="结束（不含）"
          ><c-date
            :model-value="draft.end == null ? undefined : schedulerDate(draft.end)"
            @update:model-value="draft.end = $event"
            :show-time="!draft.allDay"
            value-format="Date"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-form-item label="工作说明"
          ><c-textarea
            v-model="draft.description"
            :disabled="request?.readonly || saving"
        /></c-form-item>
        <c-space>
          <c-button :disabled="saving" @click="open = false">取消</c-button>
          <c-button
            v-if="request?.action === 'edit' && !request.readonly"
            status="danger"
            :disabled="saving"
            @click="submit(true)"
            >删除</c-button
          >
          <c-button
            v-if="!request?.readonly"
            status="primary"
            html-type="submit"
            :loading="saving"
            >确认保存</c-button
          >
        </c-space>
      </c-form>
    </template>
  </c-dialog>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { cloneSchedulerEvent, schedulerDate } from "@cedar-design/ui/scheduler/core";
import type {
  SchedulerInstance,
  SchedulerEvent,
  SchedulerEditorRequest,
  SchedulerEventTemplate,
  SchedulerBeforeChange,
} from "@cedar-design/ui";
const scheduler = ref<SchedulerInstance>();
const events = ref<SchedulerEvent[]>([
  {
    id: "inspection",
    title: "设备例行检查",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
  },
]);
const card: SchedulerEventTemplate = {
  title: "现场检查",
  duration: 60,
  description: "核对运行参数",
};
const request = ref<SchedulerEditorRequest>();
const draft = ref<SchedulerEvent>();
const open = ref(false);
const saving = ref(false);
const reject = ref(false);
const errorMessage = ref("");
let snapshot: string | undefined;
function openEditor(value: SchedulerEditorRequest) {
  if (open.value || saving.value) return;
  request.value = value;
  draft.value = cloneSchedulerEvent(value.event);
  snapshot = JSON.stringify(
    events.value.find((item) => item.id === value.event.id),
  );
  errorMessage.value = "";
  open.value = true;
}
const beforeChange: SchedulerBeforeChange = async () => {
  if (reject.value) {
    reject.value = false;
    throw new Error("模拟接口提交失败，请保留草稿直接重试");
  }
  return true;
};
function showError(error: unknown) {
  errorMessage.value = error instanceof Error ? error.message : "保存失败";
}
async function submit(remove = false) {
  if (
    !draft.value ||
    !request.value ||
    request.value.readonly ||
    saving.value ||
    !scheduler.value
  )
    return;
  if (
    draft.value.id !== request.value.event.id ||
    JSON.stringify(events.value.find((item) => item.id === draft.value!.id)) !==
      snapshot
  ) {
    errorMessage.value = "原日程已变化，请关闭并重新打开。";
    return;
  }
  saving.value = true;
  errorMessage.value = "";
  try {
    const success = await scheduler.value.change({
      type: remove
        ? "remove"
        : request.value.action === "create"
          ? "create"
          : "update",
      event: cloneSchedulerEvent(draft.value),
    });
    if (success) open.value = false;
    else if (!errorMessage.value)
      errorMessage.value = "保存被取消或当前不可提交，请重试。";
  } finally {
    saving.value = false;
  }
}
</script>
```

### Batch History

Preview configuration: `v-model:selected-keys="selected"`, `default-date="2026-09-09"`, `default-mode="resource-timeline"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/batch-history.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >开启“多选”后点击日程卡片，可整批后移一天、添加资源或删除。共享日程在多个资源列中只计为一项；撤销和重做同样经过保存接口。</c-alert
    >
    <c-checkbox v-model="reject">模拟整批保存失败</c-checkbox>
    <c-scheduler
      v-model="events"
      v-model:selected-keys="selected"
      default-date="2026-09-09"
      default-mode="resource-timeline"
      :resources="resources"
      selectable
      history
      :before-transaction="persist"
    />
    <c-tag>{{ status }}</c-tag>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerBeforeTransaction } from "../props";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
const selected = ref<string[]>([]);
const reject = ref(false);
const status = ref("尚未提交");
const persist: SchedulerBeforeTransaction = async (context) => {
  status.value = `正在提交 ${context.changes.length} 项变更…`;
  await new Promise((resolve) => setTimeout(resolve, 350));
  if (reject.value) {
    status.value = "整批保存失败，日程和历史均保留";
    throw new Error("Demo rejected");
  }
  status.value = `已提交 ${context.changes.length} 项变更（${context.action === "undo" ? "撤销" : context.action === "redo" ? "重做" : "修改"}）`;
};
</script>
```

### Atomic Swap

Preview configuration: `default-date="2026-09-09"`, `default-mode="resource-day"`, `:resources="[{ id: 'room', label: '会议室 A' }]"`, `:allow-overlap="false"`.

Example source: src/scheduler/__demos__/atomic-swap.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >会议室禁止重叠。两条日程可以通过一次事务交换时间；整体校验最终结果，任一项失败都不会改变另一项。</c-alert
    >
    <c-button @click="swap">交换两个会议的时间</c-button>
    <c-scheduler
      ref="scheduler"
      v-model="events"
      default-date="2026-09-09"
      default-mode="resource-day"
      :resources="[{ id: 'room', label: '会议室 A' }]"
      :allow-overlap="false"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent } from "../core";
import type { SchedulerInstance } from "../index";
const scheduler = ref<SchedulerInstance>();
const events = ref<SchedulerEvent[]>([
  {
    id: "a",
    title: "产品评审",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T10:00:00",
    resourceIds: ["room"],
  },
  {
    id: "b",
    title: "技术评审",
    start: "2026-09-09T10:00:00",
    end: "2026-09-09T11:00:00",
    resourceIds: ["room"],
  },
]);
async function swap() {
  const [a, b] = events.value;
  await scheduler.value?.transaction([
    { type: "move", event: { ...a, start: b.start, end: b.end } },
    { type: "move", event: { ...b, start: a.start, end: a.end } },
  ]);
}
</script>
```

### Interaction Completion

Preview configuration: `v-model:mode="mode"`, `default-date="2026-09-22"`, `:slot-duration="60"`, `:snap-duration="15"`.

Example source: src/scheduler/__demos__/interaction-completion.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >周视图空白处拖选创建，支持向上拖选；网格 60 分钟，指针吸附 15
      分钟，单击新建默认 45 分钟。月视图每天先显示 2
      条，可点击“更多日程”。</c-alert
    >
    <c-space
      ><c-button @click="mode = 'week'">拖选排期</c-button
      ><c-button @click="mode = 'month'">查看月历更多日程</c-button></c-space
    >
    <c-scheduler
      v-model="events"
      v-model:mode="mode"
      default-date="2026-09-22"
      :slot-duration="60"
      :snap-duration="15"
      :default-duration="45"
      :month-event-limit="2"
      drag-to-create
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerMode } from "../core";
const mode = ref<SchedulerMode>("week");
const events = ref<SchedulerEvent[]>(
  Array.from({ length: 5 }, (_, i) => ({
    id: `sample${i}`,
    title: `任务 ${i + 1}`,
    start: `2026-09-22T${String(i + 9).padStart(2, "0")}:00:00`,
    end: `2026-09-22T${String(i + 10).padStart(2, "0")}:00:00`,
  })),
);
</script>
```

### Advanced Planning

Preview configuration: `default-date="2026-09-22"`, `default-mode="resource-timeline"`, `default-scale="hour"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/advanced-planning.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >准备 → 执行 →
      验收里程碑。依赖连线在时间线中展示；把执行拖到准备完成前会被阻止。里程碑使用相同起止时间，不占用资源容量。缩放按钮以视口中心为锚点调整刻度宽度。</c-alert
    >
    <c-scheduler
      v-model="events"
      default-date="2026-09-22"
      default-mode="resource-timeline"
      default-scale="hour"
      :resources="resources"
      :dependencies="dependencies"
      show-resource-load
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type { SchedulerEvent, SchedulerDependency } from "../core";
const resources = [{ id: "team", label: "执行团队", capacity: 1 }];
const dependencies: SchedulerDependency[] = [
  { id: "prepare-run", fromId: "prepare", toId: "run" },
  { id: "run-accept", fromId: "run", toId: "accept" },
];
const events = ref<SchedulerEvent[]>([
  {
    id: "prepare",
    title: "准备",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
    resourceIds: ["team"],
  },
  {
    id: "run",
    title: "执行",
    start: "2026-09-22T10:00:00",
    end: "2026-09-22T12:00:00",
    resourceIds: ["team"],
  },
  {
    id: "accept",
    title: "验收里程碑",
    start: "2026-09-22T12:00:00",
    end: "2026-09-22T12:00:00",
    milestone: true,
    resourceIds: ["team"],
  },
]);
</script>
```

## Async loading and saving

### Async Resources

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-mode` | Default uncontrolled view | Async Resources, Remote Events, Async Change |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Async Resources, Async Change |
| `before-change` | Return false to cancel; supports asynchronous interception and save APIs | Async Resources, Async Change |
| `default-date` | Initial navigation date | Async Resources, Async Change |
| `resource-label` | Resource field name, such as equipment or meeting room | Async Resources |
| `request-resources` | Query resource candidates by keyword and cursor | Async Resources |
<!-- demo-config-notes:end -->


Preview configuration: `options`, `:resources="visibleResources"`, `:resource-label="kind === 'device' ? '设备' : '人员'"`, `:request-resources="requestResources"`.

Example source: src/scheduler/__demos__/async-resources.vue

```vue
<template>
  <c-space direction="column" align="stretch" wrap>
    <c-form-item layout="vertical" hide-label>
      <c-select
        v-model="kind"
        :options="[
          { value: 'device', label: '设备接口' },
          { value: 'person', label: '人员接口' },
        ]"
      />
    </c-form-item>
    <c-button @click="failNextSearch = true">下次搜索模拟失败</c-button>
    <c-button @click="retryHydration">模拟回显失败并重新加载</c-button>
    <c-button @click="useNextPage">切换可见资源页</c-button>
  </c-space>
  <p>
    当前仅提供 {{ visibleResources.length }} 条可见资源。已有日程关联第 12
    条，不在本页，仍通过 ID 接口回显名称。进入编辑器，搜索“12”或滚动加载更多。
  </p>
  <p role="status">{{ feedback }}</p>
  <c-scheduler
    :key="`${kind}-${revision}`"
    v-model="events"
    :resources="visibleResources"
    :resource-label="kind === 'device' ? '设备' : '人员'"
    :request-resources="requestResources"
    :resolve-resources="resolveResources"
    :before-change="beforeChange"
    default-mode="agenda"
    default-date="2026-09-09"
    @resource-error="resourceError"
  />
</template>
<script setup lang="ts">
import { computed, onScopeDispose, ref, watch } from "vue";
import type {
  SchedulerEvent,
  SchedulerRequestResources,
  SchedulerResolveResources,
  SchedulerBeforeChange,
  SchedulerResourceErrorContext,
} from "@cedar-design/ui";

const kind = ref<"device" | "person">("device");
// 业务接口字段在接入层适配，Scheduler 始终只认识 id / label。
const devices = Array.from({ length: 24 }, (_, index) => ({
  deviceId: `device-${index + 1}`,
  deviceName: `实验设备 ${index + 1}`,
}));
const people = Array.from({ length: 24 }, (_, index) => ({
  userId: `person-${index + 1}`,
  displayName: `工程师 ${index + 1}`,
}));
const directory = computed(() =>
  kind.value === "device"
    ? devices.map((item) => ({ id: item.deviceId, label: item.deviceName }))
    : people.map((item) => ({ id: item.userId, label: item.displayName })),
);
const page = ref(0);
const revision = ref(0);
const visibleResources = computed(() =>
  directory.value.slice(page.value * 4, page.value * 4 + 4),
);
const events = ref<SchedulerEvent[]>([]);
const feedback = ref("打开详情查看名称回显，或在资源下拉框搜索。");
const failNextSearch = ref(false);
const failNextResolve = ref(false);
const failedOperation = ref<"search" | "resolve">();
watch(
  kind,
  () => {
    failedOperation.value = undefined;
    feedback.value = "打开详情查看名称回显，或在资源下拉框搜索。";
    page.value = 0;
    events.value = [
      {
        id: `${kind.value}-job`,
        title: "已有排期：关联不在本页的资源",
        start: "2026-09-09T09:00:00",
        end: "2026-09-09T10:00:00",
        resourceIds: [`${kind.value}-12`],
      },
    ];
  },
  { immediate: true, flush: "sync" },
);

const lifetime = new AbortController();
onScopeDispose(() => lifetime.abort());
// 模拟接口延时；真实接入时直接 fetch(url, { signal })。
function delay(signal: AbortSignal) {
  return new Promise<void>((resolve, reject) => {
    if (signal.aborted) {
      reject(new Error("Aborted"));
      return;
    }
    const abort = () => {
      clearTimeout(timer);
      signal.removeEventListener("abort", abort);
      reject(new Error("Aborted"));
    };
    const timer = setTimeout(() => {
      signal.removeEventListener("abort", abort);
      resolve();
    }, 500);
    signal.addEventListener("abort", abort, { once: true });
  });
}
const requestResources: SchedulerRequestResources = async ({
  query,
  cursor,
  signal,
}) => {
  const data = directory.value;
  const fail = failNextSearch.value;
  failNextSearch.value = false;
  await delay(signal);
  if (fail) throw new Error("模拟搜索网络错误");
  const matches = data.filter(
    (item) => item.label.includes(query) || item.id.includes(query),
  );
  const offset = Number(cursor ?? 0);
  if (failedOperation.value === "search") {
    failedOperation.value = undefined;
    feedback.value = "搜索重试成功，可继续选择资源。";
  }
  return {
    items: matches.slice(offset, offset + 4),
    nextCursor: offset + 4 < matches.length ? String(offset + 4) : undefined,
  };
};
const resolveResources: SchedulerResolveResources = async (ids, { signal }) => {
  const data = directory.value;
  const fail = failNextResolve.value;
  failNextResolve.value = false;
  await delay(signal);
  if (fail) throw new Error("模拟回显网络错误");
  if (failedOperation.value === "resolve") {
    failedOperation.value = undefined;
    feedback.value = "资源名称回显成功，关联 ID 保持不变。";
  }
  return data.filter((item) => ids.includes(item.id));
};
const beforeChange: SchedulerBeforeChange = async ({ event, type }) => {
  const data = directory.value;
  await delay(lifetime.signal);
  // 演示服务端校验；生产环境还应验证权限、版本和全量时段冲突。
  if (
    type !== "remove" &&
    event.resourceIds?.some((id) => !data.some((item) => item.id === id))
  )
    throw new Error("资源不存在");
  feedback.value = "模拟接口保存成功，日程只保存 resourceIds，不保存显示名称。";
};
function resourceError(
  _error: unknown,
  context: SchedulerResourceErrorContext,
) {
  failedOperation.value = context.type;
  feedback.value =
    context.type === "resolve"
      ? "回显失败：ID 仍保留，点击日程内的重试按钮。"
      : "搜索失败：可在下拉框内重试。";
}
function retryHydration() {
  failNextResolve.value = true;
  revision.value++;
}
function useNextPage() {
  page.value = (page.value + 1) % 6;
}
</script>
```

### Remote Events

- `readonly`: Displays the current value without allowing edits.

Example source: src/scheduler/__demos__/remote-events.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >翻页按可见范围请求；返回已访问日期命中 30
      秒缓存。可模拟失败后重试，也可连续切换日期，验证慢响应不会覆盖最新页面。</c-alert
    >
    <c-space wrap>
      <c-button @click="refresh()">刷新 / 重试</c-button>
      <c-button @click="jump(1)">下一天</c-button>
      <c-button @click="jump(-1)">上一天</c-button>
      <c-checkbox v-model="fail">模拟加载失败</c-checkbox>
      <c-checkbox v-model="outOfOrder">模拟乱序响应</c-checkbox>
    </c-space>
    <c-space wrap>
      <c-tag>请求 {{ requests }} 次</c-tag>
      <c-tag>{{
        loading
          ? "加载中"
          : error
            ? "加载失败，请重试"
            : `已加载 ${events.length} 项`
      }}</c-tag>
      <c-tag>{{ status }}</c-tag>
    </c-space>
    <c-scheduler
      v-model="events"
      v-model:date="date"
      default-mode="day"
      :readonly="loading || !!error"
      :before-transaction="persist"
      @range-change="range = $event"
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
import { useSchedulerDataSource } from "../use-data-source";
import {
  applySchedulerTransaction,
  cloneSchedulerEvent,
  isSchedulerEventInRange,
  schedulerDate,
} from "../core";
import type { SchedulerDate, SchedulerEvent, SchedulerRange } from "../core";
import type { SchedulerBeforeTransaction } from "../props";
const date = ref<SchedulerDate>("2026-09-09");
const range = ref<SchedulerRange>();
const fail = ref(false);
const outOfOrder = ref(false);
const requests = ref(0);
const status = ref("编辑日程会保存到模拟服务端");
let database: SchedulerEvent[] = Array.from({ length: 90 }, (_, index) => ({
  id: `remote-${index}`,
  title: `远程计划 ${index + 1}`,
  start: new Date(2026, 7, 15 + index, 9),
  end: new Date(2026, 7, 15 + index, 10),
}));
const { events, loading, error, refresh } = useSchedulerDataSource({
  range,
  requestEvents: async (query) => {
    const sequence = ++requests.value;
    const shouldFail = fail.value;
    const ignoreAbort = outOfOrder.value;
    const result = database
      .filter((event) => isSchedulerEventInRange(event, query))
      .map(cloneSchedulerEvent);
    await new Promise<void>((resolve, reject) => {
      const abort = () => {
        clearTimeout(timer);
        reject(new Error("Aborted"));
      };
      const timer = setTimeout(
        () => {
          query.signal.removeEventListener("abort", abort);
          resolve();
        },
        ignoreAbort ? (sequence % 2 ? 1800 : 200) : 450,
      );
      if (!ignoreAbort)
        query.signal.addEventListener("abort", abort, { once: true });
    });
    if (shouldFail) throw new Error("模拟接口失败");
    return result;
  },
});
function jump(offset: number) {
  const next = schedulerDate(date.value);
  next.setDate(next.getDate() + offset);
  date.value = next;
}
const persist: SchedulerBeforeTransaction = async (context) => {
  // Send the delta to the backend, never replace the full database with a loaded window.
  database = applySchedulerTransaction(database, context.changes);
  status.value = `已保存 ${context.changes.length} 项变更；查询缓存随 v-model 更新失效`;
};
</script>
```

### Async Change

Preview configuration: `:model-value="events"`, `default-date="2026-09-09"`, `default-mode="resource-day"`, `:resources="resources"`.

Example source: src/scheduler/__demos__/async-change.vue

```vue
<template>
  <section class="scheduler-async-demo">
    <c-space direction="column" block>
      <c-space>
        <c-checkbox v-model="reject">下一次模拟保存失败</c-checkbox>
        <c-checkbox v-model="accept">父组件接受更新</c-checkbox>
        <c-button @click="reset">重置日程</c-button>
      </c-space>
      <p>
        本地模拟 600ms
        保存；失败开关在一次失败后自动复位，可直接重试。取消或父组件拒绝提案不改变已保存值。
      </p>
      <c-scheduler
        :model-value="events"
        default-date="2026-09-09"
        default-mode="resource-day"
        :resources="resources"
        :before-change="beforeChange"
        @update:model-value="update"
        @change="outcome = accept ? '父组件已接受' : '父组件未接受提案'"
        @change-error="outcome = '保存失败，原值不变'"
      />
      <p role="status">{{ outcome }}；活动请求：{{ pendingCount }}</p>
      <ul aria-label="异步已提交日程">
        <li v-for="event in events" :key="event.id" :data-demo-event="event.id">
          {{ event.title }}：{{ event.start ?? "未排期" }} →
          {{ event.end ?? "未排期" }}；资源：{{ event.resourceIds?.join(",") }}
        </li>
      </ul>
    </c-space>
  </section>
</template>
<script setup lang="ts">
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type { SchedulerBeforeChange } from "../props";
import type { SchedulerEvent } from "../core";
import { createEvents, resources } from "./data";
const events = ref(createEvents());
const reject = ref(false);
const accept = ref(true);
const outcome = ref("尚未操作");
const pendingCount = ref(0);
const pending = new Map<ReturnType<typeof setTimeout>, () => void>();
const beforeChange: SchedulerBeforeChange = () =>
  new Promise<boolean>((resolve, rejectRequest) => {
    const fail = reject.value;
    const timer = setTimeout(() => {
      pending.delete(timer);
      pendingCount.value = pending.size;
      if (fail) {
        reject.value = false;
        rejectRequest(new Error("模拟接口失败"));
      } else resolve(true);
    }, 600);
    pending.set(timer, () => resolve(false));
    pendingCount.value = pending.size;
  });
function update(value: SchedulerEvent[]) {
  if (accept.value) events.value = value;
}
function cancelPending() {
  pending.forEach((cancel, timer) => {
    clearTimeout(timer);
    cancel();
  });
  pending.clear();
  pendingCount.value = 0;
}
function reset() {
  cancelPending();
  events.value = createEvents();
  outcome.value = "已重置";
}
onBeforeUnmount(cancelPending);
onDeactivated(cancelPending);
</script>
```

## Workflows and integration

### Equipment

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `resources` | Currently visible resource rows/columns and local options; a complete directory is unnecessary | Equipment, Task Calendar Details, Task Calendar Workbench |
| `default-mode` | Default uncontrolled view | Equipment, Calendar Integration, Task Calendar Details |
| `default-date` | Initial navigation date | Equipment, Calendar Integration, Task Calendar Details |
| `editable` | Enable the built-in editor; false delegates through editor-request | Task Calendar Details, Task Calendar Workbench |
| `start-hour` | Time-grid start hour, 0–23 | Task Calendar Details, Task Calendar Workbench |
| `end-hour` | Time-grid end hour; greater than start and at most 24 | Task Calendar Details, Task Calendar Workbench |
<!-- demo-config-notes:end -->


Preview configuration: `:resources="devices"`, `resource-label="设备"`, `default-mode="resource-day"`, `default-date="2026-09-09"`.

Example source: src/scheduler/__demos__/equipment.vue

```vue
<template>
  <p>
    设备共享使用时段：拖入左侧任务后确认排期；维护中的设备禁止新增分配，同一设备的时间冲突会阻止保存。
  </p>
  <c-scheduler
    v-model="events"
    :resources="devices"
    resource-label="设备"
    default-mode="resource-day"
    default-date="2026-09-09"
    :allow-overlap="false"
  >
    <template #sidebar-extra="{ startDrag, cancelDrag, disabled }">
      <strong>待安排工单</strong>
      <c-button
        v-for="task in tasks"
        :key="String(task.metadata?.taskId)"
        :draggable="!disabled"
        :disabled="disabled"
        @dragstart="startDrag(task, $event)"
        @dragend="cancelDrag"
      >
        {{ task.title }} · {{ task.duration }} 分钟
      </c-button>
    </template>
    <template #resource-header="{ resource, date }">
      <strong>{{ resource?.label ?? date.toLocaleDateString() }}</strong>
      <small v-if="resource">
        · {{ resource.disabled ? "维护中" : "可预约" }}</small
      >
    </template>
    <template #event="{ event }">
      <strong>{{ event.title }}</strong
      ><span v-if="event.metadata?.taskId">
        · {{ event.metadata?.taskId }}</span
      >
    </template>
  </c-scheduler>
</template>
<script setup lang="ts">
import { ref } from "vue";
import type {
  SchedulerEvent,
  SchedulerResource,
  SchedulerEventTemplate,
} from "@cedar-design/ui";
const devices: SchedulerResource[] = [
  { id: "laser-01", label: "激光切割机 01" },
  { id: "printer-02", label: "3D 打印机 02" },
  { id: "scanner-03", label: "扫描仪 03", disabled: true },
];
const tasks: SchedulerEventTemplate[] = [
  {
    title: "样件加工",
    duration: 90,
    metadata: { taskId: "JOB-201" },
    description: "安排加工设备并确认材料",
  },
  {
    title: "设备校准",
    duration: 30,
    metadata: { taskId: "JOB-202" },
    description: "校准完成后记录结果",
  },
];
const events = ref<SchedulerEvent[]>([
  {
    id: "run-1",
    title: "批次 A 加工",
    start: "2026-09-09T09:00:00",
    end: "2026-09-09T11:00:00",
    resourceIds: ["laser-01"],
    metadata: { taskId: "JOB-100" },
  },
  {
    id: "run-2",
    title: "联合验收（共用两台设备）",
    start: "2026-09-09T14:00:00",
    end: "2026-09-09T15:00:00",
    resourceIds: ["laser-01", "printer-02"],
    metadata: { taskId: "JOB-101" },
  },
  {
    id: "maintenance",
    title: "停机维护",
    start: "2026-09-09",
    end: "2026-09-10",
    allDay: true,
    resourceIds: ["scanner-03"],
    readonly: true,
  },
]);
</script>
```

### Calendar Integration

Preview configuration: `placeholder="ICS 文本"`, `:rows="4"`, `default-date="2026-09-22"`, `default-mode="week"`.

Example source: src/scheduler/__demos__/calendar-integration.vue

```vue
<template>
  <c-space direction="column" block>
    <c-alert
      >模拟服务端持有版本号：编辑保存延迟
      300ms，期间模拟远端更新会触发过期保护。导入/导出使用真实 ICS
      文本；打印生成独立文档，不打印整页组件文档。</c-alert
    >
    <c-space
      ><c-button @click="remote">模拟远端更新</c-button
      ><c-button @click="exportIcs">导出 ICS 文本</c-button
      ><c-button @click="importIcs">导入 ICS 文本</c-button
      ><c-button @click="print">打印日程</c-button
      ><c-tag>版本 {{ revision }}</c-tag></c-space
    >
    <c-alert v-if="error" status="danger">{{ error }}</c-alert>
    <c-textarea v-model="ical" placeholder="ICS 文本" :rows="4" />
    <c-scheduler
      v-model="events"
      default-date="2026-09-22"
      default-mode="week"
      :before-transaction="save"
      history
    />
  </c-space>
</template>
<script setup lang="ts">
import { ref, onBeforeUnmount } from "vue";
import {
  createSchedulerMemoryProvider,
  exportSchedulerICalendar,
  importSchedulerICalendar,
  createSchedulerPrintHtml,
} from "../adapters";
import type { SchedulerEvent, SchedulerTransactionContext } from "../core";
const events = ref<SchedulerEvent[]>([
  {
    id: "meeting",
    title: "团队会议",
    start: "2026-09-22T09:00:00",
    end: "2026-09-22T10:00:00",
  },
]);
const source = createSchedulerMemoryProvider(events.value),
  revision = ref(0),
  ical = ref(""),
  error = ref("");
const stop = source.subscribe!((snapshot, origin) => {
  if (origin === "editor") return;
  revision.value = snapshot.revision;
  events.value = snapshot.events;
});
onBeforeUnmount(stop);
async function save(context: SchedulerTransactionContext) {
  const expected = revision.value;
  await new Promise((resolve) => setTimeout(resolve, 300));
  const next = await source.commit(context.changes, expected, "editor");
  revision.value = next.revision;
}
async function remote() {
  try {
    await source.commit(
      [
        {
          type: "update",
          event: {
            ...events.value[0],
            title: `远端更新 ${revision.value + 1}`,
          },
        },
      ],
      revision.value,
      "remote",
    );
  } catch (cause) {
    error.value = String(cause);
  }
}
function exportIcs() {
  try {
    ical.value = exportSchedulerICalendar(events.value, {
      stamp: new Date(),
      name: "Cedar demo",
    });
    error.value = "";
  } catch (cause) {
    error.value = String(cause);
  }
}
async function importIcs() {
  try {
    const parsed = importSchedulerICalendar(ical.value, {
      timeZone: "Asia/Shanghai",
    });
    if (parsed.series.length)
      throw new Error("含重复系列，请先通过 RRULE 适配器展开");
    const existing = new Set(events.value.map((event) => event.id));
    await source.commit(
      parsed.events.map((event) => ({
        type: existing.has(event.id) ? "update" : "create",
        event,
      })),
      revision.value,
      "import",
    );
    error.value = "";
  } catch (cause) {
    error.value = String(cause);
  }
}
function print() {
  const page = window.open("", "_blank");
  if (!page) return;
  page.document.open();
  page.document.write(
    createSchedulerPrintHtml(events.value, { title: "团队日程" }),
  );
  page.document.close();
  page.focus();
  page.print();
}
</script>
```

### Task Calendar Details

Preview configuration: `:editable="false"`, `:resources="resources"`, `default-date="2026-09-09"`, `default-mode="resource-day"`.

Example source: src/scheduler/__demos__/task-calendar-details.vue

```vue
<template>
  <c-alert>
    点击日程先查看业务摘要，再进入高级详情。完整出勤单、任务与打卡记录由页面按
    metadata ID 查询，Scheduler 只保存展示字段和业务 ID。
  </c-alert>
  <c-scheduler
    v-model="events"
    :editable="false"
    :resources="resources"
    default-date="2026-09-09"
    default-mode="resource-day"
    :start-hour="0"
    :end-hour="24"
    :initial-scroll-minute="420"
    :modes="['resource-day']"
    :show-sidebar="false"
    @editor-request="activate"
  >
    <template #event="{ event }">
      <EventSummaryPopover
        :open="previewId === event.id"
        :title="event.title"
        @update:open="!$event && (previewId = undefined)"
        @click-outside="previewId = undefined"
      >
        <span :class="{ 'completed-event': event.readonly }">
          {{ event.title }} · {{ personLabel(event) }}
        </span>
        <template #content>
          <c-space v-if="orderOf(event)" direction="column" block>
            <c-space>
              <c-tag>{{ statusLabel(orderOf(event)!) }}</c-tag>
              <c-tag>{{ orderOf(event)!.source }}</c-tag>
            </c-space>
            <strong>{{ timeRange(event) }}</strong>
            <span>
              {{ orderOf(event)!.tasks.length }} 项任务 ·
              {{ totalMinutes(orderOf(event)!) }} 分钟 · 1 人
            </span>
            <span>设备：{{ deviceLabels(orderOf(event)!) }}</span>
            <span>最近打卡：{{ latestPunch(orderOf(event)!) }}</span>
            <c-space>
              <c-button status="primary" @click.stop="openDetails(event)">
                高级详情
              </c-button>
              <c-button @click.stop="previewId = undefined">关闭</c-button>
            </c-space>
          </c-space>
        </template>
      </EventSummaryPopover>
    </template>
  </c-scheduler>

  <c-dialog v-model:open="detailsOpen" title="出勤单高级详情" :footer="false">
    <template v-if="activeOrder">
      <c-space direction="column" block>
        <c-space>
          <c-tag>{{ statusLabel(activeOrder) }}</c-tag>
          <c-tag>{{ activeOrder.source }}</c-tag>
        </c-space>
        <p>执行人：{{ resourceLabel(activeOrder.personId) }} · 人数：1</p>
        <p>
          计划时间：{{ displayTime(activeOrder.plannedStart) }} –
          {{ displayTime(activeOrder.plannedEnd) }}
        </p>
        <p v-if="activeOrder.actualStart">
          实际时间：{{ displayTime(activeOrder.actualStart) }} –
          {{ displayTime(activeOrder.actualEnd) }}
        </p>
        <c-divider />
        <strong>任务与工单</strong>
        <div v-for="task in activeOrder.tasks" :key="task.id">
          <c-link :href="`#work-order-${task.id}`">{{ task.title }}</c-link>
          · 技能 {{ skillLabel(task.skill) }} · {{ task.standardMinutes }} 分钟
        </div>
        <p>总标准工时：{{ totalMinutes(activeOrder) }} 分钟</p>
        <c-divider />
        <strong>打卡记录</strong>
        <div v-for="record in activeOrder.punchRecords" :key="record.id">
          {{ resourceLabel(record.deviceId) }}：
          {{ displayTime(record.checkedInAt) }} –
          {{ displayTime(record.checkedOutAt) }}
        </div>
        <c-empty
          v-if="!activeOrder.punchRecords.length"
          description="暂无打卡记录"
        />
        <c-space>
          <c-button @click="detailsOpen = false">关闭</c-button>
          <c-button
            v-if="
              activeOrder.status !== 'closed' && activeOrder.kind !== 'rest'
            "
            status="primary"
            @click="closeOrder(activeOrder)"
          >
            按实际打卡时间关单
          </c-button>
        </c-space>
      </c-space>
    </template>
  </c-dialog>
</template>

<script setup lang="ts">
import { computed, ref } from "vue";
import type {
  SchedulerEditorRequest,
  SchedulerEvent,
  SchedulerResource,
} from "@cedar-design/ui";
import EventSummaryPopover from "./event-summary-popover.vue";
import {
  toTaskCalendarEvent,
  type TaskCalendarOrder,
} from "./task-calendar-model";

const resources: SchedulerResource[] = [
  { id: "person-li", label: "李卫东" },
  { id: "person-zhang", label: "张志强" },
  { id: "device-a", label: "月检站 A" },
  { id: "device-c", label: "预警处理台 C" },
];
const orders = ref<TaskCalendarOrder[]>([
  {
    id: "detail-101",
    kind: "work",
    status: "review",
    source: "设备待办",
    personId: "person-li",
    plannedStart: "2026-09-09T09:00:00",
    plannedEnd: "2026-09-09T11:00:00",
    tasks: [
      {
        id: "WO-301",
        title: "月检与运行参数复核",
        deviceId: "device-a",
        skill: "inspection",
        standardMinutes: 120,
      },
    ],
    punchRecords: [
      {
        id: "punch-1",
        deviceId: "device-a",
        checkedInAt: "2026-09-09T09:12:00",
        checkedOutAt: "2026-09-09T10:48:00",
      },
    ],
    color: "#1677ff",
  },
  {
    id: "detail-102",
    kind: "work",
    status: "closed",
    source: "站长负责范围",
    personId: "person-zhang",
    plannedStart: "2026-09-09T13:00:00",
    plannedEnd: "2026-09-09T14:00:00",
    actualStart: "2026-09-09T13:08:00",
    actualEnd: "2026-09-09T13:52:00",
    tasks: [
      {
        id: "WO-302",
        title: "预警处理",
        deviceId: "device-c",
        skill: "warning",
        standardMinutes: 60,
      },
    ],
    punchRecords: [
      {
        id: "punch-2",
        deviceId: "device-c",
        checkedInAt: "2026-09-09T13:08:00",
        checkedOutAt: "2026-09-09T13:52:00",
      },
    ],
    color: "#86909c",
  },
  {
    id: "detail-rest",
    kind: "rest",
    status: "planned",
    source: "个人安排",
    personId: "person-li",
    plannedStart: "2026-09-09T12:00:00",
    plannedEnd: "2026-09-09T13:00:00",
    tasks: [],
    punchRecords: [],
    color: "#00a854",
  },
]);
const events = ref<SchedulerEvent[]>(orders.value.map(toTaskCalendarEvent));
const previewId = ref<string>();
const activeOrderId = ref<string>();
const detailsOpen = ref(false);
const activeOrder = computed(() =>
  orders.value.find((order) => order.id === activeOrderId.value),
);

function activate(request: SchedulerEditorRequest) {
  if (request.action !== "edit") return;
  previewId.value = request.event.id;
  activeOrderId.value = businessId(request.event);
}
function openDetails(event: SchedulerEvent) {
  activeOrderId.value = businessId(event);
  previewId.value = undefined;
  detailsOpen.value = true;
}
function closeOrder(order: TaskCalendarOrder) {
  const punches = order.punchRecords;
  const first = punches[0]?.checkedInAt;
  const last = punches.at(-1)?.checkedOutAt;
  if (!first || !last) return;
  orders.value = orders.value.map((item) =>
    item.id === order.id
      ? { ...item, status: "closed", actualStart: first, actualEnd: last }
      : item,
  );
  events.value = orders.value.map(toTaskCalendarEvent);
}
function businessId(event: SchedulerEvent) {
  return String(event.metadata?.attendanceOrderId ?? event.id);
}
function orderOf(event: SchedulerEvent) {
  return orders.value.find((order) => order.id === businessId(event));
}
function totalMinutes(order: TaskCalendarOrder) {
  return order.tasks.reduce((total, task) => total + task.standardMinutes, 0);
}
function deviceLabels(order: TaskCalendarOrder) {
  return (
    [...new Set(order.tasks.map((task) => resourceLabel(task.deviceId)))].join(
      "、",
    ) || "无"
  );
}
function personLabel(event: SchedulerEvent) {
  return resourceLabel(orderOf(event)?.personId);
}
function resourceLabel(id?: string) {
  return resources.find((resource) => resource.id === id)?.label ?? "未知";
}
function skillLabel(skill: string) {
  return { inspection: "巡检", warning: "预警处理" }[skill] ?? skill;
}
function statusLabel(order: TaskCalendarOrder) {
  if (order.kind === "rest") return "休息";
  return {
    planned: "计划中",
    active: "执行中",
    review: "待关单",
    closed: "已完成",
  }[order.status];
}
function latestPunch(order: TaskCalendarOrder) {
  const record = order.punchRecords.at(-1);
  return record
    ? `${displayTime(record.checkedInAt)} – ${displayTime(record.checkedOutAt)}`
    : "暂无";
}
function timeRange(event: SchedulerEvent) {
  return `${displayTime(event.start)} – ${displayTime(event.end)}`;
}
function displayTime(value?: string | number | Date) {
  return value == null
    ? "未记录"
    : new Date(value).toLocaleString("zh-CN", {
        month: "numeric",
        day: "numeric",
        hour: "2-digit",
        minute: "2-digit",
        hour12: false,
      });
}
</script>

<style scoped>
.completed-event {
  opacity: 0.55;
}
</style>
```

### Task Calendar Workbench

- `step`: Controls the allowed increment.
- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/scheduler/__demos__/task-calendar-workbench.vue

```vue
<template>
  <div
    ref="host"
    class="workbench-shell"
    @pointerdown.capture="captureDrag"
    @dragend="endDrag"
  >
    <nav v-if="navigationOpen" class="workbench-nav" aria-label="应用导航">
      <c-button variant="text">任务日历</c-button>
      <c-button variant="text" @click="navigationOpen = false"
        >收起导航</c-button
      >
    </nav>
    <c-scheduler
      ref="scheduler"
      class="task-calendar-workbench"
      :model-value="events"
      v-model:date="date"
      mode="week"
      show-now-indicator
      :snap-duration="1"
      :modes="['week']"
      :step="60"
      :start-hour="0"
      :end-hour="24"
      :initial-scroll-minute="420"
      :resources="data.resources"
      :event-layout="workbenchLayout"
      :editable="false"
      :readonly="role === 'viewer'"
      :disabled="saving"
      :preview-event="preview"
      :before-change="prepareMove"
      @change="finishMove"
      @change-error="moveError"
      @editor-request="openEditor"
    >
      <template #toolbar="{ navigate, create }">
        <c-space wrap>
          <c-button
            :aria-expanded="navigationOpen"
            @click="navigationOpen = !navigationOpen"
            >导航</c-button
          >
          <c-button aria-label="上一周" :disabled="saving" @click="navigate(-1)"
            >‹</c-button
          >
          <c-popover
            trigger="click"
            placement="bottom-start"
            :open="datePickerOpen"
            @update:open="datePickerOpen = $event"
          >
            <c-button :disabled="saving">{{ weekLabel(date) }}</c-button>
            <template #content
              ><c-date-picker
                :model-value="date"
                value-format="Date"
                @update:model-value="chooseDate"
            /></template>
          </c-popover>
          <c-button aria-label="下一周" :disabled="saving" @click="navigate(1)"
            >›</c-button
          >
          <c-button :disabled="saving" @click="goToday">今天</c-button>
        </c-space>
        <c-button
          status="primary"
          :disabled="saving || role === 'viewer'"
          @click="create"
          >新增出勤单</c-button
        >
      </template>
      <template #sidebar="{ startDrag, cancelDrag, disabled }">
        <div class="workbench-panels">
          <section class="source-panel" aria-label="人员设备选择">
            <strong class="panel-title">人员与设备</strong>
            <c-input
              v-model="query"
              placeholder="搜索人员、账号或设备"
              clearable
              :disabled="saving"
            />
            <div class="panel-scroll source-scroll">
              <c-tree
                :data="sourceTree"
                :checked-values="sourceKeys"
                :expanded-values="expandedSources"
                checkable
                only-check-leaf
                block-node
                :selectable="false"
                :disabled="saving"
                @update:expanded-values="expandedSources = $event"
                @check="checkSources"
              >
                <template #label="node">
                  <span
                    v-if="node.resourceId"
                    class="source-object"
                    :data-owner="node.resourceId"
                  >
                    {{ resource(node.resourceId)?.label }}
                    <small v-if="resource(node.resourceId)?.account">{{
                      resource(node.resourceId)?.account
                    }}</small>
                    <span
                      v-if="resource(node.resourceId)?.managers"
                      class="quick-actions"
                    >
                      <c-button
                        v-for="id in resource(node.resourceId)?.managers"
                        :key="id"
                        size="xs"
                        :disabled="saving"
                        :aria-pressed="selected.includes(id)"
                        @click.stop="toggleResource(id)"
                        >{{ resource(id)?.label }}
                        {{ selected.includes(id) ? "−" : "+" }}</c-button
                      >
                    </span>
                  </span>
                  <span v-else>{{ node.label }}</span>
                </template>
              </c-tree>
            </div>
          </section>
          <section class="pending-panel" aria-label="待分配任务">
            <strong
              >待分配任务 <c-tag>{{ pending.length }}</c-tag></strong
            >
            <div class="panel-scroll">
              <c-tree
                :data="pendingTree"
                :checked-values="pendingKeys"
                :expanded-values="expandedPending"
                checkable
                only-check-leaf
                block-node
                :selectable="false"
                :disabled="disabled"
                @update:expanded-values="expandedPending = $event"
                @check="checkPending"
              >
                <template #label="node">
                  <div
                    v-if="node.taskId"
                    class="pending-task"
                    :class="deadlineClass(task(node.taskId))"
                    :draggable="!disabled"
                    @dragstart="beginPending(node.taskId, startDrag, $event)"
                    @dragend="
                      cancelDrag();
                      endDrag();
                    "
                  >
                    <strong>{{ task(node.taskId)?.title }}</strong>
                    <span>{{
                      resource(task(node.taskId)?.deviceId)?.label
                    }}</span>
                    <span>{{ deadlineText(task(node.taskId)) }}</span>
                    <span
                      >{{ task(node.taskId)?.skill }} /
                      {{ task(node.taskId)?.people }} 人 /
                      {{ task(node.taskId)?.minutes }} 分钟</span
                    >
                    <small>{{ task(node.taskId)?.source }}</small>
                  </div>
                  <span v-else>{{ node.label }}</span>
                </template>
              </c-tree>
              <c-empty
                v-if="!pendingTree.length"
                description="暂无待分配任务"
              />
            </div>
          </section>
        </div>
      </template>
      <template #resource-header="{ date: day }">
        {{ day.toLocaleDateString("zh-CN", { weekday: "short" }) }}
        {{ day.getDate() }}
      </template>
      <template #column-background="{ date: day }">
        <div
          v-if="dragDeadline && schedulerDateKey(day) > dragDeadline"
          class="deadline-mask"
          aria-label="晚于任务截止日期"
        />
      </template>
      <template #event="{ event }">
        <div
          class="task-card"
          :data-order-id="event.metadata?.orderId"
          :data-edge="event.metadata?.edge"
          :class="{
            linked: activeOrder === event.metadata?.orderId,
            closed: event.metadata?.closed,
            rest: event.metadata?.kind === 'rest',
          }"
          @mouseenter="hoverOrder = String(event.metadata?.orderId ?? '')"
          @mouseleave="hoverOrder = ''"
          @dragover="allowMerge($event, event)"
          @drop="dropMerge($event, event)"
        >
          <strong>{{ event.title }}</strong>
          <span v-if="event.metadata?.kind !== 'rest'">{{
            event.metadata?.counterpart
          }}</span>
          <span v-if="!event.allDay"
            >{{ time(event.start) }}–{{ time(event.end) }}</span
          >
        </div>
      </template>
    </c-scheduler>
  </div>
  <c-alert
    v-if="notice"
    :status="noticeError ? 'danger' : 'warning'"
    class="workbench-notice"
    role="status"
    >{{ notice }}</c-alert
  >
  <c-space wrap class="workbench-test-controls">
    <span>联调演示</span>
    <c-select
      v-model="role"
      :options="roles"
      :disabled="saving"
      style="width: 170px"
    />
    <c-checkbox v-model="rejectSave" :disabled="saving"
      >模拟保存失败</c-checkbox
    >
    <c-checkbox v-model="conflict" :disabled="saving">模拟版本冲突</c-checkbox>
    <c-button :disabled="saving" @click="reload">重新加载</c-button>
    <c-popover trigger="click" title="最近提交的业务 DTO" placement="top">
      <c-button>提交数据</c-button>
      <template #content>
        <pre class="payload">{{ lastPayload || "尚未提交" }}</pre>
      </template>
    </c-popover>
  </c-space>
  <c-dialog
    v-model:open="editorOpen"
    :title="
      draft?.kind === 'rest'
        ? '休息安排'
        : draft?.version
          ? '出勤单详情'
          : '创建出勤单'
    "
    :footer="false"
    :closable="!saving"
    :overlay-closable="!saving"
    :esc-to-close="!saving"
    @update:open="onEditorVisibility"
  >
    <template v-if="draft">
      <c-alert v-if="editorError" status="danger">{{ editorError }}</c-alert>
      <template v-if="draft.kind === 'rest'">
        <p>{{ resource(draft.personId)?.label }}</p>
        <p>{{ format(draft.start) }} – {{ format(draft.end) }}</p>
        <c-button @click="closeEditor">关闭</c-button>
      </template>
      <c-form v-else :model="draft" layout="vertical" @submit="saveDraft()">
        <c-space
          ><c-tag>{{ statuses[draft.status] }}</c-tag
          ><span>{{ draft.id }}</span></c-space
        >
        <c-form-item label="执行人"
          ><c-select
            v-model="draft.personId"
            :options="personOptions"
            :disabled="readOnly || saving"
        /></c-form-item>
        <c-form-item label="开始"
          ><c-date
            :model-value="new Date(draft.start)"
            value-format="Date"
            :show-time="!draft.allDay"
            :disabled="readOnly || saving"
            @update:model-value="setStart"
        /></c-form-item>
        <c-form-item v-if="draft.allDay" label="结束日期（不含）"
          ><c-date
            :model-value="new Date(draft.end)"
            value-format="Date"
            :disabled="readOnly || saving"
            @update:model-value="setAllDayEnd"
        /></c-form-item>
        <p v-else>计划结束：{{ format(calculatedEnd) }}</p>
        <c-form-item label="任务">
          <div class="detail-task-list">
            <div
              v-for="(entry, index) in draftTasks"
              :key="entry.id"
              class="detail-task"
              :data-task-id="entry.id"
            >
              <WorkbenchPunches
                :data="data"
                :task="entry"
                :start="taskStart(index)"
              />
              <div>
                <c-tag>{{ entry.source }}</c-tag> ·
                {{ resource(entry.deviceId)?.label }}
              </div>
              <c-button variant="text" @click="workOrderTask = entry"
                >工单详情</c-button
              >
              <c-button
                v-if="!readOnly"
                variant="text"
                :disabled="saving"
                @click="removeDraftTask(entry.id)"
                >移出任务</c-button
              >
            </div>
            <c-select
              v-if="!readOnly"
              v-model="addTaskId"
              :options="availableTaskOptions"
              placeholder="选择同设备待办任务"
              :disabled="saving"
              @update:model-value="addTask"
            />
            <c-button
              v-if="!readOnly"
              :disabled="saving || !selectedTasks.length"
              @click="addSelected"
              >加入已勾选任务（{{ selectedTasks.length }}）</c-button
            >
          </div>
        </c-form-item>
        <template v-if="draft.status === 'closed'">
          <p v-for="record in linkedPunches" :key="record.id">
            实际：{{ format(record.start) }} – {{ format(record.end) }}
          </p>
        </template>
        <template v-if="closing && !readOnly">
          <c-divider />
          <c-form-item label="关联打卡">
            <div class="detail-task-list">
              <c-checkbox
                v-for="record in eligiblePunches"
                :key="record.id"
                :model-value="draft.punchIds.includes(record.id)"
                :disabled="saving"
                @update:model-value="togglePunch(record.id, $event)"
                >{{ format(record.start) }} – {{ time(record.end) }}</c-checkbox
              >
              <c-empty
                v-if="!eligiblePunches.length"
                description="暂无匹配打卡，可手动补录"
              />
            </div>
          </c-form-item>
          <c-checkbox v-model="manualPunch" :disabled="saving"
            >手动补录打卡</c-checkbox
          >
          <c-form-item v-if="manualPunch" label="登录"
            ><c-date
              v-model="punchStart"
              value-format="Date"
              show-time
              :disabled="saving"
          /></c-form-item>
          <c-form-item v-if="manualPunch" label="注销"
            ><c-date
              v-model="punchEnd"
              value-format="Date"
              show-time
              :disabled="saving"
          /></c-form-item>
        </template>
        <c-space wrap>
          <c-button
            v-if="!readOnly"
            html-type="submit"
            status="primary"
            :loading="saving"
            >{{ closing ? "确认关单" : "保存" }}</c-button
          >
          <c-button
            v-if="!readOnly && draft.version && !closing"
            :disabled="saving || !draft.taskIds.length"
            @click="closing = true"
            >关联打卡并关单</c-button
          >
          <c-button
            v-if="!readOnly && draft.version"
            status="danger"
            :disabled="saving"
            @click="saveDraft(true)"
            >删除出勤单</c-button
          >
          <c-button :disabled="saving" @click="closeEditor">{{
            readOnly ? "关闭" : "取消"
          }}</c-button>
        </c-space>
      </c-form>
    </template>
  </c-dialog>
  <c-dialog
    :open="!!workOrderTask"
    title="工单详情"
    :footer="false"
    @update:open="!$event && (workOrderTask = undefined)"
  >
    <template v-if="workOrderTask"
      ><h3>{{ workOrderTask.id }} · {{ workOrderTask.title }}</h3>
      <p>{{ resource(workOrderTask.deviceId)?.label }}</p>
      <p>
        {{ workOrderTask.skill }} / {{ workOrderTask.people }} 人 /
        {{ workOrderTask.minutes }} 分钟
      </p>
      <p>
        来源：{{ workOrderTask.source }}；截止：{{ workOrderTask.deadline }}
      </p></template
    >
  </c-dialog>
</template>
<script setup lang="ts">
import {
  computed,
  nextTick,
  onBeforeUnmount,
  onMounted,
  ref,
  watch,
} from "vue";
import type {
  SchedulerEvent,
  SchedulerEventTemplate,
  SchedulerEditorRequest,
  SchedulerChangeContext,
} from "../index";
import { schedulerDateKey } from "../core";
import type { TreeNodeData } from "../../tree";
import WorkbenchPunches from "./workbench-punches.vue";
import {
  createWorkbenchApi,
  createWorkbenchMock,
  copyData,
  moveWorkbenchOrder,
  orderEnd,
  orderTasks,
  pendingWorkbenchTasks,
  projectWorkbench,
  remainingDays,
  weekLabel,
  workbenchLayout,
  type WorkbenchOrder,
  type WorkbenchTask,
  type WorkbenchPunch,
  type SaveResult,
} from "./workbench-model";

const today = new Date();
const api = createWorkbenchApi(createWorkbenchMock(today));
const data = ref(api.load());
const date = ref(new Date(today));
const role = ref<"dispatcher" | "viewer">("dispatcher");
const roles = [
  { value: "dispatcher", label: "调度员（可编辑）" },
  { value: "viewer", label: "查看者（只读）" },
];
const statuses = {
  planned: "待出发",
  active: "进行中",
  submit: "待提交",
  review: "待审核",
  closed: "已完成",
};
const rejectSave = ref(false),
  conflict = ref(false),
  saving = ref(false),
  navigationOpen = ref(false),
  datePickerOpen = ref(false);
const query = ref(""),
  recent = ref<string[]>(["li", "station-a"]),
  selected = ref<string[]>(["me"]);
const selectedTasks = ref<string[]>([]),
  draggingTasks = ref<string[]>([]),
  dragDeadline = ref<string>();
const notice = ref(""),
  noticeError = ref(false),
  editorError = ref(""),
  lastPayload = ref("");
const editorOpen = ref(false),
  draft = ref<WorkbenchOrder>(),
  hoverOrder = ref("");
const closing = ref(false),
  manualPunch = ref(false),
  punchStart = ref<Date>(),
  punchEnd = ref<Date>();
const addTaskId = ref<string>(),
  workOrderTask = ref<WorkbenchTask>();
const host = ref<HTMLElement>();
const scheduler = ref();
let opener: HTMLElement | undefined;
let sequence = 0;
let staged: (() => SaveResult) | undefined;
const events = computed(() => projectWorkbench(data.value, selected.value));
const pending = computed(() => pendingWorkbenchTasks(data.value, today));
const resource = (id: unknown) =>
  data.value.resources.find((item) => item.id === id);
const task = (id: unknown) => data.value.tasks.find((item) => item.id === id);
const draftTasks = computed(() =>
  draft.value ? orderTasks(draft.value, data.value) : [],
);
const calculatedEnd = computed(() =>
  draft.value ? orderEnd(draft.value.start, draftTasks.value) : "",
);
const readOnly = computed(
  () =>
    role.value === "viewer" ||
    draft.value?.kind === "rest" ||
    draft.value?.status === "closed",
);
const activeOrder = computed(() =>
  editorOpen.value ? draft.value?.id : hoverOrder.value,
);
const personOptions = computed(() =>
  data.value.resources
    .filter((r) => r.dimensionId === "person")
    .map((r) => ({ value: r.id, label: r.label })),
);
const availableTaskOptions = computed(() =>
  pending.value
    .filter(
      (entry) =>
        !draft.value?.taskIds.includes(entry.id) &&
        (!draftTasks.value.length ||
          entry.deviceId === draftTasks.value[0].deviceId),
    )
    .map((entry) => ({
      value: entry.id,
      label: `${entry.title} · ${resource(entry.deviceId)?.label}`,
    })),
);
const eligiblePunches = computed(() =>
  data.value.punches.filter(
    (record) =>
      record.personId === draft.value?.personId &&
      record.deviceId === draftTasks.value[0]?.deviceId,
  ),
);
const linkedPunches = computed(() =>
  data.value.punches.filter((record) =>
    draft.value?.punchIds.includes(record.id),
  ),
);
const preview = computed<SchedulerEvent | undefined>(() =>
  editorOpen.value && draft.value?.version === 0
    ? {
        id: "workbench-draft",
        title:
          draftTasks.value.map((entry) => entry.title).join("、") || "新出勤单",
        start: draft.value.start,
        end: draft.value.allDay
          ? draft.value.end
          : draft.value.taskIds.length
            ? calculatedEnd.value
            : new Date(+new Date(draft.value.start) + 3600000).toISOString(),
        allDay: draft.value.allDay,
        color: resource(draft.value.personId)?.color,
        backgroundColor: resource(draft.value.personId)?.background,
      }
    : undefined,
);

interface Node extends TreeNodeData {
  resourceId?: string;
  taskId?: string;
  children?: Node[];
}
const group = (key: string, title: string, ids: string[]): Node => ({
  value: key,
  label: title,
  children: ids.map((id) => ({
    value: `${key}/${id}`,
    label: resource(id)?.label,
    resourceId: id,
  })),
});
const sourceTree = computed<Node[]>(() => [
  ...(query.value.trim()
    ? [
        group(
          "search",
          "搜索结果",
          data.value.resources
            .filter((r) =>
              `${r.label} ${r.account ?? ""}`
                .toLowerCase()
                .includes(query.value.trim().toLowerCase()),
            )
            .map((r) => r.id),
        ),
      ]
    : []),
  group("self", "自己", ["me"]),
  group("stations", "我的站", ["station-a", "station-b"]),
  group("favorites", "收藏", ["station-a", "station-c"]),
  group("recent", "最近使用", recent.value),
]);
const expandedSources = ref<Array<string | number>>([
  "self",
  "stations",
  "favorites",
  "recent",
  "search",
]);
const sourceKeys = computed(() =>
  sourceTree.value
    .flatMap((node) => node.children ?? [])
    .filter((node) => selected.value.includes(node.resourceId!))
    .map((node) => node.value!),
);
function checkSources(
  _keys: Array<string | number>,
  context: { checked?: boolean; node?: Node },
) {
  if (saving.value || !context.node) return;
  const ids = context.node.resourceId
    ? [context.node.resourceId]
    : (context.node.children ?? []).map((node) => node.resourceId!);
  selected.value = context.checked
    ? [...new Set([...selected.value, ...ids])]
    : selected.value.filter((id) => !ids.includes(id));
  if (context.checked)
    recent.value = [...new Set([...ids, ...recent.value])].slice(0, 12);
}
function toggleResource(id: string) {
  selected.value = selected.value.includes(id)
    ? selected.value.filter((value) => value !== id)
    : [...selected.value, id];
  recent.value = [...new Set([id, ...recent.value])].slice(0, 12);
}
const pendingTree = computed<Node[]>(() =>
  selected.value.flatMap((id) => {
    const owner = resource(id);
    const ids =
      owner?.dimensionId === "device"
        ? [id]
        : data.value.resources
            .filter((r) => r.managers?.includes(id))
            .map((r) => r.id);
    const tasks = pending.value.filter((entry) => ids.includes(entry.deviceId));
    return tasks.length
      ? [
          {
            value: `pending/${id}`,
            label: owner?.label,
            children: tasks.map((entry) => ({
              value: `pending/${id}/${entry.id}`,
              label: entry.title,
              taskId: entry.id,
            })),
          },
        ]
      : [];
  }),
);
const expandedPending = ref<Array<string | number>>(
  data.value.resources.map((r) => `pending/${r.id}`),
);
const pendingKeys = computed(() =>
  pendingTree.value
    .flatMap((node) => node.children ?? [])
    .filter((node) => selectedTasks.value.includes(node.taskId!))
    .map((node) => node.value!),
);
function checkPending(
  _keys: Array<string | number>,
  context: { checked?: boolean; node?: Node },
) {
  if (!context.node) return;
  const ids = context.node.taskId
    ? [context.node.taskId]
    : (context.node.children ?? []).map((node) => node.taskId!);
  const next = context.checked
    ? [...new Set([...selectedTasks.value, ...ids])]
    : selectedTasks.value.filter((id) => !ids.includes(id));
  if (new Set(next.map((id) => task(id)?.deviceId)).size > 1)
    return showNotice("请勾选同一设备的任务", true);
  selectedTasks.value = next;
}
const deadlineClass = (entry?: WorkbenchTask) => ({
  overdue: entry && remainingDays(entry, today) < 0,
  urgent:
    entry &&
    remainingDays(entry, today) >= 0 &&
    remainingDays(entry, today) <= 3,
});
const deadlineText = (entry?: WorkbenchTask) => {
  if (!entry) return "";
  const days = remainingDays(entry, today);
  return days < 0
    ? `逾期 ${-days} 天`
    : days === 0
      ? "今天截止"
      : `剩 ${days} 天`;
};
function beginPending(
  id: string,
  startDrag: (template: SchedulerEventTemplate, event: DragEvent) => void,
  event: DragEvent,
) {
  const ids = selectedTasks.value.includes(id)
    ? [...selectedTasks.value]
    : [id];
  draggingTasks.value = ids;
  dragDeadline.value = ids
    .map((key) => task(key)?.deadline ?? "")
    .filter(Boolean)
    .sort()[0];
  startDrag(
    {
      title: ids.map((key) => task(key)?.title).join("、"),
      duration: ids.reduce((sum, key) => sum + (task(key)?.minutes ?? 0), 0),
      metadata: { taskIds: ids },
    },
    event,
  );
}
function captureDrag(event: PointerEvent) {
  const node = (event.target as HTMLElement).closest<HTMLElement>(
    "[data-order-id]",
  );
  const order = data.value.orders.find(
    (item) => item.id === node?.dataset.orderId,
  );
  if (
    order &&
    order.kind === "work" &&
    order.status !== "closed" &&
    role.value !== "viewer"
  )
    dragDeadline.value = orderTasks(order, data.value)
      .map((entry) => entry.deadline)
      .sort()[0];
}
function endDrag() {
  dragDeadline.value = undefined;
  draggingTasks.value = [];
}
function allowMerge(event: DragEvent, target: SchedulerEvent) {
  if (
    draggingTasks.value.length &&
    !target.readonly &&
    !saving.value &&
    role.value !== "viewer"
  )
    event.preventDefault();
}
async function dropMerge(event: DragEvent, target: SchedulerEvent) {
  if (!draggingTasks.value.length) return;
  event.preventDefault();
  event.stopPropagation();
  const ids = [...draggingTasks.value];
  endDrag();
  const current = data.value.orders.find(
    (order) => order.id === target.metadata?.orderId,
  );
  if (!current || target.readonly || saving.value || role.value === "viewer")
    return showNotice("当前记录不可合并", true);
  const next = copyData(current);
  next.taskIds = [...new Set([...next.taskIds, ...ids])];
  if (!next.allDay)
    next.end = orderEnd(next.start, orderTasks(next, data.value));
  await persist(next);
}
function openEditor(request: SchedulerEditorRequest) {
  editorError.value = "";
  closing.value = false;
  manualPunch.value = false;
  addTaskId.value = undefined;
  opener =
    document.activeElement instanceof HTMLElement
      ? document.activeElement
      : undefined;
  if (request.action === "edit") {
    const order = data.value.orders.find(
      (item) => item.id === request.event.metadata?.orderId,
    );
    if (!order) return;
    draft.value = copyData(order);
  } else {
    const templateIds = request.event.metadata?.taskIds;
    const ids = Array.isArray(templateIds)
      ? templateIds.filter((id): id is string => typeof id === "string")
      : [...selectedTasks.value];
    const start = new Date(request.event.start ?? date.value);
    if (request.source === "toolbar") start.setHours(9, 0, 0, 0);
    else if (request.source === "cell") start.setMinutes(0, 0, 0);
    draft.value = {
      id: `ATT-${Date.now()}-${++sequence}`,
      version: 0,
      personId:
        selected.value.find((id) => resource(id)?.dimensionId === "person") ??
        "me",
      taskIds: ids,
      start: start.toISOString(),
      end: request.event.allDay
        ? new Date(request.event.end!).toISOString()
        : orderEnd(
            start.toISOString(),
            ids.map(task).filter((entry): entry is WorkbenchTask => !!entry),
          ),
      allDay: request.event.allDay,
      kind: "work",
      status: "planned",
      punchIds: [],
    };
  }
  punchStart.value = new Date(draft.value.start);
  punchEnd.value = new Date(draft.value.end);
  editorOpen.value = true;
  endDrag();
}
function setStart(value: Date | undefined) {
  if (draft.value && value && Number.isFinite(+value))
    draft.value.start = value.toISOString();
}
function setAllDayEnd(value: Date | undefined) {
  if (draft.value && value && Number.isFinite(+value))
    draft.value.end = value.toISOString();
}
function addTask(id: string) {
  if (draft.value && id)
    draft.value.taskIds = [...new Set([...draft.value.taskIds, id])];
  addTaskId.value = undefined;
}
function addSelected() {
  if (!draft.value) return;
  const ids = [...new Set([...draft.value.taskIds, ...selectedTasks.value])];
  if (new Set(ids.map((id) => task(id)?.deviceId)).size > 1) {
    editorError.value = "一张出勤单只能安排同一设备的任务";
    return;
  }
  draft.value.taskIds = ids;
}
function removeDraftTask(id: string) {
  if (draft.value)
    draft.value.taskIds = draft.value.taskIds.filter((value) => value !== id);
}
function taskStart(index: number) {
  return draft.value
    ? orderEnd(draft.value.start, draftTasks.value.slice(0, index))
    : "";
}
function togglePunch(id: string, checked: boolean) {
  if (draft.value)
    draft.value.punchIds = checked
      ? [...new Set([...draft.value.punchIds, id])]
      : draft.value.punchIds.filter((key) => key !== id);
}
function options() {
  const value = {
    role: role.value,
    fail: rejectSave.value,
    conflict: conflict.value,
  };
  conflict.value = false;
  return value;
}
function accept(result: SaveResult) {
  data.value = result.data;
  selectedTasks.value = selectedTasks.value.filter((id) =>
    pending.value.some((entry) => entry.id === id),
  );
  showNotice(result.warnings.join("；") || "已保存", false);
}
async function persist(
  value: WorkbenchOrder,
  remove = false,
  manual?: WorkbenchPunch,
) {
  saving.value = true;
  editorError.value = "";
  lastPayload.value = JSON.stringify(
    {
      operation: remove ? "remove" : "save",
      order: value,
      manualPunch: manual,
    },
    null,
    2,
  );
  try {
    accept(await api.save(value, options(), remove, manual));
    return true;
  } catch (error) {
    editorError.value = error instanceof Error ? error.message : "保存失败";
    showNotice(editorError.value, true);
    return false;
  } finally {
    saving.value = false;
  }
}
async function saveDraft(remove = false) {
  if (!draft.value || saving.value || readOnly.value) return;
  const value = copyData(draft.value);
  const dissolve = !!value.version && !value.taskIds.length;
  if (!value.allDay && value.taskIds.length)
    value.end = orderEnd(value.start, orderTasks(value, data.value));
  let manual: WorkbenchPunch | undefined;
  if (closing.value && !remove && !dissolve) {
    value.status = "closed";
    if (manualPunch.value) {
      if (
        !punchStart.value ||
        !punchEnd.value ||
        !Number.isFinite(+punchStart.value) ||
        !Number.isFinite(+punchEnd.value)
      ) {
        editorError.value = "请填写登录和注销时间";
        return;
      }
      manual = {
        id: `punch-${Date.now()}-${++sequence}`,
        personId: value.personId,
        deviceId: draftTasks.value[0]?.deviceId ?? "",
        start: punchStart.value.toISOString(),
        end: punchEnd.value.toISOString(),
      };
      value.punchIds = [...value.punchIds, manual.id];
    }
  }
  if (await persist(value, remove || dissolve, manual)) closeEditor();
}
async function prepareMove(context: SchedulerChangeContext) {
  if (!context.previous || context.type !== "move")
    throw new Error("请在出勤单详情中修改");
  if (context.event.allDay !== context.previous.allDay)
    throw new Error("请在详情中调整全天安排");
  const next = moveWorkbenchOrder(data.value, context.event, context.previous);
  lastPayload.value = JSON.stringify(
    { operation: "move", order: next },
    null,
    2,
  );
  staged = await api.prepare(next, options());
  return true;
}
function finishMove() {
  try {
    if (staged) accept(staged());
  } catch (error) {
    moveError(error);
  } finally {
    staged = undefined;
    endDrag();
  }
}
function moveError(error: unknown) {
  staged = undefined;
  showNotice(error instanceof Error ? error.message : "保存失败", true);
  endDrag();
}
function showNotice(message: string, error: boolean) {
  notice.value = message;
  noticeError.value = error;
}
function reload() {
  data.value = api.load();
  if (draft.value?.version)
    draft.value = copyData(
      data.value.orders.find((item) => item.id === draft.value?.id) ??
        draft.value,
    );
  editorError.value = "";
  showNotice("已重新加载", false);
}
async function onEditorVisibility(open: boolean) {
  if (open) return;
  hoverOrder.value = "";
  await nextTick();
  if (opener?.isConnected) opener.focus({ preventScroll: true });
}
function closeEditor() {
  editorOpen.value = false;
  void onEditorVisibility(false);
}
async function chooseDate(value: Date | undefined) {
  if (value && Number.isFinite(+value)) date.value = value;
  datePickerOpen.value = false;
}
async function goToday() {
  date.value = new Date();
  await nextTick();
  const container =
    host.value?.querySelector<HTMLElement>(".c-scheduler__main");
  const heading = [
    ...(host.value?.querySelectorAll<HTMLElement>(
      "[data-scheduler-heading-date]",
    ) ?? []),
  ].find(
    (element) =>
      schedulerDateKey(element.dataset.schedulerHeadingDate!) ===
      schedulerDateKey(new Date()),
  );
  const cell = host.value?.querySelector<HTMLElement>(
    ".c-scheduler__time-cell",
  );
  if (container && cell) {
    container.scrollTop = (cell.getBoundingClientRect().height || 36) * 7;
    if (heading) container.scrollLeft = Math.max(0, heading.offsetLeft - 64);
  }
}
const time = (value: SchedulerEvent["start"]) =>
  value == null
    ? ""
    : new Date(value).toLocaleTimeString("zh-CN", {
        hour: "2-digit",
        minute: "2-digit",
        hour12: false,
      });
const format = (value: string) =>
  new Date(value).toLocaleString("zh-CN", {
    month: "numeric",
    day: "numeric",
    hour: "2-digit",
    minute: "2-digit",
    hour12: false,
  });
const cancelWithEscape = (event: KeyboardEvent) => {
  if (event.key === "Escape") endDrag();
};
onMounted(() => {
  window.addEventListener("pointerup", endDrag);
  window.addEventListener("pointercancel", endDrag);
  window.addEventListener("blur", endDrag);
  window.addEventListener("keydown", cancelWithEscape);
});
onBeforeUnmount(() => {
  window.removeEventListener("pointerup", endDrag);
  window.removeEventListener("pointercancel", endDrag);
  window.removeEventListener("blur", endDrag);
  window.removeEventListener("keydown", cancelWithEscape);
});
watch(query, () => {
  if (!expandedSources.value.includes("search"))
    expandedSources.value.push("search");
});
</script>
<style scoped>
.workbench-shell {
  display: flex;
  min-width: 0;
}
.workbench-nav {
  flex: 0 0 88px;
  display: flex;
  flex-direction: column;
  border: 1px solid var(--c-color-border);
}
.task-calendar-workbench {
  min-width: 0;
  flex: 1;
  --c-scheduler-sidebar-width: 420px;
  --c-scheduler-max-height: 650px;
  --c-scheduler-min-height: 650px;
  --c-scheduler-column-min-width: 110px;
  --c-scheduler-gap: 8px;
  --c-scheduler-padding: 10px;
}
.task-calendar-workbench :deep(.c-scheduler__sidebar) {
  padding: 0;
  overflow: hidden;
}
.workbench-panels {
  display: grid;
  grid-template-columns: 190px minmax(0, 1fr);
  grid-template-rows: minmax(0, 1fr);
  height: 650px;
  min-height: 0;
}
.source-panel,
.pending-panel {
  min-width: 0;
  min-height: 0;
  display: flex;
  flex-direction: column;
  padding: 12px;
  gap: 12px;
}
.source-panel {
  border-right: 1px solid var(--c-color-border);
}
.panel-scroll {
  min-height: 0;
  flex: 1;
  overflow-y: auto;
  overflow-x: hidden;
}
.source-object {
  color: var(--c-color-text-1);
  position: relative;
  display: block;
  white-space: nowrap;
}
.source-object small {
  display: block;
  font-size: 11px;
  color: var(--c-color-text-3);
}
.quick-actions {
  display: none;
  position: absolute;
  right: 0;
  bottom: 100%;
  z-index: 5;
  background: var(--c-color-bg-2);
  box-shadow: 0 2px 8px #0002;
}
.source-object:hover .quick-actions,
.source-object:focus-within .quick-actions,
.source-scroll :deep(.c-tree-node:focus-within) .quick-actions {
  display: flex;
}
.source-scroll :deep(.c-tree-node:has([data-owner="me"])) {
  --c-checkbox-control-color-checked: #466caa;
}
.source-scroll :deep(.c-tree-node:has([data-owner="li"])) {
  --c-checkbox-control-color-checked: #ad813c;
}
.source-scroll :deep(.c-tree-node:has([data-owner="zhang"])) {
  --c-checkbox-control-color-checked: #4b8d70;
}
.source-scroll :deep(.c-tree-node:has([data-owner="station-a"])) {
  --c-checkbox-control-color-checked: #8670ac;
}
.source-scroll :deep(.c-tree-node:has([data-owner="station-b"])) {
  --c-checkbox-control-color-checked: #a1657e;
}
.source-scroll :deep(.c-tree-node:has([data-owner="station-c"])) {
  --c-checkbox-control-color-checked: #458c98;
}
.pending-task {
  color: var(--c-color-text-2);
  display: flex;
  flex-direction: column;
  white-space: normal;
  font-size: 12px;
  line-height: 1.5;
  padding: 8px 0;
  cursor: grab;
}
.pending-task.overdue {
  color: #b8434b;
}
.pending-task.urgent {
  color: #a7782d;
}
.task-card {
  color: var(--c-scheduler-event-color);
  width: 100%;
  height: 100%;
  min-height: 0;
  display: flex;
  flex-direction: column;
  overflow: hidden;
  text-align: left;
}
.task-card > * {
  white-space: nowrap;
  overflow: hidden;
  text-overflow: clip;
  flex-shrink: 0;
  line-height: 16px;
}
.task-card.closed::after {
  content: "";
  position: absolute;
  inset: 0;
  background: #ffffff66;
  pointer-events: none;
}
.task-calendar-workbench :deep(.c-scheduler__event) {
  border: 1px solid var(--c-scheduler-event-color);
  border-left-width: 4px;
  color: var(--c-scheduler-event-color);
  margin-bottom: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event--static) {
  border-left-width: 1px;
}
.task-calendar-workbench :deep(.c-scheduler__positioned-event) {
  padding-top: 0;
  padding-bottom: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has([data-edge="first"])) {
  border-bottom: 0;
  border-bottom-left-radius: 0;
  border-bottom-right-radius: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has([data-edge="middle"])) {
  border-block: 0;
  border-radius: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has([data-edge="last"])) {
  border-top: 0;
  border-top-left-radius: 0;
  border-top-right-radius: 0;
}
.task-calendar-workbench :deep(.c-scheduler__event:has(.linked)) {
  box-shadow: inset 0 0 0 2px currentColor;
}
.task-calendar-workbench :deep(.c-scheduler__event:has(.rest)) {
  border-style: dashed;
}
.task-calendar-workbench :deep(.c-scheduler__event-button) {
  height: 100%;
  align-items: flex-start;
  padding-block: 0;
}
.deadline-mask {
  position: absolute;
  inset: 0;
  background: #66708526;
  pointer-events: none;
}
.detail-task-list {
  display: flex;
  flex-direction: column;
  gap: 12px;
  width: 100%;
}
.detail-task {
  padding: 8px 0;
  border-bottom: 1px solid var(--c-color-border);
}
.workbench-test-controls,
.workbench-notice {
  margin-top: 12px;
}
.payload {
  max-width: 480px;
  max-height: 300px;
  overflow: auto;
}

.task-calendar-workbench :deep(.c-scheduler__toolbar) {
  padding: 14px 16px;
}
.task-calendar-workbench :deep(.c-scheduler__toolbar .c-button) {
  box-shadow: none;
}
.task-calendar-workbench :deep(.c-scheduler__time-heading) {
  font-weight: 500;
}
.panel-title {
  font-size: 13px;
  font-weight: 600;
  color: var(--c-color-text-1);
}
.panel-scroll {
  scrollbar-width: thin;
  scrollbar-color: var(--c-color-border) transparent;
}
.source-scroll :deep(.c-tree-node-title-text),
.pending-panel :deep(.c-tree-node-title-text) {
  color: var(--c-color-text-2);
}
.pending-task {
  border-bottom: 1px solid var(--c-color-border);
}
.pending-task > small {
  color: var(--c-color-text-3);
}
.pending-task:active {
  cursor: grabbing;
}
.task-card > :first-child {
  font-weight: 600;
}
.task-card > :not(:first-child) {
  opacity: 0.85;
}
.quick-actions {
  border: 1px solid var(--c-color-border);
  border-radius: 6px;
  padding: 4px;
}
.workbench-test-controls {
  padding: 12px 16px;
  background: var(--c-color-fill-1);
  border-radius: 8px;
}
</style>
```

## API

### `<c-scheduler>` Props

| Prop | Description | Type | Default |
| -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------- | ------------ |
| model-value | Schedule data; supports v-model and becomes controlled when provided | SchedulerEvent[] | — |
| preview-event | Unsaved new-event placeholders; visual only | SchedulerEvent | — |
| default-value | Initial uncontrolled data | SchedulerEvent[] | [] |
| mode | Current view; supports v-model:mode | SchedulerMode | — |
| default-mode | Default uncontrolled view | SchedulerMode | week |
| date | Navigation date; supports v-model:date | Date / string / number | — |
| default-date | Initial navigation date | Date / string / number | Current date |
| resource-dimensions | Dimension definitions: `{ id, label }[]` | SchedulerResourceDimension[] | [] |
| resource-filters | Combined resource-dimension filters; supports v-model:resource-filters | SchedulerResourceFilters | — |
| default-resource-filters | Initial uncontrolled filters | SchedulerResourceFilters | {} |
| resource-dimension | Resource row/column dimension; an empty string shows all | string | — |
| default-resource-dimension | Initial uncontrolled display dimension | string | '' |
| resources | Currently visible resource rows/columns and local options; a complete directory is unnecessary | SchedulerResource[] | [] |
| resource-label | Resource field name, such as equipment or meeting room | string | Localized resource label |
| request-resources | Query resource candidates by keyword and cursor | SchedulerRequestResources | — |
| resolve-resources | Batch-resolve resource names by ID | SchedulerResolveResources | — |
| modes | Views available for switching | SchedulerMode[] | All six views |
| first-day-of-week | Week start: 0 Sunday to 6 Saturday | number | 1 |
| start-hour | Time-grid start hour, 0–23 | number | 8 |
| end-hour | Time-grid end hour; greater than start and at most 24 | number | 20 |
| initial-scroll-minute | Minute of day initially scrolled into view; subsequent renders retain user scroll position | number | — |
| step | Grid/snap interval in minutes; a positive integer dividing 60 | number | 30 |
| slot-duration | Grid interval in minutes; positive integer | number | step |
| snap-duration | Pointer snap interval in minutes; positive integer | number | step |
| default-duration | Default duration for click-to-create, in positive integer minutes | number | step |
| drag-to-create | Drag-select empty slots in day/week/resource-day views | boolean | false |
| month-event-limit | Maximum directly displayed events per month-view day; extra events use Popover | number | 3 |
| overlap-event-limit | Maximum directly displayed events per overlapping time-grid group; extra events use Popover | number | — |
| zoom / default-zoom | Timeline zoom, 0.5–4 | number | 1 |
| show-date-header | Tiered timeline date headers | boolean | true |
| show-assignment-details | Edit resource occupancy and roles | boolean | false |
| show-resource-load | Resource peak load, capacity and utilization within the range | boolean | false |
| rule-policy | allow/warn/block policies for capacity/unavailable/conflict | SchedulerRulePolicy | {}（block） |
| dependencies | Task dependencies | SchedulerDependency[] | [] |
| event-layout | Time-grid layout: stack / columns / geometry callback. Week defaults to stack; others to columns | SchedulerEventLayout | Depends on the view |
| readonly | Viewing/navigation allowed, editing blocked | boolean | false |
| disabled | Disable interaction | boolean | false |
| hidden-days | Hide specified weekdays in week/month/agenda, 0–6; cannot hide every day | number[] | [] |
| show-now-indicator | Show the current local-time line in day/week/resource-day views | boolean | false |
| show-sidebar | Show filters and the unscheduled list | boolean | true |
| allow-overlap | Allow overlapping times for the same resource | boolean | true |
| editable | Enable the built-in editor; false delegates through editor-request | boolean | true |
| before-change | Return false to cancel; supports asynchronous interception and save APIs | SchedulerBeforeChange / SchedulerBeforeChange[] | — |

mode is `day | week | month | agenda | resource-day | resource-timeline`. Agenda/resource-timeline navigate by week. Events outside time-grid hours remain visible in month/agenda/timeline.

With controlled model-value, the component proposes data and waits for parent acceptance before changing the UI; it does not move first and roll back after request failure. Input arrays/objects are not mutated. before-change receives detached copies; editing them does not alter the committed proposal.

### `<c-scheduler>` Events

| Event | Description | Arguments |
| ------------------------ | ---------------------------------------------------------------- | ------------------------------------ |
| update:model-value | Proposes a new main value | SchedulerEvent[] |
| update:resourceFilters | Combined resource-filter changes; controlled mode waits for parent acceptance | SchedulerResourceFilters |
| update:resourceDimension | Resource row/column display-dimension changes | string |
| update:mode | View changes | SchedulerMode |
| update:zoom | Timeline zoom changes | number |
| rule-warning | Advisory rule issues on an accepted proposal | SchedulerError[] |
| update:date | Navigation-date changes | Date |
| change | Validation/hooks complete; controlled mode has proposed a validated value | value, SchedulerChangeContext |
| change-error | Validation, conflict, save or stale-proposal errors | error, SchedulerChange |
| event-click | Activate an event with a copy; stacked events support click/Enter too, while multiselection does not activate | SchedulerEvent |
| cell-click | Click an empty time slot | SchedulerCell |
| range-change | Initial and actual visible-date-range changes | SchedulerRange |
| resource-error | Resource search/display resolution fails without changing schedule data | error, SchedulerResourceErrorContext |
| editor-request | Only with editable=false: request external creation or viewing/editing | SchedulerEditorRequest |

### `<c-scheduler>` Slots

| Slot | Arguments | Description |
| ----------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| event | { event } | Event-button content |
| sidebar | { startDrag, cancelDrag, disabled, unscheduled } | Replace the entire sidebar, e.g. with a resource tree/task pool; hidden when show-sidebar=false |
| sidebar-extra | { startDrag, cancelDrag, disabled } | Content above the default sidebar; startDrag(template: SchedulerEventTemplate, event: DragEvent). Hidden when show-sidebar=false |
| resource-header | { resource?, resources?, date } | Resource or date header |
| toolbar | { date, mode, navigate, create } | Replace the toolbar; navigate(-1/1) changes range, create() follows toolbar creation |
| column-background | { date, resource? } | Background for day/week/resource-day columns without intercepting pointers; useful for soft warnings/heatmaps |
| toolbar-extra | { date, mode } | Toolbar extension |
| editor | SchedulerEditorSlotProps | Custom drawer content: action, event, error, errorMessage, save, remove, close, readonly, pending |
| empty | — | Empty state |

### Instance methods

| Method | Description |
| ---------------------------------- | -------------------------------------------------------------- |
| `change(change): Promise<boolean>` | Execute create/update/remove/move/resize with all validation/hooks |
| duplicateEvent(id: string) | Open a separately copied draft or request custom creation; returns boolean without automatically saving |
| goToDate(date: Date) | Navigate to a date; respects controlled models |

## Type definitions

```ts
import type {
  SchedulerProps,
  SchedulerInstance,
  SchedulerMode,
  SchedulerEvent,
  SchedulerResource,
  SchedulerChange,
  SchedulerChangeContext,
  SchedulerBeforeChange,
  SchedulerEventTemplate,
  SchedulerRequestResources,
  SchedulerResolveResources,
  SchedulerResourcePage,
  SchedulerResourceQuery,
  SchedulerResourceErrorContext,
  SchedulerEditorRequest,
  SchedulerEditorAction,
  SchedulerEditorSlotProps,
} from "@cedar-design/ui";

interface SchedulerEvent {
  id: string;
  title: string;
  start?: Date | string | number;
  end?: Date | string | number;
  allDay?: boolean;
  resourceIds?: string[];
  resourceDetails?: Record<string, { units?: number; role?: string }>;
  milestone?: boolean;
  layoutGroupId?: string;
  description?: string;
  color?: string;
  accentColor?: string;
  backgroundColor?: string;
  backgroundPattern?: "solid" | "diagonal-stripes" | "dots" | "crosshatch";
  metadata?: Record<string, unknown>;
  readonly?: boolean;
  resizable?: boolean; // false disables time-grid resizing while preserving moving/viewing
}
type SchedulerEventTemplate = Pick<
  SchedulerEvent,
  | "title"
  | "description"
  | "color"
  | "accentColor"
  | "backgroundColor"
  | "backgroundPattern"
  | "metadata"
  | "resourceIds"
> & {
  duration?: number; // positive minutes; defaults to default-duration or step
};
interface SchedulerResource {
  id: string;
  dimensionId?: string;
  label: string;
  color?: string;
  disabled?: boolean;
  capacity?: number; // nonnegative safe integer; omission leaves concurrent event counts unlimited
}
interface SchedulerResourceQuery {
  dimensionId?: string;
  query: string;
  cursor?: string;
  signal: AbortSignal;
}
interface SchedulerResourcePage {
  items: SchedulerResource[];
  nextCursor?: string;
}
type SchedulerRequestResources = (
  query: SchedulerResourceQuery,
) => SchedulerResourcePage | Promise<SchedulerResourcePage>;
type SchedulerResolveResources = (
  ids: string[],
  context: { signal: AbortSignal },
) => SchedulerResource[] | Promise<SchedulerResource[]>;
type SchedulerResourceErrorContext =
  | { type: "search"; query: string; cursor?: string }
  | { type: "resolve"; ids: string[] };

type SchedulerEditorAction = "create" | "edit";
type SchedulerEditorRequest = { event: SchedulerEvent; readonly: boolean } & (
  | { action: "create"; source: "toolbar" | "cell" | "drop" }
  | { action: "edit"; source: "event" }
);
interface SchedulerEditorSlotProps {
  action: SchedulerEditorAction;
  event: SchedulerEvent;
  error?: SchedulerError;
  errorMessage?: string;
  readonly: boolean;
  pending: boolean;
  save: (event?: SchedulerEvent) => void;
  remove: () => void;
  close: () => void;
}
```

Every event id must be unique. Omitting both start/end means unscheduled; otherwise end must follow start, except timed milestones requiring start=end. All intervals are `[start, end)`, so adjacent intervals do not conflict. allDay uses `YYYY-MM-DD` strings with an exclusive end, e.g. September 9–10 for a one-day event.

Display currently uses the runtime's local zone; timed events should use ISO instants. Arbitrary IANA display zones are not promised. Cross-zone RRULE, ICS and version synchronization come from separate adapters; business code must connect real external accounts. Configure virtual resource rows with virtual-list-props. See examples for local undo and range-based remote loading. Pointer drag supports moving/resizing; Escape cancels. Keyboard/touch users can also schedule/assign through the editor. Disabled resource options prevent new assignments/drops while existing associations may remain or be removed.

## Independent core

`src/scheduler/core` imports no Vue, DOM or external calendar library. It can be tested independently and later extracted as scheduler-core. The published pure-core subentry avoids importing component runtime:

```ts
import {
  applySchedulerChange,
  getSchedulerConflicts,
  layoutSchedulerEvents,
} from "@cedar-design/ui/scheduler/core";
```

Other date/timeline utilities are exported from this entry too. The core computes and applies immutable changes; it does not handle networking, authorization or database transactions.

### Style variables

All variables are defined in `style/token.less` and support light/dark theme overrides.

| Variable | Default |
| -------------------------------- | ------------------------------ |
| --c-scheduler-background | var(--c-color-bg-2) |
| --c-scheduler-color | var(--c-color-text-1) |
| --c-scheduler-border-color | var(--c-color-border) |
| --c-scheduler-sidebar-width | 220px |
| --c-scheduler-slot-height | 36px |
| --c-scheduler-column-min-width | 120px |
| --c-scheduler-max-height | 720px |
| --c-scheduler-event-color | rgb(var(--c-primary-6)) |
| --c-scheduler-event-accent-color | var(--c-scheduler-event-color) |
| --c-scheduler-event-background | var(--c-color-primary-light-1) |
| --c-scheduler-lane-height | 38px |
| --c-scheduler-ghost-opacity | 0.75 |
| --c-scheduler-preview-opacity | 0.85 |
| --c-scheduler-preview-duration | 100ms |
| --c-scheduler-ghost-z-index | 2000 |

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading.

---

Document: llms/en-US/components/scrollbar.md

<!-- Source: src/scrollbar/README.en-US.md; locale: en-US; page: /en/components/scrollbar/ -->

# Scrollbar

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/scrollbar/__demos__/basic.vue

```vue
<template>
  <c-scrollbar style="height: 200px; overflow: auto">
    <div style="height: 2000px; width: 2000px; background-color: var(--c-color-primary-light-1)">Content</div>
  </c-scrollbar>
</template>

<script lang="ts" setup>
</script>
```

## Appearance and states

### Type

- `type`: Type

Example source: src/scrollbar/__demos__/type.vue

```vue
<template>
  <c-scrollbar type="track" style="height: 200px; overflow: auto">
    <div style="height: 2000px; width: 2000px; background-color: var(--color-primary-light-4)">Content</div>
  </c-scrollbar>
</template>

<script lang="ts" setup>
</script>
```

## Lifecycle and edge cases

### Thumb Lifecycle

Example source: src/scrollbar/__demos__/thumb-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref(true)
const mounted = ref(true)
const scrolls = ref(0)
</script>
<template>
  <div>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <c-button @mouseenter="active = false">Hover while dragging to deactivate / 拖动时移入停用</c-button>
    <p>Scroll notifications / 滚动通知: {{ scrolls }}. Drag a thumb, release, open context menu or blur the window; later movement must not replay. Fresh activation requires a fresh press.</p>
    <KeepAlive v-if="mounted">
      <c-scrollbar v-if="active" style="height: 160px; width: 260px; overflow: auto" @scroll="scrolls++">
        <div style="height: 800px; width: 700px">Drag the horizontal/vertical thumb / 拖动横向或纵向滑块</div>
      </c-scrollbar>
    </KeepAlive>
  </div>
</template>
```

### Lifecycle

Example source: src/scrollbar/__demos__/lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { ScrollbarInstance } from '@cedar-design/ui'
const active = ref(true)
const mounted = ref(true)
const bar = ref<ScrollbarInstance>()
let retained: ScrollbarInstance | undefined
function remember() { retained = bar.value }
function scrollRetained() { retained?.scrollTo(100, 100) }
</script>
<template>
  <div>
    <c-button @click="remember">Remember handle / 保留句柄</c-button>
    <c-button @click="active = !active">Activate / 停用与激活</c-button>
    <c-button @click="mounted = !mounted">Mount / 卸载与挂载</c-button>
    <c-button @click="scrollRetained">Retained scroll / 调用保留滚动</c-button>
    <c-button @click="bar?.scrollTo(0, 0)">Origin / 回到原点</c-button>
    <p>Remember the handle, deactivate or unmount, then call it. It must be inert. Activate for fresh commands; zero coordinates must work.</p>
    <KeepAlive v-if="mounted">
      <c-scrollbar v-if="active" ref="bar" style="height: 160px; width: 260px; overflow: auto">
        <div style="height: 800px; width: 700px">Scrollable content / 可滚动内容</div>
      </c-scrollbar>
    </KeepAlive>
  </div>
</template>
```

## API

### `<scrollbar>` Props

| Parameter | Description | Type | Default |
| ----------- | ---------- | ----------------------- | :-------: |
| type | Type | `'track' \| 'embed'` | `'embed'` |
| outer-class | Outer class | `string\|object\|array` | `-` |
| outer-style | Outer style | `StyleValue` | `-` |

### `<scrollbar>` Events

| Event | Description | Arguments |
| ------ | ---------- | ---- |
| scroll | Emitted on scrolling | - |

### `<scrollbar>` Methods

| Method | Description | Arguments | Returns | Version |
| ---------- | -------- | ---------------------------------------------------------------- | ------ | :----- |
| scrollTo | Scroll | options: `number \| {left?: number;top?: number}`<br>y: `number` | - |  |
| scrollTop | Vertical scroll | top: `number` | - | 2.40.0 |
| scrollLeft | Horizontal scroll | left: `number` | - | 2.40.0 |

### Type definitions

The component exports the following types

```ts
import type { ScrollbarBoxInstance } from '@cedar-design/ui'
```

---

Document: llms/en-US/components/search.md

<!-- Source: src/search/README.en-US.md; locale: en-US; page: /en/components/search/ -->

# Search

Search submits keywords and controlled field models. The application handles requests and loading.

## Basic examples

### Basic usage

Enter a keyword and press Enter. The first example has one input and one submitted value.

Example source: src/search/__demos__/en-US/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { SearchResult } from '@cedar-design/ui'
const keyword = ref('')
const submitted = ref('')
function onSearch(result: SearchResult) { submitted.value = result.modelValue }
</script>
<template>
  <c-search v-model="keyword" placeholder="Enter keywords and press Enter" @search="onSearch" />
  <p role="status">Submitted: {{ submitted || 'No search yet' }}</p>
</template>
```

## Data and options

### Search button

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                  | Related examples                               |
| ----------------- | ---------------------------------------- | ---------------------------------------------- |
| `placeholder`     | Placeholder                              | Search button, With Fields, Controlled history |
| `search-button`   | Whether to show the shared search button | Search button, With Fields                     |
| `recent-searches` | Controlled search history                | With Fields, Controlled history                |
| `button-text`     | Shared search button text                | Search button                                  |
| `fields`          | Search field options                     | With Fields                                    |
| `select-style`    | Field selector style                     | With Fields                                    |

<!-- demo-config-notes:end -->

Example source: src/search/__demos__/en-US/search-button.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { SearchResult } from '@cedar-design/ui'
const keyword = ref('')
const submitted = ref('')
function onSearch(result: SearchResult) { submitted.value = result.modelValue }
</script>
<template>
  <c-search v-model="keyword" search-button button-text="Search" placeholder="Click Search to submit" @search="onSearch" />
  <p role="status">Submitted: {{ submitted || 'No search yet' }}</p>
</template>
```

### With Fields

Example source: src/search/__demos__/with-fields.vue

```vue
<template>
  <c-space direction="column">
    <c-search
      v-model="keyword"
      v-model:model-field="modelField"
      v-model:model="model"
      :style="inputStyle"
      :fields="fields"
      :recent-searches="recentSearches"
      :select-style="{ minWidth: '140px' }"
      default-field="name"
      placeholder="请输入搜索内容"
      search-button
      @change="handleChange"
      @search="handleSearch"
    />
    <c-button @click="resetModel">Reset Model</c-button>
    <div>最近提交：{{ latestChange || "-" }}</div>
    <pre v-if="latestResult">{{ JSON.stringify(latestResult, null, 2) }}</pre>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";
import type { SearchResult, SearchField } from "@cedar-design/ui";

const inputStyle = { width: "420px" };
const keyword = ref("");
const modelField = ref("name");
const model = ref<Record<string, unknown>>({});
const recentSearches = ref<string[]>(["设备 A", "设备 B", "设备 C"]);
const latestChange = ref("");
const latestResult = ref<SearchResult>();

const fields: SearchField[] = [
  {
    value: "id",
    label: "设备 ID",
    placeholder: "请输入设备 ID",
  },
  {
    value: "name",
    label: "设备名称",
    placeholder: "请输入设备名称",
  },
  {
    value: "desc",
    label: "设备描述",
    placeholder: "请输入设备描述",
  },
];

function handleSearch(data: SearchResult) {
  recentSearches.value = data.recentSearches;
  latestResult.value = data;
}

function handleChange(value: string) {
  latestChange.value = value;
}

function resetModel() {
  model.value = {};
  keyword.value = "";
}
</script>
```

### Controlled history

Example source: src/search/__demos__/local-storage.vue

```vue
<template>
  <c-space direction="column">
    <c-search
      v-model="keyword"
      :style="inputStyle"
      placeholder="业务侧使用 localStorage 保存搜索历史"
      :recent-searches="recentSearches"
      @search="handleSearch"
    />
    <c-button @click="clearRecentSearches">Clear History</c-button>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";
import type { SearchResult } from "@cedar-design/ui";

const inputStyle = { width: "360px" };
const storageKey = "__cedar_search_history__";

const keyword = ref("");
const recentSearches = ref<string[]>(loadRecentSearches());

function loadRecentSearches() {
  try {
    return JSON.parse(localStorage.getItem(storageKey) || "[]");
  } catch {
    return [];
  }
}

function saveRecentSearches(list: string[]) {
  localStorage.setItem(storageKey, JSON.stringify(list));
  recentSearches.value = list;
}

function handleSearch(data: SearchResult) {
  saveRecentSearches(data.recentSearches);
}

function clearRecentSearches() {
  saveRecentSearches([]);
}
</script>
```

## Customization and slots

### History presentation and slots

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                                                                 | Related examples               |
| ----------------- | --------------------------------------------------------------------------------------- | ------------------------------ |
| `edit-mode`       | Search editing mode: direct searches in place; popup opens the search editor in a popup | History presentation and slots |
| `recent-searches` | Controlled search history                                                               | History presentation and slots |
| `label`           | Text to the left of the search input                                                    | History presentation and slots |
| `placeholder`     | Placeholder                                                                             | History presentation and slots |
| `clearable`       | Whether the value can be cleared                                                        | History presentation and slots |
| `show-action`     | Whether to show the mobile action                                                       | History presentation and slots |

<!-- demo-config-notes:end -->

Example source: src/search/__demos__/en-US/presentation.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const keyword = ref("");
const popup = ref(false);
const history = ref(["Project A", "Device B"]);
const lastAction = ref("No search yet");
</script>
<template>
  <div class="search-demo">
    <c-checkbox v-model="popup"
      >popup fullscreen search (uncheck for inline)</c-checkbox
    >
    <c-search
      v-model="keyword"
      :edit-mode="popup ? 'popup' : 'direct'"
      :recent-searches="history"
      label="Resource"
      placeholder="Enter resource name"
      clearable
      show-action
      action-text="Cancel"
      @cancel="lastAction = 'Cancelled'"
      @search="
        (result) => {
          history = result.recentSearches;
          lastAction = result.modelValue;
        }
      "
    />
    <c-search
      v-model="keyword"
      search-button
      :button-props="{ variant: 'outline' }"
      placeholder="Custom button slots"
      @search="(result) => (lastAction = result.modelValue)"
    >
      <template #button-icon><span aria-hidden="true">⌕</span></template>
      <template #button-default>Find</template>
    </c-search>
    <div>Last action：{{ lastAction }}</div>
  </div>
</template>
<style scoped>
.search-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 100%;
}
</style>
```

### Functional playground

## Interaction and control

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                            | Related examples           |
| --------------- | -------------------------------------------------- | -------------------------- |
| `placeholder`   | Placeholder                                        | State Lab, Loading         |
| `loading`       | Loading state; submission is blocked while loading | State Lab, Loading         |
| `readonly`      | Whether readonly                                   | State Lab, Loading         |
| `search-button` | Whether to show the shared search button           | Loading, Controlled Fields |
| `disabled`      | Whether disabled                                   | State Lab                  |
| `default-value` | Uncontrolled default keyword                       | Loading                    |

<!-- demo-config-notes:end -->

Example source: src/search/__demos__/state-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
const inputStyle = { width: "360px" };
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-search
      :style="inputStyle"
      placeholder="加载中"
      loading
      v-bind="__demoState"
    />
  </c-space>
</template>
```

### Loading

- `readonly`: Displays the current value without allowing edits.

Example source: src/search/__demos__/loading.vue

```vue
<template>
  <c-space direction="column">
    <c-search :style="inputStyle" placeholder="加载中" loading />
    <c-search
      :style="inputStyle"
      placeholder="按钮加载中"
      search-button
      loading
    />
    <c-search :style="inputStyle" default-value="只读内容" readonly />
  </c-space>
</template>

<script lang="ts" setup>
const inputStyle = { width: "360px" };
</script>
```

### Controlled Fields

Example source: src/search/__demos__/en-US/controlled-fields.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { SearchResult } from "@cedar-design/ui";

const field = ref("name");
const model = ref<Record<string, unknown>>({
  name: "Device A",
  tenant: "demo",
});
const accepted = ref(true);
const history = ref(["Device A", "42"]);
const result = ref<SearchResult>();
const fields = [
  { value: "name", label: "Device name", placeholder: "Enter name" },
  { value: "id", label: "Device ID", placeholder: "Enter ID" },
];
function updateModel(proposal: Record<string, unknown>) {
  if (accepted.value) model.value = proposal;
}
function updateField(proposal: string) {
  if (accepted.value) field.value = proposal;
}
function search(next: SearchResult) {
  result.value = next;
  history.value = next.recentSearches;
}
</script>
<template>
  <div class="search-demo">
    <c-checkbox v-model="accepted"
      >Accept updates (uncheck to demonstrate controlled rejection)</c-checkbox
    >
    <c-search
      :model="model"
      :model-field="field"
      :fields="fields"
      :recent-searches="history"
      edit-mode="direct"
      search-button
      button-text="Search"
      clearable
      @update:model="updateModel"
      @update:model-field="updateField"
      @search="search"
    />
    <c-button
      variant="text"
      @click="model = { name: 'External value', tenant: 'demo' }"
      >Replace model externally</c-button
    >
    <div>Accepted model：{{ model }}</div>
    <pre v-if="result">{{ JSON.stringify(result, null, 2) }}</pre>
  </div>
</template>
<style scoped>
.search-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 100%;
}
.search-demo pre {
  white-space: pre-wrap;
  overflow-wrap: anywhere;
}
</style>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Arguments                  | Description                                                                             | Type                      | Default                               |
| -------------------------- | --------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------- |
| `v-model`                  | Search keyword                                                                          | _string_                  | `-`                                   |
| `default-value`            | Uncontrolled default keyword                                                            | _string_                  | `''`                                  |
| `v-model:model-field`      | Current search field                                                                    | _string_                  | `-`                                   |
| `default-field`            | Uncontrolled default field                                                              | _string_                  | `-`                                   |
| `v-model:model`            | Object updated by field in field-search mode                                            | _Record<string, unknown>_ | `-`                                   |
| `fields`                   | Search field options                                                                    | _SearchField[]_           | `[]`                                  |
| `select-style`             | Field selector style                                                                    | _StyleValue_              | `-`                                   |
| `recent-searches`          | Controlled search history                                                               | _string[]_                | `[]`                                  |
| `max-search-history-count` | Maximum items in the next history list                                                  | _number_                  | `5`                                   |
| `edit-mode`                | Search editing mode: direct searches in place; popup opens the search editor in a popup | `'direct' \| 'popup'`     | `'direct'`                            |
| `search-button`            | Whether to show the shared search button                                                | _boolean_                 | `false`                               |
| `button-text`              | Shared search button text                                                               | _string_                  | `-`                                   |
| `button-props`             | Shared search button props                                                              | _ButtonProps_             | `-`                                   |
| `loading`                  | Loading state; submission is blocked while loading                                      | _boolean_                 | `false`                               |
| `clearable`                | Whether the value can be cleared                                                        | _boolean_                 | `false`                               |
| `variant`                  | Input variant: `filled`, `outline`, or `standard`                                       | _string_                  | `outline`                             |
| `size`                     | Input size inherited from Form / ConfigProvider                                         | `xs / sm / md / lg / xl`  | `md`                                  |
| `placeholder`              | Placeholder                                                                             | _string_                  | `-`                                   |
| `disabled`                 | Whether disabled                                                                        | _boolean_                 | `false`                               |
| `readonly`                 | Whether readonly                                                                        | _boolean_                 | `false`                               |
| `label`                    | Text to the left of the search input                                                    | _string_                  | `-`                                   |
| `shape`                    | Inner field shape: `round` or `square`                                                  | _string_                  | `square`                              |
| `background`               | Outer background color                                                                  | _string_                  | `-`                                   |
| `input-background`         | Inner field background color                                                            | _string_                  | `-`                                   |
| `show-action`              | Whether to show the mobile action                                                       | _boolean_                 | `false`                               |
| `action-text`              | Action button text                                                                      | `string`                  | Follows global locale and action-type |
| `action-type`              | Action type: `cancel` or `search`                                                       | _string_                  | `cancel`                              |
| `search-icon`              | Search icon name                                                                        | _string_                  | `magnify`                             |
| `max-length`               | Maximum length                                                                          | _string \| number_        | `-`                                   |
| `enterkeyhint`             | Virtual keyboard Enter hint                                                             | _string_                  | `search`                              |

### Events

| Event               | Description                                              | Callback arguments                   |
| ------------------- | -------------------------------------------------------- | ------------------------------------ |
| `update:modelValue` | Emitted when the keyword updates                         | `value: string`                      |
| `update:modelField` | Emitted when the field updates                           | `field: string`                      |
| `update:model`      | Emitted when the field model updates                     | `model: Record<string, unknown>`     |
| `input`             | Emitted during live editing                              | `value: string, event: Event`        |
| `change`            | Emitted on blur, Enter commit, or field change           | `value: string, event: Event`        |
| `clear`             | Emitted when clearing                                    | `event: Event`                       |
| `search`            | Emitted by the icon, button, Enter, or history selection | `result: SearchResult, event: Event` |
| `focus`             | Emitted on focus                                         | `event: FocusEvent`                  |
| `blur`              | Emitted on blur                                          | `event: FocusEvent`                  |
| `cancel`            | Emitted by the mobile cancel action                      | `event: Event`                       |

### Slots

| Name             | Description                                    | Arguments   |
| ---------------- | ---------------------------------------------- | ----------- |
| `prefix`         | Input prefix; replaces the default search icon | `-`         |
| `suffix`         | Input suffix                                   | `-`         |
| `clear-icon`     | Clear icon                                     | `{ clear }` |
| `button-default` | Shared search button content                   | `-`         |
| `button-icon`    | Shared search button icon                      | `-`         |
| `label`          | Left label                                     | `-`         |
| `action`         | Action content                                 | `-`         |

### Methods

| Method  | Description | Arguments | Returns |
| ------- | ----------- | --------- | ------- |
| `focus` | Focus       | `-`       | `-`     |
| `blur`  | Blur        | `-`       | `-`     |

### SearchField

| Arguments     | Description                                         | Type     |
| ------------- | --------------------------------------------------- | -------- |
| `label`       | Field label                                         | _string_ |
| `value`       | Field value                                         | _string_ |
| `placeholder` | Field `placeholder`; overrides Search `placeholder` | _string_ |

### SearchResult

| Arguments        | Description         | Type                                   |
| ---------------- | ------------------- | -------------------------------------- |
| `modelField`     | Search field        | _string \| undefined_                  |
| `modelValue`     | Raw search keyword  | _string_                               |
| `model`          | Field model object  | _Record<string, unknown> \| undefined_ |
| `recentSearches` | Next search history | _string[]_                             |

Input event contract: editing emits `input` before `update:modelValue`; committing on blur emits `change` only for a changed value. Clearing emits `clear → input → update:modelValue → change` once, updates the search field model once, and does not submit a search.

input fires before model updates. Enter waits for Input submission and controlled-value reconciliation before producing search results. If the parent rejects a trim proposal, search still uses the actual controlled value. Clearing notifies clear → input → update:modelValue → change without automatically searching.

## Controlled-model protocol

Value precedence is `modelValue` > `model`[current field] > uncontrolled `defaultValue`. With `model` and a current field, missing/null values display an empty string. Keep simultaneously bound models consistent in the parent. `modelField` overrides `defaultField` and the first field. Internal logic never forcibly overrides controlled values.

`model` is not mutated in place. Every logical update emits a new `update:model` object, clearing other declared fields while retaining undeclared properties. Use `v-model:model` or explicitly accept proposals. Switching fields produces one `update:modelField → update:modelValue → update:model → change` sequence. Parents can reject proposals. Enter/button/history searches wait one update cycle, then read the actually accepted field, keyword and `model`.

History is neither filtered by current input nor persisted internally. New history returned by `search` is trimmed, emptied entries removed, deduplicated and limited to the configured maximum. Empty keywords are not added. Nonfinite/negative limits are treated as 0. Clearing does not `search`; cancel proposes an empty string and emits cancel/change without searching.

Editing emits `input → update:modelValue`; changed commits emit `change`. Clear emits `clear → input → update:modelValue → change` once. Disabled, readonly and loading block search, cancel, history and field actions. Form / FormItem / InputGroup state is inherited. Deactivation or unmount cancels pending asynchronous search.

### Platform boundaries

The controller, public API and history content are independently copied. Both default to `presentation=inline`; Cedar defaults to `shape=square` and Maple to `shape=round`. Fullscreen history uses local Drawer / Popup instances. Desktop InputGroup and mobile search-bar layout/touch spacing remain independent. Input supports `xs/sm/md/lg/xl`; outer bar density is configured by Search tokens rather than scaled by size.

### Public types

`SearchPresentation`、`SearchProps`, `SearchEmits`, `SearchSlots`, `SearchExpose`, `SearchField`, `SearchResult`.

### Forwarded Input props

Explicit Input props include `modelModifiers`, `type`, `ariaLabel`, `placeholder`, `maxLength`, `readonly`, `disabled`, `autofocus`, `enterkeyhint`, `textColor`, `focusColor`, `blurColor`, `size`, `variant`, `clearable`, `inputAttrs` and `error`. `inputAttrs` carries native name/autocomplete/ARIA attributes to both outer and fullscreen Input; `error` overrides inherited `error` state. Search actions, popup cancellation and dialog labels follow the global locale. Programmatic cancel, field and history selection notify Form change once; native edits retain the Input event pipeline.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.
Text and person-ID models remain strings; use an empty string or a business-defined string sentinel.

---

Document: llms/en-US/components/segmented.md

<!-- Source: src/segmented/README.en-US.md; locale: en-US; page: /en/components/segmented/ -->

# Segmented

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `options`: Options

Example source: src/segmented/__demos__/basic.vue

```vue
<template>
  <c-segmented v-model="value" :options="['Daily', 'Weekly', 'Monthly']" />
</template>

<script setup>
import { ref } from 'vue'

const value = ref('Daily')
</script>
```

## Appearance and states

### Segment sizes and disabled states

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `size` | Size | Segment sizes and disabled states |
| `options` | Action list | Segment sizes and disabled states |
| `disabled` | Disable interaction | Segment sizes and disabled states |
| `default-value` | Uncontrolled default value | Segment sizes and disabled states |
<!-- demo-config-notes:end -->


Compare density at each size and disabled-option behavior.

Example source: src/segmented/__demos__/appearance-state-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const value = ref('md')

const options = ['xs', 'sm', 'md', 'lg', 'xl']
return { value, options }
})())

const scene2 = demoProxyRefs((() => {


const value = ref('on')
return { value }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">尺寸</span><span lang="en-US">size</span></h4>
    <c-space direction="column">
        <c-segmented v-model="scene1.value" size="xs" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="sm" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="md" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="lg" :options="scene1.options" />
        <c-segmented v-model="scene1.value" size="xl" :options="scene1.options" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="disabled">
    <h4><span lang="zh-CN">禁用</span><span lang="en-US">disabled</span></h4>
    <c-space wrap>
        <c-segmented disabled :options="['A', 'B', 'C']" default-value="A" />
        <c-segmented
          v-model="scene2.value"
          :options="[{
      label: '可用',
      value: 'on'
    }, {
      label: '禁用',
      value: 'off',
      disabled: true
    }]"
        />
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Layout and arrangement

### Block

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `block` | Fill parent width | Block |
| `options` | Action list | Block |
<!-- demo-config-notes:end -->


- `block`: Fit parent width
- `options`: Options

Example source: src/segmented/__demos__/block.vue

```vue
<template>
  <div style="width: 360px">
    <c-segmented v-model="value" block :options="['列表', '看板', '日历']" />
  </div>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('列表')
</script>
```

## Interaction and control

### Controlled

- `model-value`: Binding value
- `options`: Options

Example source: src/segmented/__demos__/controlled.vue

```vue
<template>
  <c-space direction="column">
    <c-segmented :model-value="value" :options="options" @change="onChange" />
    <div>当前值：{{ value }}</div>
  </c-space>
</template>

<script setup>
import { ref } from 'vue'

const value = ref('a')
const options = [
  { label: '选项 A', value: 'a' },
  { label: '选项 B', value: 'b' },
  { label: '选项 C', value: 'c', disabled: true },
]

const onChange = (next) => {
  value.value = next
}
</script>
```

## Accessibility

- The root uses `role="radiogroup"`; native `radio` options support keyboard changes.
- `name` binds a native form field `name`.
- Whole-control disabling sets `aria-disabled`.

## API

### Segmented Props

| Arguments | Description | Type | Default |
| --- | --- | --- | --- |
| model-value / v-model | Current value | `string \| number` | — |
| default-value | Uncontrolled default value | `string \| number` | — |
| options | Action list | `(string \| number \| SegmentedOption)[]` | `[]` |
| size | Size | `xs \| sm \| md \| lg \| xl` | `md` |
| disabled | Disable interaction | `boolean` | `false` |
| block | Fill parent width | `boolean` | `false` |
| orientation | Horizontal/vertical arrangement of segmented options, default horizontal; not text reading direction | `horizontal \| vertical` | `horizontal` |
| name | Native name | `string` | — |

### SegmentedOption

| Field | Description | Type |
| --- | --- | --- |
| label | Label | `string \| () => VNodeChild` |
| value | Value | `string \| number` |
| disabled | Disable this item | `boolean` |

### Segmented Events

| Event | Description | Arguments |
| --- | --- | --- |
| change | Value change | `(value, event)` |
| update:model-value | v-model | `(value)` |

### Segmented Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| label | Custom option content | `{ data: SegmentedOption }` |

---

Document: llms/en-US/components/select.md

<!-- Source: src/select/README.en-US.md; locale: en-US; page: /en/components/select/ -->

# Select

Single or multiple selection with array options, controlled values and shared field presentation.

## Reading direction

Select inherits source `dir`. Standalone fields align to inline start; FormItem content-align still takes precedence when inherited. Explicit left/right alignment remains physical. Tags keep their array order and empty-search Backspace removes the last closable value. Dropdowns and picker panels retain source direction, including in a custom popup-container.

## Async arrays and clearing

useAsyncData is a public composable exported by @cedar-design/use. Pass a loader to that composable and bind its data/loading to Select. Options remain arrays. An initialization call is per owner; share a parent result to avoid duplicate loading.

empty-value sets the single-selection clear result. Omitted preserves the existing behavior: empty string unless an empty-string option exists, in which case clearing may produce undefined. The event types include undefined. Multiple selection keeps its array semantics and cannot clear disabled selected options.

case-sensitive defaults to false. search-fields defaults to ['label']; ['value', 'label'] matches either field. Custom filters retain priority.

| Variable                              | Default                             |
| ------------------------------------- | ----------------------------------- |
| `--c-select-popup-option-check-color` | `var(--c-sys-color-action-primary)` |
| `--c-select-popup-option-check-size`  | `var(--c-sys-font-size-md)`         |
| `--c-select-popup-option-check-gap`   | `var(--c-sys-space-4)`              |

## Basic examples

### Basic

Example source: src/select/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-select v-model="value" :style="{ width: '240px' }" placeholder="Please select ..." aria-label="基础单选示例" clearable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('Shanghai')
    return {
      value,
    }
  },
})
</script>
```

## Appearance and states

### Appearance configuration comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                 | Related examples                                   |
| ------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
| `options`     | Primitive, object or grouped options; one source for every presentation | Appearance configuration comparison, Control Sizes |
| `clearable`   | Allow clearing; preserve disabled selections                            | Appearance configuration comparison, Control Sizes |
| `size`        | Supports all five sizes; inherits group/form settings                   | Control Sizes                                      |
| `variant`     | filled, outline, standard; inherits InputGroup                          | Control Sizes                                      |
| `placeholder` | Placeholder                                                             | Control Sizes                                      |
| `multiple`    | Multiple selection; enables search by default                           | Control Sizes                                      |

<!-- demo-config-notes:end -->

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/select/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("design");
const options = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops", disabled: true },
];
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-select
      v-model="value"
      :options="options"
      clearable
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-select>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Control Sizes

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

## Selection modes and options

### Multiple

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                 | Related examples                     |
| ------------- | ----------------------------------------------------------------------- | ------------------------------------ |
| `placeholder` | Placeholder                                                             | Multiple, Same Label, Optgroup       |
| `multiple`    | Multiple selection; enables search by default                           | Multiple, Same Label, Optgroup       |
| `clearable`   | Allow clearing; preserve disabled selections                            | Multiple, Same Label, Options Review |
| `filterable`  | Enable search; optionally retainInputValue                              | Same Label, Options Review           |
| `options`     | Primitive, object or grouped options; one source for every presentation | Same Label, Group Spacing            |
| `scrollbar`   | Whether to enable virtual scroll bar                                    | Multiple                             |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/multiple.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select
      :default-value="['Beijing', 'Shanghai']"
      :style="{ width: '360px' }"
      placeholder="Please select ..."
      multiple
      scrollbar
    >
      <c-option>Beijing</c-option>
      <c-option :tag-props="{ color: 'red' }">Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select
      :default-value="['Beijing', 'Shanghai', 'Guangzhou']"
      :style="{ width: '360px' }"
      placeholder="Please select ..."
      multiple
      :max-tag-count="2"
      clearable
      scrollbar
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('Shanghai')
    return {
      value,
    }
  },
})
</script>
```

### Same Label

Example source: src/select/__demos__/same-label.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const value = ref([1, 2])
const options = [
  { value: 1, label: '设备' },
  { value: 2, label: '设备' },
  { value: 3, label: '备用设备' },
]
</script>

<template>
  <c-space direction="column">
    <c-select v-model="value" multiple filterable clearable :options="options" placeholder="选择设备" />
    <span>已选 ID：{{ value.join(', ') || '无' }}</span>
  </c-space>
</template>
```

### Optgroup

Example source: src/select/__demos__/optgroup.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select :style="{ width: '320px' }" placeholder="Please select ...">
      <c-optgroup label="Group-1">
        <c-option>Beijing</c-option>
        <c-option>Shanghai</c-option>
      </c-optgroup>
      <c-optgroup label="Group-2">
        <c-option>Guangzhou</c-option>
        <c-option disabled>Disabled</c-option>
        <c-option>Shenzhen</c-option>
      </c-optgroup>
      <c-optgroup label="Group-3">
        <c-option>Chengdu</c-option>
        <c-option>Wuhan</c-option>
      </c-optgroup>
    </c-select>
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." multiple>
      <c-optgroup label="Group-1">
        <c-option>Beijing</c-option>
        <c-option>Shanghai</c-option>
      </c-optgroup>
      <c-optgroup label="Group-2">
        <c-option>Guangzhou</c-option>
        <c-option disabled>Disabled</c-option>
        <c-option>Shenzhen</c-option>
      </c-optgroup>
      <c-optgroup label="Group-3">
        <c-option>Chengdu</c-option>
        <c-option>Wuhan</c-option>
      </c-optgroup>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  })
</script>
```

### Group Spacing

Example source: src/select/__demos__/group-spacing.vue

```vue
<script setup lang="ts">
const options = [
  {
    isGroup: true,
    label: "华北",
    options: [
      { value: "beijing", label: "北京" },
      { value: "tianjin", label: "天津" },
    ],
  },
  {
    isGroup: true,
    label: "华东",
    options: [
      { value: "shanghai", label: "上海" },
      { value: "hangzhou", label: "杭州" },
    ],
  },
];
</script>

<template>
  <c-select
    :options="options"
    placeholder="分组候选"
    :style="{ width: '280px' }"
  />
</template>
```

### Options Review

Example source: src/select/__demos__/options-review.vue

```vue
<script setup lang="ts">
import { ref, watch } from 'vue'
const multiple = ref(true)
const filterable = ref(true)
const disabled = ref(false)
const value = ref<string | string[] | undefined>([])
watch(multiple, (next) => { value.value = next ? [] : undefined })
</script>
<template>
  <c-space direction="column">
    <c-space>
      <c-checkbox v-model="multiple">多选</c-checkbox>
      <c-checkbox v-model="filterable">允许搜索</c-checkbox>
      <c-checkbox v-model="disabled">禁用研发选项</c-checkbox>
      <c-button @click="value = multiple ? [] : undefined">清空选择</c-button>
    </c-space>
    <c-select v-model="value" :multiple="multiple" :filterable="filterable" clearable placeholder="子组件选项审查" :style="{ width: '280px' }">
      <c-optgroup label="研发组">
        <template #label><c-tag>研发组插槽</c-tag></template>
        <c-option value="dev" label="研发" :disabled="disabled" :tag-props="{ size: 'sm' }" :index="0">
          <template #default="{ selected }"><c-tag>{{ selected ? '已选研发' : '选择研发' }}</c-tag></template>
          <template #icon><c-tag>图标</c-tag></template>
          <template #suffix><c-tag>后缀</c-tag></template>
        </c-option>
      </c-optgroup>
    </c-select>
    <p role="status">当前值：{{ JSON.stringify(value) }}</p>
  </c-space>
</template>
```

### Allow Create

Example source: src/select/__demos__/allow-create.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." creatable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." multiple creatable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({})
</script>
```

### Fallback Option

Example source: src/select/__demos__/fallback-option.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select
      default-value="Shanxi"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      :fallback-option="fallback"
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
    </c-select>
    <c-select
      default-value="Shanxi"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      :fallback-option="fallback"
      :show-extr-options="false"
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
    </c-select>
    <c-select
      :default-value="['Shanxi', 'Nanjing', 'Hangzhou']"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      multiple
      :fallback-option="fallback"
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const fallback = (value: any) => {
      return {
        value,
        label: `++${value}++`,
      }
    }
    return {
      fallback,
    }
  },
})
</script>
```

## Search and filtering

### Filterable

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                                                                 | Related examples                             |
| ---------------- | ----------------------------------------------------------------------- | -------------------------------------------- |
| `placeholder`    | Placeholder                                                             | Filterable, Search Matching, Dropdown Scroll |
| `options`        | Primitive, object or grouped options; one source for every presentation | Filterable, Search Matching, Virtual List    |
| `filterable`     | Enable search; optionally retainInputValue                              | Filterable, Search Matching                  |
| `loading`        | Loading state; blocks selection and confirmation                        | Filterable                                   |
| `multiple`       | Multiple selection; enables search by default                           | Filterable                                   |
| `case-sensitive` | Case-sensitive built-in filtering; custom filters take priority         | Search Matching                              |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/filterable.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." filterable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select :style="{ width: '320px' }" placeholder="Please select ..." :filterable="{ retainInputValue: true }">
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Chengdu</c-option>
      <c-option>Wuhan</c-option>
    </c-select>
    <c-select
      :options="options"
      :style="{ width: '320px' }"
      :loading="loading"
      placeholder="Please select ..."
      multiple
      @search="handleSearch" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const options = ref(['Option1', 'Option2', 'Option3'])
    const loading = ref(false)

    const handleSearch = (value: any) => {
      if (value) {
        loading.value = true
        window.setTimeout(() => {
          options.value = [`${value}-Option1`, `${value}-Option2`, `${value}-Option3`]
          loading.value = false
        }, 2000)
      } else {
        options.value = []
      }
    }

    return {
      options,
      loading,
      handleSearch,
    }
  },
})
</script>
```

### Search Matching

Example source: src/select/__demos__/search-matching.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
const value = ref("");
const mode = ref("label");
const caseSensitive = ref(false);
const modes = [
  { value: "label", label: "默认：只匹配 label" },
  { value: "both", label: "配置：value 或 label" },
];
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
const searchFields = computed<("label" | "value")[]>(() =>
  mode.value === "both" ? ["value", "label"] : ["label"],
);
</script>
<template>
  <c-space direction="column" align="stretch" fill>
    <c-form-item layout="vertical" size="sm" label="匹配字段">
      <c-radio-group
        v-model="mode"
        aria-label="匹配字段"
        :options="modes"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-space
      ><c-switch v-model="caseSensitive" /><span>区分大小写</span></c-space
    >
    <c-select
      v-model="value"
      :options="options"
      :case-sensitive="caseSensitive"
      :search-fields="searchFields"
      :search-delay="0"
      filterable
      placeholder="输入 Apple、apple 或 USER_A"
    />
    <p>
      默认搜索 label，不区分大小写；配置两字段后，USER_A 和 Apple
      都能找到同一个选项。
    </p>
  </c-space>
</template>
```

### Dropdown Scroll

Example source: src/select/__demos__/dropdown-scroll.vue

```vue
<template>
  <c-select
    :style="{ width: '320px' }"
    default-value="Beijing"
    placeholder="Please select ..."
    @dropdown-scroll="handleScroll"
    @dropdown-reach-bottom="handleReachBottom"
  >
    <c-option>Beijing</c-option>
    <c-option>Shanghai</c-option>
    <c-option>Guangzhou</c-option>
    <c-option disabled>Disabled</c-option>
    <c-option>Shenzhen</c-option>
    <c-option>Chengdu</c-option>
    <c-option>Wuhan</c-option>
  </c-select>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const handleScroll = (ev) => {
      console.log('scroll', ev)
    }
    const handleReachBottom = (ev) => {
      console.log('reach the bottom', ev)
    }

    return {
      handleScroll,
      handleReachBottom,
    }
  },
})
</script>
```

### Virtual List

Example source: src/select/__demos__/virtual-list.vue

```vue
<template>
  <c-select
    :style="{ width: '320px' }"
    :options="options"
    placeholder="Please select ..."
    :virtual-list-props="{ height: 200 }" />
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  setup() {
    const options = Array(1000)
      .fill(null)
      .map((_, index) => `Option ${index}`)

    return {
      options,
    }
  },
})
</script>
```

## Content and dropdown customization

### Tag Props

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                                 | Related examples                        |
| ------------- | ----------------------------------------------------------------------- | --------------------------------------- |
| `placeholder` | Placeholder                                                             | Tag Props, Custom Header, Custom Footer |
| `multiple`    | Multiple selection; enables search by default                           | Tag Props, Custom Header, Slots Review  |
| `options`     | Primitive, object or grouped options; one source for every presentation | Tag Props, Slots Review                 |
| `filterable`  | Enable search; optionally retainInputValue                              | Custom Footer, Slots Review             |
| `clearable`   | Allow clearing; preserve disabled selections                            | Slots Review                            |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/tag-props.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-select
      multiple
      :default-value="['urgent', 'high', 'medium', 'low', 'custom', 'outline']"
      :style="{ width: '520px' }"
      placeholder="Please select ..."
      :options="colorOptions"
    />
    <c-select
      multiple
      :default-value="['long']"
      :style="{ width: '320px' }"
      placeholder="Please select ..."
      :options="widthOptions"
    />
  </c-space>
</template>

<script lang="ts">
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    const colorOptions = [
      { value: 'urgent', label: '紧急', tagProps: { color: 'red' } },
      { value: 'high', label: '高', tagProps: { status: 'danger' } },
      { value: 'medium', label: '中', tagProps: { status: 'warning' } },
      { value: 'low', label: '低', tagProps: { status: 'success' } },
      { value: 'custom', label: '自定义色', tagProps: { color: '#165DFF' } },
      {
        value: 'outline',
        label: '描边',
        tagProps: { variant: 'outline', status: 'primary' },
      },
    ]

    const widthOptions = [
      {
        value: 'long',
        label: '这是一段很长的选项文案，用来演示 Tag 最大宽度截断',
        tagProps: {
          nowrap: true,
          style: { maxWidth: '160px' },
        },
      },
      { value: 'short', label: '短标签' },
    ]

    return {
      colorOptions,
      widthOptions,
    }
  },
})
</script>
```

### Custom Header

Example source: src/select/__demos__/custom-header.vue

```vue
<template>
  <c-select :default-value="'Beijing'" :style="{ width: '360px' }" placeholder="Please select ..." multiple>
    <c-option>Beijing</c-option>
    <c-option>Shanghai</c-option>
    <c-option>Guangzhou</c-option>
    <c-option disabled>Disabled</c-option>
    <c-option>Shenzhen</c-option>
    <c-option>Wuhan</c-option>
    <template #header>
      <div style="padding: 6px 12px">
        <c-checkbox value="1">全选</c-checkbox>
      </div>
    </template>
  </c-select>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  })
</script>
```

### Custom Footer

Example source: src/select/__demos__/custom-footer.vue

```vue
<template>
  <c-space>
    <c-select :default-value="'Beijing'" :style="{ width: '360px' }" placeholder="Please select ..." filterable>
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Wuhan</c-option>
      <template #footer>
        <div style="padding: 6px 0; text-align: center">
          <c-button>Click Me</c-button>
        </div>
      </template>
    </c-select>
    <c-select
      :default-value="'Beijing'"
      :style="{ width: '360px' }"
      placeholder="Please select ..."
      filterable
      show-footer-on-empty
    >
      <c-option>Beijing</c-option>
      <c-option>Shanghai</c-option>
      <c-option>Guangzhou</c-option>
      <c-option disabled>Disabled</c-option>
      <c-option>Shenzhen</c-option>
      <c-option>Wuhan</c-option>
      <template #footer>
        <div style="padding: 6px 0; text-align: center">
          <c-button>Click Me</c-button>
        </div>
      </template>
    </c-select>
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  })
</script>
```

### Custom Label

Example source: src/select/__demos__/custom-label.vue

```vue
<template>
  <c-select v-model:modelValue="value" :style="{ width: '320px' }" placeholder="Please select ...">
    <template #label="{ data }">
      <span> <c-icon-plus />{{ data?.label }}</span>
    </template>
    <c-option>Beijing</c-option>
    <c-option>Shanghai</c-option>
    <c-option>Guangzhou</c-option>
    <c-option disabled>Disabled</c-option>
  </c-select>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const value = ref('Beijing')
    return { value }
  },
})
</script>
```

### Slots Review

Example source: src/select/__demos__/slots-review.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string[]>(['dev'])
const selectedSlot = ref(false)
const triggerSlot = ref(false)
const clears = ref(0)
const options = [{ value: 'dev', label: '研发' }, { value: 'design', label: '设计' }, { value: 'ops', label: '运营', disabled: true }]
function onClear(clear: (event: MouseEvent) => void, event: MouseEvent) {
  clears.value++
  clear(event)
}
</script>
<template>
  <c-space direction="column">
    <c-space>
      <c-checkbox v-model="selectedSlot">自定义已选区</c-checkbox>
      <c-checkbox v-model="triggerSlot">自定义触发器</c-checkbox>
    </c-space>
    <c-select v-model="value" :options="options" multiple filterable clearable placeholder="复杂插槽审查" :style="{ width: '320px' }">
      <template #prefix><c-tag>前缀</c-tag></template>
      <template #suffix><c-tag>后缀</c-tag></template>
      <template #header><c-tag>菜单页头</c-tag></template>
      <template #footer><c-tag>菜单页脚</c-tag></template>
      <template #option="{ data }"><c-tag>选项：{{ data.label }}</c-tag></template>
      <template #label="{ data }"><c-tag>已选：{{ data.label }}</c-tag></template>
      <template #clear-icon="{ clear }"><c-button size="xs" @mousedown.prevent @click.stop="onClear(clear, $event)">插槽清空</c-button></template>
      <template #arrow-icon><c-tag>展开</c-tag></template>
      <template #search-icon><c-tag>搜索</c-tag></template>
      <template #loading-icon><c-tag>加载</c-tag></template>
      <template #empty><c-tag>无匹配选项</c-tag></template>
      <template #read="{ text }"><c-tag>阅读：{{ text }}</c-tag></template>
      <template v-if="selectedSlot" #selected><c-tag>已选区域：{{ value.join(' / ') }}</c-tag></template>
      <template v-if="triggerSlot" #trigger><c-button>插槽打开选择器</c-button></template>
    </c-select>
    <p role="status">当前值：{{ JSON.stringify(value) }}；插槽清空：{{ clears }}</p>
  </c-space>
</template>
```

## Value model and linked fields

### Selection Data Flow

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration                 | Purpose                                                                                                                                                                                 | Related examples                                                 |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `options`                     | Primitive, object or grouped options; one source for every presentation                                                                                                                 | Selection Data Flow, Linkage, Empty recognition and clear output |
| `clearable`                   | Allow clearing; preserve disabled selections                                                                                                                                            | Empty recognition and clear output, Interaction state comparison |
| `edit-mode`                   | Field presentation; inherits FormItem/Form when omitted                                                                                                                                 | Selection Data Flow                                              |
| `default-active-first-option` | On opening, activate the first enabled candidate if no valid selected option exists. Highlighting does not update modelValue or emit change; an existing valid selection takes priority | Selection Data Flow                                              |
| `placeholder`                 | Placeholder                                                                                                                                                                             | Selection Data Flow                                              |
| `empty-value`                 | Clear output override; return an array for multiple selection and preserve protected items                                                                                              | Empty recognition and clear output                               |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/selection-data-flow.vue

```vue
<script setup lang="ts">
import { computed, reactive, ref } from "vue";

const props = defineProps<{ english?: boolean }>();
const autoFirst = ref(true);
const generation = ref(0);
const form = reactive<{ city?: string; panelCity?: string }>({
  city: undefined,
  panelCity: undefined,
});
const logs = reactive<{ inline: string[]; panel: string[] }>({
  inline: [],
  panel: [],
});
const counts = reactive({ inline: 0, panel: 0 });
const options = computed(() => [
  { label: props.english ? "Hangzhou" : "杭州", value: "hangzhou" },
  { label: props.english ? "Shanghai" : "上海", value: "shanghai" },
  {
    label: props.english ? "Beijing (disabled)" : "北京（禁用）",
    value: "beijing",
    disabled: true,
  },
]);
function show(value: unknown) {
  return value === undefined ? "undefined" : JSON.stringify(value);
}
function record(kind: "inline" | "panel", event: string, value: unknown) {
  if (event === "update:modelValue") {
    counts[kind]++;
  }
  logs[kind].unshift(`${event}(${show(value)})`);
  logs[kind].splice(8);
}
function reset() {
  generation.value++;
  form.city = undefined;
  form.panelCity = undefined;
  counts.inline = counts.panel = 0;
  logs.inline = [];
  logs.panel = [];
}
</script>

<template>
  <div class="selection-data-flow">
    <c-checkbox v-model="autoFirst" @change="reset"
      >defaultActiveFirstOption = {{ autoFirst }}</c-checkbox
    >
    <c-button @click="reset">{{
      english ? "Reset both forms and logs" : "重置两组表单和日志"
    }}</c-button>
    <p>
      {{
        english
          ? "Each field starts empty. Open it and inspect the highlighted candidate: highlighting does not select a city. Change the switch to remount both fields."
          : "两组字段初始都没有值。打开后观察候选行的高亮：高亮不代表选中城市。切换开关会重建两组字段，便于从空值重新比较。"
      }}
    </p>

    <section>
      <h4>
        inline · {{ english ? "Selection commits immediately" : "选择即提交" }}
      </h4>
      <c-form-item layout="vertical" hide-label>
        <c-select
          :key="`inline-${generation}`"
          v-model="form.city"
          edit-mode="direct"
          :options="options"
          :default-active-first-option="autoFirst"
          :placeholder="english ? 'Choose a city' : '请选择城市'"
          @update:model-value="record('inline', 'update:modelValue', $event)"
          @change="record('inline', 'change', $event)"
          @open-change="record('inline', 'open-change', $event)"
        >
          <template #footer>
            <p class="panel-value">
              form.city = {{ show(form.city) }} · update:modelValue ×
              {{ counts.inline }}
            </p>
          </template>
        </c-select>
      </c-form-item>
      <p>
        {{
          english
            ? "Move with arrow keys, then press Enter, or click a city. Closing without selecting leaves the form unchanged."
            : "上下键移动后按 Enter，或点击城市，才更新表单。只打开、移动候选或关闭，不更新表单。"
        }}
      </p>
      <p role="status">
        form.city = <code>{{ show(form.city) }}</code> · update:modelValue ×
        {{ counts.inline }}
      </p>
      <ol v-if="logs.inline.length" aria-live="polite">
        <li v-for="(entry, index) in logs.inline" :key="index">
          <code>{{ entry }}</code>
        </li>
      </ol>
      <p v-else>
        {{ english ? "No component events yet." : "尚无组件事件。" }}
      </p>
    </section>

    <section>
      <h4>
        click · {{ english ? "Confirm commits the draft" : "确认后提交草稿" }}
      </h4>
      <c-form-item layout="vertical" hide-label>
        <c-select
          :key="`panel-${generation}`"
          v-model="form.panelCity"
          edit-mode="click"
          :options="options"
          :default-active-first-option="autoFirst"
          :placeholder="
            english ? 'Choose a city, then confirm' : '选择城市后确认'
          "
          @update:model-value="record('panel', 'update:modelValue', $event)"
          @change="record('panel', 'change', $event)"
          @open-change="record('panel', 'open-change', $event)"
        >
          <template #footer>
            <p class="panel-value">
              {{ english ? "Committed form value" : "已提交表单值" }}：{{
                show(form.panelCity)
              }}
              · update:modelValue × {{ counts.panel }}
            </p>
          </template>
        </c-select>
      </c-form-item>
      <p>
        {{
          english
            ? "Choose a city in the editor: the selection mark is a draft. Confirm saves it; cancel or Escape discards it. Highlighting a candidate alone is not a draft selection."
            : "在编辑面板选择城市后，勾选标记表示草稿；确认才保存，取消或 Escape 丢弃草稿。只有候选高亮、尚未选择，不算草稿选择。"
        }}
      </p>
      <p role="status">
        form.panelCity = <code>{{ show(form.panelCity) }}</code> ·
        update:modelValue × {{ counts.panel }}
      </p>
      <ol v-if="logs.panel.length" aria-live="polite">
        <li v-for="(entry, index) in logs.panel" :key="index">
          <code>{{ entry }}</code>
        </li>
      </ol>
      <p v-else>
        {{ english ? "No component events yet." : "尚无组件事件。" }}
      </p>
    </section>
    <p>
      {{
        english
          ? "Logs are newest first. open-change only changes panel visibility; update:modelValue is the event that writes the form value."
          : "日志按最新在前排列。open-change 只表示打开或关闭面板；update:modelValue 才对应表单值更新。"
      }}
    </p>
  </div>
</template>

<style scoped>
.selection-data-flow {
  display: grid;
  gap: 12px;
  min-width: 0;
}
.selection-data-flow section {
  display: grid;
  gap: 8px;
  min-width: 0;
}
.selection-data-flow p,
.selection-data-flow h4 {
  margin: 0;
}
.selection-data-flow code {
  overflow-wrap: anywhere;
}
.panel-value {
  padding: 8px;
}
</style>
```

### Linkage

Example source: src/select/__demos__/linkage.vue

```vue
<template>
  <c-space>
    <c-select :style="{ width: '200px' }" v-model="province">
      <c-option v-for="value of Object.keys(data)" :key="value">{{ value }}</c-option>
    </c-select>
    <c-select :style="{ width: '200px' }" :options="data[province] || []" v-model="city" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref, watch } from 'vue'
export default defineComponent({
  setup() {
    const province = ref('Sichuan')
    const city = ref('Chengdu')
    const data = {
      Beijing: ['Haidian', 'Chaoyang', 'Changping'],
      Sichuan: ['Chengdu', 'Mianyang', 'Aba'],
      Guangdong: ['Guangzhou', 'Shenzhen', 'Shantou'],
    }

    watch(province, () => {
      city.value = ''
    })

    return {
      province,
      city,
      data,
    }
  },
})
</script>
```

### Empty recognition and clear output

This example keeps an empty string as the valid All option and clears to null. Compare the selected All option with the cleared state in the model output. Deleting the search query does not remove the selected value. The additional fields show multiple selection clearing to [] and a factory explicitly producing undefined, each with its own model output.

Example source: src/select/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ status: "" as string | null });
const multiple = ref(["active"]);
const optional = ref<string | undefined>("active");
const options = [
  { value: "", label: "All" },
  { value: "active", label: "Active" },
];
</script>
<template>
  <c-space direction="column">
    <p>
      All uses an empty string as a valid option value. Clearing produces null.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="status" label="Status">
        <c-select
          v-model="model.status"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined]"
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.status = ''">Choose All</c-button>
    <p>
      Current model: <output>{{ JSON.stringify(model.status) }}</output>
    </p>
    <c-form layout="vertical">
      <c-form-item label="Multiple: clear to []">
        <c-select
          v-model="multiple"
          :options="options"
          edit-mode="direct"
          multiple
          clearable
          :empty-value="() => []"
        />
        <output>{{ JSON.stringify(multiple) }}</output>
      </c-form-item>
      <c-form-item label="Single: clear to undefined">
        <c-select
          v-model="optional"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="() => undefined"
        />
        <output>{{ String(optional) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

### Interaction state comparison

Toggle disabled, read-only and error states, then interact with the same instance. Recovery controls remain outside the target; error appearance alone does not validate data.

Example source: src/select/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("design");
const options = [
  { label: "研发", value: "dev" },
  { label: "设计", value: "design" },
  { label: "运营", value: "ops", disabled: true },
];
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-select
      v-model="value"
      :options="options"
      clearable
      v-bind="__demoState"
    ></c-select>
  </c-space>
</template>
```

## Async data and search

### Loading

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                 | Related examples                        |
| --------------- | ----------------------------------------------------------------------- | --------------------------------------- |
| `loading`       | Loading state; blocks selection and confirmation                        | Loading, Search, Async Devices          |
| `options`       | Primitive, object or grouped options; one source for every presentation | Search, Async Devices, Async Source     |
| `placeholder`   | Placeholder                                                             | Loading, Search, Async Devices          |
| `filterable`    | Enable search; optionally retainInputValue                              | Async Devices, Async Source, Async Data |
| `multiple`      | Multiple selection; enables search by default                           | Search, Async Devices                   |
| `filter-option` | false disables local filtering; callback receives query and raw option  | Search                                  |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/loading.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const busy = ref(true)
const value = ref('beijing')
const options = [{ label: '北京 / Beijing', value: 'beijing' }, { label: '上海 / Shanghai', value: 'shanghai' }, { label: '广州 / Guangzhou', value: 'guangzhou' }]
</script>
<template>
  <c-space direction="column" :size="16" style="width: 100%">
    <c-form layout="vertical">
      <c-form-item label="加载状态 / Loading"><c-switch v-model="busy" /></c-form-item>
      <c-form-item label="默认指示器 / Default"><c-select v-model="value" :loading="busy" :options="options" edit-mode="direct" loading-mode="default" /></c-form-item>
      <c-form-item label="底部加载线 / Line"><c-select v-model="value" :loading="busy" :options="options" edit-mode="direct" loading-mode="line" /></c-form-item>
    </c-form>
    <p>切换加载状态；加载期间保留已选值，暂停选择与确认，关闭加载后恢复。Loading preserves the selected value and pauses selection.</p>
  </c-space>
</template>
```

### Search

Example source: src/select/__demos__/search.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <div>Show selections after search options</div>
    <c-select
      :style="{ width: '320px' }"
      :loading="loading"
      placeholder="Please select ..."
      multiple
      :filter-option="false"
      @search="handleSearch"
    >
      <c-option v-for="item of options" :key="item" :value="item">{{ item }}</c-option>
    </c-select>
    <div>Hide selections after search options</div>
    <c-select
      :options="options"
      :style="{ width: '320px' }"
      :loading="loading"
      placeholder="Please select ..."
      multiple
      :filter-option="false"
      :show-extr-options="false"
      @search="handleSearch" />
  </c-space>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const options = ref(['Option1', 'Option2', 'Option3'])
    const loading = ref(false)

    const handleSearch = (value: any) => {
      if (value) {
        loading.value = true
        window.setTimeout(() => {
          options.value = [`${value}-Option1`, `${value}-Option2`, `${value}-Option3`]
          loading.value = false
        }, 2000)
      } else {
        options.value = []
      }
    }

    return {
      options,
      loading,
      handleSearch,
    }
  },
})
</script>
```

### Async Devices

Example source: src/select/__demos__/async-devices.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref([2])
const options = ref<{ id: number; name: string; disabled?: boolean }[]>([])
const loading = ref(false)
async function load() {
  loading.value = true
  try {
    options.value = await Promise.resolve(Array.from({ length: 200 }, (_, index) => ({
      id: index + 1, name: `设备 ${index + 1}`, disabled: index === 3,
    })))
  } finally { loading.value = false }
}
</script>
<template>
  <c-space direction="column" :size="16">
    <c-button @click="load">加载设备列表</c-button>
    <c-select v-model="value" :options="options" :loading="loading"
      :field-names="{ label: 'name', value: 'id' }" :virtual-list-props="{ height: 180 }"
      :limit="3" multiple filterable clearable placeholder="最多选择三个设备" />
    <p>已提交 ID：{{ value }}。加载前显示 ID，加载后自动回显名称。</p>
  </c-space>
</template>
```

### Async Source

Example source: src/select/__demos__/async-source.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { useAsyncData } from '@cedar-design/use'
const value = ref('mengshuai')
// A shared business function can be imported and reused in other fields.
const loadPeople = async () => {
  await new Promise(resolve => setTimeout(resolve, 200))
  return [{ value: 'mengshuai', label: '孟帅' }, { value: 'wujiaming', label: '吴甲明' }]
}
const { data: options, loading, error, refresh } = useAsyncData(loadPeople, {
  initialData: [] as { value: string; label: string }[],
})
</script>
<template>
  <c-space direction="column">
    <c-select v-model="value" :options="options" :loading="loading" filterable />
    <p v-if="error" role="alert">加载失败，请重试。</p>
    <c-button @click="refresh()">重新加载</c-button>
  </c-space>
</template>
```

### Async Data

Example source: src/select/__demos__/en-US/async-data.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
// Replace this loader body with your API and response mapping.
async function request(query: string, { signal }: { signal: AbortSignal }) {
  await new Promise<void>((resolve, reject) => {
    const abort = () => { clearTimeout(timer); reject(new Error('Cancelled')) }
    const timer = setTimeout(() => { signal.removeEventListener('abort', abort); resolve() }, 300)
    if (signal.aborted) { abort(); return }
    signal.addEventListener('abort', abort, { once: true })
  })
  return [{ value: 'a', label: 'Alice' }, { value: 'b', label: 'Bob' }].filter(option => option.label.toLowerCase().includes(query.toLowerCase()))
}
const error = ref('')
</script>
<template>
  <c-space direction="column">
    <c-select v-model="value" :options="request" filterable @load-error="error = 'Load failed'" />
    <p role="alert">{{ error }}</p>
    <p>Selected: {{ value }}</p>
  </c-space>
</template>
```

## Configuration and lifecycle

### Passthrough Options

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration         | Purpose                                                                                                                                                                                 | Related examples                                              |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `options`             | Primitive, object or grouped options; one source for every presentation                                                                                                                 | Passthrough Options, Scheduler Lifecycle, Copying and editing |
| `edit-mode`           | Field presentation; inherits FormItem/Form when omitted                                                                                                                                 | Passthrough Options, Copying and editing                      |
| `trigger-props`       | Optional dropdown Trigger settings. Placement defaults to bottom-start and automatically adjusts when space is limited. The field owns open state; there is no top-level placement prop | Passthrough Options                                           |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available.                                                        | Copying and editing                                           |
| `filterable`          | Enable search; optionally retainInputValue                                                                                                                                              | Copying and editing                                           |

<!-- demo-config-notes:end -->

Example source: src/select/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { SelectTriggerOptions } from "@cedar-design/ui";
const open = ref(false);
const triggerOptions: SelectTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
  popupContainer: false,
};
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-select
      edit-mode="direct"
      v-model:open="open"
      :options="options"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### Select

| Prop                                          | Description                                                                                                                                                                             | Type                                                        | Default                          |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------- |
| `open-trigger-target`                         | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available.                                                        | `'field' \| 'icon'`                                         | `'field'`                        |
| `model-value / default-value`                 | Controlled value / uncontrolled initial value                                                                                                                                           | `Value`                                                     | `Single: ''; multiple: []`       |
| `open / default-open`                         | Controlled / initial open state                                                                                                                                                         | `boolean`                                                   | `undefined / false`              |
| `input-value / default-input-value`           | Search text, independent of selected values                                                                                                                                             | `string`                                                    | `undefined / ''`                 |
| `multiple`                                    | Multiple selection; enables search by default                                                                                                                                           | `boolean`                                                   | `false`                          |
| `size`                                        | Supports all five sizes; inherits group/form settings                                                                                                                                   | `ComponentSize`                                             | `md`                             |
| `variant`                                     | filled, outline, standard; inherits InputGroup                                                                                                                                          | `FormControlVariant`                                        | `filled`                         |
| `disabled / readonly / error`                 | Inherits form state unless explicitly overridden                                                                                                                                        | `boolean`                                                   | `undefined`                      |
| `placeholder`                                 | Placeholder                                                                                                                                                                             | `string`                                                    | `—`                              |
| `hint / line`                                 | Floating hint / standard variant underline                                                                                                                                              | `boolean`                                                   | `true`                           |
| `text-color / focus-color / blur-color`       | Field colors                                                                                                                                                                            | `string`                                                    | `—`                              |
| `loading`                                     | Loading state; blocks selection and confirmation                                                                                                                                        | `boolean`                                                   | `false`                          |
| `show-tags`                                   | Show tags; false displays separated text                                                                                                                                                | `boolean`                                                   | `true`                           |
| `separator`                                   | Separator when show-tags=false                                                                                                                                                          | `string`                                                    | `,`                              |
| `text-align`                                  | Value alignment: left / center / right. Inherits FormItem content-align when omitted; defaults to inline start outside forms.                                                                   | `'left' \| 'center' \| 'right'`                             | `-`                              |
| `max-tag-count`                               | Maximum visible tags; 0 means unlimited                                                                                                                                                 | `number`                                                    | `0`                              |
| `tag-nowrap`                                  | Keep tags on one line with ellipsis and preserved removal icons; overflow scrolls horizontally; hover, focus or tap truncated text to preview it                                        | `boolean`                                                   | `false`                          |
| `popup-container`                             | Selector, element, element resolver, or false for inline rendering                                                                                                                      | `PopupContainer`                                            | `—`                              |
| `trigger-props`                               | Optional dropdown Trigger settings. Placement defaults to bottom-start and automatically adjusts when space is limited. The field owns open state; there is no top-level placement prop | `TriggerProps`                                              | `—`                              |
| `virtual-list-props`                          | Pass the virtual list attribute, pass in this parameter to turn on virtual scrolling [VirtualListProps](#VirtualListProps)                                                              | `VirtualListProps`                                          | `—`                              |
| `search-delay`                                | Search debounce delay in ms                                                                                                                                                             | `number`                                                    | `500`                            |
| `format-label`                                | Format selected labels; use label slot for VNodes                                                                                                                                       | `function`                                                  | `—`                              |
| `clearable`                                   | Allow clearing; preserve disabled selections                                                                                                                                            | `boolean`                                                   | `true`                           |
| `empty-value`                                 | Clear output override; return an array for multiple selection and preserve protected items                                                                                              | `SelectEmptyValue`                                          | `undefined`                      |
| `options`                                     | Primitive, object or grouped options; one source for every presentation                                                                                                                 | `SelectOption[]` / `(query, { signal }) => Array / Promise` | `undefined`                      |
| `field-names`                                 | Map value, label, disabled, tagProps, render; object values need a unique ID field                                                                                                      | `SelectFieldNames`                                          | `—`                              |
| `filterable`                                  | Enable search; optionally retainInputValue                                                                                                                                              | `boolean or { retainInputValue?: boolean }`                 | `Single: false / multiple: true` |
| case-sensitive                                | Case-sensitive built-in filtering; custom filters take priority                                                                                                                         | boolean                                                     | false                            |
| `filter-option`                               | false disables local filtering; callback receives query and raw option                                                                                                                  | `boolean or (input, option) => boolean`                     | automatic: arrays on; loader off |
| `creatable`                                   | Allow creating missing options                                                                                                                                                          | `boolean`                                                   | `false`                          |
| `fallback-option`                             | Display unresolved values or return a complete fallback option                                                                                                                          | `boolean or (value) => SelectOptionData`                    | `true`                           |
| `show-extra-options`                          | Display fallback/created options in the panel                                                                                                                                           | `boolean`                                                   | `true`                           |
| `limit`                                       | Selection limit; 0 means unlimited                                                                                                                                                      | `number`                                                    | `0`                              |
| `auto-fit-popup-width`                        | Match Menu width to the field                                                                                                                                                           | `boolean`                                                   | `true`                           |
| `default-active-first-option`                 | On opening, activate the first enabled candidate if no valid selected option exists. Highlighting does not update modelValue or emit change; an existing valid selection takes priority | `boolean`                                                   | `true`                           |
| `unmount-on-close`                            | Unmount Menu content when closed                                                                                                                                                        | `boolean`                                                   | `false`                          |
| `scrollbar`                                   | Whether to enable virtual scroll bar                                                                                                                                                    | `boolean or ScrollbarProps`                                 | `true`                           |
| `show-header-on-empty / show-footer-on-empty` | Display header/footer in empty state                                                                                                                                                    | `boolean`                                                   | `false`                          |
| `edit-mode`                                   | Field presentation; inherits FormItem/Form when omitted                                                                                                                                 | `direct / click / dblclick`                                 | `direct`                         |
| `before-commit`                               | Asynchronous before-commit hook after validation                                                                                                                                        | `(value, context) => void / false / Promise`                | —                                |

### Option Props

| Prop      | Description                                                 | Type                                                   | Default   |
| --------- | ----------------------------------------------------------- | ------------------------------------------------------ | --------- |
| value     | Option Value                                                | string \| number \| boolean \| Record<string, unknown> | undefined |
| label     | Option group title                                          | string                                                 | undefined |
| disabled  | Whether to disable                                          | boolean                                                | false     |
| tag-props | Props of the multi-select label corresponding to the option | TagProps                                               | undefined |
| index     | Explicit option order                                       | number                                                 | undefined |

### Option Slots

| Slot    | Description           | Arguments             |
| ------- | --------------------- | --------------------- |
| default | Custom option content | { selected: boolean } |
| icon    | Option icon           | -                     |
| suffix  | Option suffix         | -                     |

### Optgroup Props

| Prop  | Description        | Type   | Default   |
| ----- | ------------------ | ------ | --------- |
| label | Option group title | string | undefined |

### Optgroup Slots

| Slot    | Description                   | Arguments |
| ------- | ----------------------------- | --------- |
| label   | Option group title            | -         |
| default | Option children in this group | -         |

### Select Slots

| Slot         | Description                             | Arguments       |
| ------------ | --------------------------------------- | --------------- |
| default      | Option or Optgroup children             | -               |
| option       | Custom option content                   | { data }        |
| label        | Option group title                      | { data }        |
| selected     | Replace the whole selected-value region | -               |
| header       | Menu header                             | -               |
| footer       | Menu footer                             | -               |
| trigger      | Custom field trigger                    | -               |
| prefix       | Field prefix                            | -               |
| suffix       | Field suffix                            | -               |
| clear-icon   | Custom clear action                     | { clear }       |
| arrow-icon   | Dropdown arrow                          | -               |
| search-icon  | Search icon                             | -               |
| loading-icon | Loading icon                            | -               |
| empty        | Empty-state content                     | -               |
| read         | Read-mode content                       | { value, text } |

### Select Events

| Event                 | Description                                              | Arguments    |
| --------------------- | -------------------------------------------------------- | ------------ |
| update:model-value    | Request a model value update                             | value        |
| change                | Option                                                   | value        |
| update:open           | Request popup visibility                                 | open         |
| open-change           | Popup visibility changes                                 | open         |
| update:input-value    | Request search text update                               | text         |
| input-value-change    | Search text changes                                      | text         |
| search                | Triggered when the user searches                         | text         |
| focus                 | Focus enters the field                                   | event        |
| blur                  | Focus leaves the field                                   | event        |
| clear                 | Triggered when the value of the input changes            | event        |
| remove                | Triggered when the delete button of the label is clicked | value        |
| exceed-limit          | Selection would exceed the multiple-selection limit      | value, event |
| dropdown-scroll       | Menu scrolls                                             | event        |
| dropdown-reach-bottom | Menu reaches its bottom                                  | event        |

### Select Methods

| Method | Description            | Arguments |
| ------ | ---------------------- | --------- |
| focus  | Focus the actual field | -         |
| blur   | Blur the actual field  | -         |

### Scheduler Lifecycle

Example source: src/select/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const active = ref(true);
const open = ref(false);
const value = ref("Item 101");
const options = Array.from(
  { length: 200 },
  (_, index) => "Item " + (index + 1),
);
</script>
<template>
  <div>
    <c-button @click="open = !open">Open / close</c-button>
    <c-button @click="active = !active">Activate / deactivate</c-button>
    <p>
      Open the menu, navigate with Arrow keys, then close or deactivate. Old
      scrolling must not replay.
    </p>
    <KeepAlive>
      <c-select
        v-if="active"
        v-model="value"
        v-model:open="open"
        :options="options"
        style="width: 240px"
      />
    </KeepAlive>
  </div>
</template>
```

### Api Review

### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/select/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column" align="stretch">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-form-item layout="vertical" hide-label>
      <c-select
        v-model="value"
        edit-mode="direct"
        :open-trigger-target="target"
        :filterable="editable"
        :options="[
          { value: 'a', label: 'Alpha' },
          { value: 'b', label: 'Beta' },
        ]"
      />
    </c-form-item>
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("a");
</script>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

Selected rows show a primary-colored right-side checkmark in both single/multiple modes; candidate highlighting alone does not. In click/dblclick editors, checkmarks reflect draft selection, committed to Form only on confirmation. Disabled selected items retain disabled appearance.

### Cleared values and 1.x compatibility

`SelectValue` includes `undefined`. By default, single-select clear emits `''`; if the current options contain a `value: ''` option, it emits `undefined` to distinguish clearing from selecting that option. This published behavior is preserved. Both `change` and `update:modelValue` use `SelectValue`.

`empty-value` defines clear output; omission preserves the existing fallback. Single selection can use `() => undefined` to explicitly return undefined; multiple selection should return an array matching its model shape. Protected disabled selections take priority and prevent the clear override from running. Controlled mode still requires parent acceptance.

Root and component entries export `SelectValue` and `SelectEmptyValue`.

### Select props

Use `v-model`, `v-model:open` and `v-model:input-value` for controlled state. Clear values are `''` for single selection and `[]` for multiple selection. Select uses `undefined` when an actual empty-string option exists.

| Prop                                          | Description                                                                                                                                                                             | Type                                                        | Default                                                      |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------ |
| `open-trigger-target`                         | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available.                                                        | `'field' \| 'icon'`                                         | `'field'`                                                    |
| `model-value / default-value`                 | Controlled value / uncontrolled initial value                                                                                                                                           | `Value`                                                     | `Single: ''; multiple: []`                                   |
| `open / default-open`                         | Controlled / initial open state                                                                                                                                                         | `boolean`                                                   | `undefined / false`                                          |
| `input-value / default-input-value`           | Search text, independent of selected values                                                                                                                                             | `string`                                                    | `undefined / ''`                                             |
| `multiple`                                    | Multiple selection; enables search by default                                                                                                                                           | `boolean`                                                   | `false`                                                      |
| `size`                                        | Supports all five sizes; inherits group/form settings                                                                                                                                   | `ComponentSize`                                             | `md`                                                         |
| `variant`                                     | filled, outline, standard; inherits InputGroup                                                                                                                                          | `FormControlVariant`                                        | `filled`                                                     |
| `disabled / readonly / error`                 | Inherits form state unless explicitly overridden                                                                                                                                        | `boolean`                                                   | `undefined`                                                  |
| `placeholder`                                 | Placeholder                                                                                                                                                                             | `string`                                                    | `—`                                                          |
| `hint / line`                                 | Floating hint / standard variant underline                                                                                                                                              | `boolean`                                                   | `true`                                                       |
| `text-color / focus-color / blur-color`       | Field colors                                                                                                                                                                            | `string`                                                    | `—`                                                          |
| `loading`                                     | Loading state; blocks selection and confirmation                                                                                                                                        | `boolean`                                                   | `false`                                                      |
| `loading-mode` | Loading layout: default indicator or bottom line | `default / line` | `default` |
| `show-tags`                                   | Show tags; false displays separated text                                                                                                                                                | `boolean`                                                   | `true`                                                       |
| `separator`                                   | Separator when show-tags=false                                                                                                                                                          | `string`                                                    | `,`                                                          |
| `text-align`                                  | Text alignment: left / center / right. Inherits FormItem content-align when unset; standalone fields default to inline start                                                                    | `'left' \| 'center' \| 'right'`                             | `-`                                                          |
| `max-tag-count`                               | Maximum visible tags; 0 means unlimited                                                                                                                                                 | `number`                                                    | `0`                                                          |
| `tag-nowrap`                                  | Keep tags on one line with ellipsis and preserved removal icons; overflow scrolls horizontally; hover, focus or tap truncated text to preview it                                        | `boolean`                                                   | `false`                                                      |
| `popup-container`                             | Selector, element, element resolver, or false for inline rendering                                                                                                                      | `PopupContainer`                                            | `—`                                                          |
| `trigger-props`                               | Optional dropdown Trigger settings. Placement defaults to bottom-start and automatically adjusts when space is limited. The field owns open state; there is no top-level placement prop | `TriggerProps`                                              | `—`                                                          |
| `virtual-list-props`                          | Pass the virtual list attribute, pass in this parameter to turn on virtual scrolling [VirtualListProps](#VirtualListProps)                                                              | `VirtualListProps`                                          | `—`                                                          |
| `search-delay`                                | Search debounce delay in ms                                                                                                                                                             | `number`                                                    | `500`                                                        |
| `format-label`                                | Format selected labels; use label slot for VNodes                                                                                                                                       | `function`                                                  | `—`                                                          |
| `clearable`                                   | Allow clearing; preserve disabled selections                                                                                                                                            | `boolean`                                                   | `true`                                                       |
| `empty-value`                                 | Clear output override; return an array for multiple selection and preserve protected items                                                                                              | `SelectEmptyValue`                                          | `undefined`                                                  |
| `options`                                     | Primitive, object or grouped options; one source for every presentation                                                                                                                 | `SelectOption[]` / `(query, { signal }) => Array / Promise` | `undefined`                                                  |
| `field-names`                                 | Map value, label, disabled, tagProps, render; object values need a unique ID field                                                                                                      | `SelectFieldNames`                                          | `—`                                                          |
| `filterable`                                  | Enable search; optionally retainInputValue                                                                                                                                              | `boolean or { retainInputValue?: boolean }`                 | `Single: false; multiple: true`                              |
| case-sensitive                                | Case-sensitive built-in filtering; custom filters take priority                                                                                                                         | boolean                                                     | false                                                        |
| `filter-option`                               | false disables local filtering; callback receives query and raw option                                                                                                                  | `boolean or (input, option) => boolean`                     | Automatic: enabled for arrays, disabled for loader functions |
| `creatable`                                   | Allow creating missing options                                                                                                                                                          | `boolean`                                                   | `false`                                                      |
| `fallback-option`                             | Display unresolved values or return a complete fallback option                                                                                                                          | `boolean or (value) => SelectOptionData`                    | `true`                                                       |
| `show-extra-options`                          | Display fallback/created options in the panel                                                                                                                                           | `boolean`                                                   | `true`                                                       |
| `limit`                                       | Selection limit; 0 means unlimited                                                                                                                                                      | `number`                                                    | `0`                                                          |
| `auto-fit-popup-width`                        | Match Menu width to the field                                                                                                                                                           | `boolean`                                                   | `true`                                                       |
| `default-active-first-option`                 | On opening, activate the first enabled candidate if no valid selected option exists. Highlighting does not update modelValue or emit change; an existing valid selection takes priority | `boolean`                                                   | `true`                                                       |
| `unmount-on-close`                            | Unmount Menu content when closed                                                                                                                                                        | `boolean`                                                   | `false`                                                      |
| `scrollbar`                                   | Whether to enable virtual scroll bar                                                                                                                                                    | `boolean or ScrollbarProps`                                 | `true`                                                       |
| `show-header-on-empty / show-footer-on-empty` | Display header/footer in empty state                                                                                                                                                    | `boolean`                                                   | `false`                                                      |
| `edit-mode`                                   | Field presentation; inherits FormItem/Form when omitted                                                                                                                                 | `direct / click / dblclick`                                 | `direct`                                                     |
| `before-commit`                               | Asynchronous before-commit hook after validation                                                                                                                                        | `(value, context) => void / false / Promise`                | —                                                            |

### Events and methods

- `update:modelValue`, `change(value)`: emitted on commit, not while editing a draft.
- `update:open`, `open-change(open)`: request an expanded-state change.
- `update:inputValue`, `input-value-change(text)`, `search(text)`: search state.
- `focus(event)`, `blur(event)`, `clear(event)`: native field events; only the field owner notifies Form.
- Methods: `focus()`, `blur()`.

Select also emits `remove(value)`, `exceed-limit(value, event)`, `dropdown-scroll(event)`, and `dropdown-reach-bottom(event)`.

### Slots and option data

Use `label({ data })` for custom `selected` labels; `selected` replaces the whole selection area. Also supports `prefix`, `suffix`, `clear-icon({ clear })`, `arrow-icon`, `loading-icon`, `search-icon`, `empty`, and `option({ data })`.

Option `label` is searchable plain text. Use `render` or the `option` slot for custom `option` content, and `format-label` or `label` slot for selected content. Values identify selections; labels never do. `disabled` blocks selection/removal, and `tagProps` customizes selected tags.

Select additionally supports `header`, `footer`, `trigger`, and default `Option / Optgroup` children. Option props: `value`, `label`, `disabled`, `tagProps`, `index`; its default slot receives `selected`. Group data uses `{ isGroup: true, label, options }`. List and Picker also accept slot options; Picker displays their text labels.

Single/multiple options both use popup-option-padding-horizontal. There is no implicit search-highlight DOM; custom option slots style their own highlighted fragments. Unused multi-popup-option-padding-horizontal and popup-option-highlight-* variables are removed.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

### Option Props

| Prop      | Description                                                 | Type                                                   | Default   |
| --------- | ----------------------------------------------------------- | ------------------------------------------------------ | --------- |
| value     | Option Value                                                | string \| number \| boolean \| Record<string, unknown> | undefined |
| label     | Option group title                                          | string                                                 | undefined |
| disabled  | Whether to disable                                          | boolean                                                | false     |
| tag-props | Props of the multi-select label corresponding to the option | TagProps                                               | undefined |
| index     | Explicit option order                                       | number                                                 | undefined |

### Option Slots

| Slot    | Description           | Arguments             |
| ------- | --------------------- | --------------------- |
| default | Custom option content | { selected: boolean } |
| icon    | Option icon           | -                     |
| suffix  | Option suffix         | -                     |

### Optgroup Props

| Prop  | Description        | Type   | Default   |
| ----- | ------------------ | ------ | --------- |
| label | Option group title | string | undefined |

### Optgroup Slots

| Slot    | Description                    | Arguments |
| ------- | ------------------------------ | --------- |
| label   | Option group title             | -         |
| default | Option children inside a group | -         |

### Select Slots

| Slot         | Description                             | Arguments       |
| ------------ | --------------------------------------- | --------------- |
| default      | Option / Optgroup children              | -               |
| option       | Custom option content                   | { data }        |
| label        | Option group title                      | { data }        |
| selected     | Replace the whole selected-value region | -               |
| header       | Menu header                             | -               |
| footer       | Menu footer                             | -               |
| trigger      | Custom field trigger                    | -               |
| prefix       | Field prefix                            | -               |
| suffix       | Field suffix                            | -               |
| clear-icon   | Custom clear action                     | { clear }       |
| arrow-icon   | Dropdown arrow                          | -               |
| search-icon  | Search icon                             | -               |
| loading-icon | Loading icon                            | -               |
| empty        | Empty-state content                     | -               |
| read         | Read-mode content                       | { value, text } |

### Select Events

| Event                 | Description                                              | Arguments    |
| --------------------- | -------------------------------------------------------- | ------------ |
| update:model-value    | Request a model value update                             | value        |
| change                | Option                                                   | value        |
| update:open           | Request popup visibility                                 | open         |
| open-change           | Popup visibility changes                                 | open         |
| update:input-value    | Request search text update                               | text         |
| input-value-change    | Search text changes                                      | text         |
| search                | Triggered when the user searches                         | text         |
| focus                 | Field gains focus                                        | event        |
| blur                  | Field loses focus                                        | event        |
| clear                 | Triggered when the value of the input changes            | event        |
| remove                | Triggered when the delete button of the label is clicked | value        |
| exceed-limit          | Selection would exceed the multiple-selection limit      | value, event |
| dropdown-scroll       | Menu scrolls                                             | event        |
| dropdown-reach-bottom | Menu reaches its bottom                                  | event        |

### Select Methods

| Method | Description            | Arguments |
| ------ | ---------------------- | --------- |
| focus  | Focus the actual field | -         |
| blur   | Blur the actual field  | -         |

### Selected-checkmark style variables

| Variable                              | Default                             |
| ------------------------------------- | ----------------------------------- |
| `--c-select-popup-option-check-color` | `var(--c-sys-color-action-primary)` |
| `--c-select-popup-option-check-size`  | `var(--c-sys-font-size-md)`         |
| `--c-select-popup-option-check-gap`   | `var(--c-sys-space-4)`              |

### Public type exports

Root and component entries export `SelectEmits`、`SelectSlots`、`SelectExpose` alongside Props and Instance. Emits are event argument tuples derived from the runtime validators; Expose contains focus/blur.

### Built-in search fields

`searchFields` / `search-fields` is a readonly `('label' | 'value')[]`, defaulting to `['label']`. Multiple fields use OR matching, case-insensitive by default. `['value', 'label']` searches codes and names; fieldNames maps semantic fields to business fields. An empty array matches no items for a nonempty query. Values are compared as strings; object traversal, object values and pinyin matching require a custom callback. A custom callback takes precedence and decides case handling itself. Remote results use the existing protocol for disabling local filtering. Cascader retains path semantics and checks the configured fields on each path node.

## Loading options through a function prop

Pass options(query, { signal }) directly; useAsyncData is unnecessary. options still accepts arrays, and an explicit array, including [], takes precedence. The component manages loading, stale-result isolation and cancellation. load-error reports failures, and the instance refresh() method retries. A business loader may accept only query and ignore the second argument.

filterable enables entering a search query. filterOption controls only local matching and never sends requests. With an options loader, remote results are not filtered again by default; with only an array, local matching is enabled by default. Most callers do not need filter-option.

```vue
<c-select v-model="value" :options="loadOptions" filterable />
```

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

---

Document: llms/en-US/components/skeleton.md

<!-- Source: src/skeleton/README.en-US.md; locale: en-US; page: /en/components/skeleton/ -->

# Skeleton

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:loading="loading"`.

Example source: src/skeleton/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const loading = ref(true);
</script>

<template>
  <c-switch v-model="loading" />
  <c-skeleton :loading="loading">加载的数据</c-skeleton>
</template>
```

## Content and presentation

### Skeleton content shapes

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Whether to show a title placeholder | Skeleton content shapes, Animation |
| `loading` | Whether to display the loading skeleton | Skeleton content shapes, Fullscreen |
| `avatar` | Whether to show an avatar placeholder | Skeleton content shapes, Animation |
| `rows` | The paragraph number of rows | Skeleton content shapes |
| `rows-width` | Width of each row | Skeleton content shapes |
| `card` | Whether to show a card placeholder | Skeleton content shapes |
<!-- demo-config-notes:end -->


Compare text-row placeholders with avatar and card shapes according to the final content layout.

Example source: src/skeleton/__demos__/content-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {

const loading = ref(true);
return { loading }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="title-and-rows">
    <h4><span lang="zh-CN">标题与段落</span><span lang="en-US">title and rows</span></h4>
    <c-skeleton
        title
        :rows="3"
        :loading="scene1.loading"
        :rows-width="['200px', '100px', '50px']"
      >
        加载的数据
      </c-skeleton>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="avatar-and-card">
    <h4><span lang="zh-CN">头像与卡片</span><span lang="en-US">avatar and card</span></h4>
    <c-skeleton title avatar card :rows="3">加载的数据</c-skeleton>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Animation

Preview configuration: `title`, `avatar`, `:animation="animation"`.

Example source: src/skeleton/__demos__/animation.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const animation = ref(true);
</script>

<template>
  <c-switch v-model="animation" />
  <c-skeleton title avatar :animation="animation">加载的数据</c-skeleton>
</template>
```

### Fullscreen

Preview configuration: `fullscreen`, `:loading="loading"`.

Example source: src/skeleton/__demos__/fullscreen.vue

```vue
<script setup lang="ts">
import { onUnmounted, ref } from "vue";
const loading = ref(false);
let timer: ReturnType<typeof setTimeout> | undefined;

function show() {
  loading.value = true;
  clearTimeout(timer);
  timer = setTimeout(() => {
    loading.value = false;
  }, 2000);
}
onUnmounted(() => clearTimeout(timer));
</script>

<template>
  <c-button status="danger" @click="show">切换全屏模式</c-button>
  <c-skeleton fullscreen :loading="loading" />
</template>
```

## Customization and slots

### Custom Template

Preview configuration: `:rows="3"`, `:widths="['100%', '100%', '60%']"`, `shape="circle"`.

Example source: src/skeleton/__demos__/custom-template.vue

```vue
<template>
  <c-skeleton>
    <template #template>
      <c-space block direction="column" size="lg">
        <c-skeleton-line :rows="3" :widths="['100%', '100%', '60%']" />
        <c-skeleton-shape shape="circle" />
      </c-space>
    </template>
    加载的数据
  </c-skeleton>
</template>
```

## API

### `<skeleton>` Props

| Parameter | Description | Type | Default |
| ------------------ | ---------------------------- | ------------------------- | :-----: |
| loading | Whether to display the loading skeleton | `boolean` | `true` |
| animation | Whether skeleton animation is enabled | `boolean` | `true` |
| title | Whether to show a title placeholder | `boolean` | `false` |
| avatar | Whether to show an avatar placeholder | `boolean` | `false` |
| card | Whether to show a card placeholder | `boolean` | `false` |
| rows | The paragraph number of rows | `number \| string` | `3` |
| rows-width | Width of each row | `Array<number \| string>` | `[]` |
| title-width | `50%` | `number \| string` | `-` |
| avatar-size | `34px` | `number \| string` | `-` |
| card-height | `160px` | `number \| string` | `-` |
| fullscreen | Whether to use a fullscreen placeholder | `boolean` | `false` |
| fullscreen-z-index | Fullscreen placeholder stacking level | `number \| string` | `100` |

### `<skeleton>` Slots

| Slot | Description |
| -------- | -------------------- |
| default | Actual content after loading |
| template | Custom loading placeholder |

### `<skeleton-line>` Props

| Parameter | Description | Type | Default |
| ------------ | ---------------- | ------------------------- | :----: |
| rows | Displayed row count | `number` | `1` |
| widths | Line skeleton width | `Array<number \| string>` | `[]` |
| line-height | Line skeleton height | `number` | `20` |
| line-spacing | Line skeleton row spacing | `number` | `15` |

### `<skeleton-shape>` Props

| Parameter | Description | Type | Default |
| ------ | -------------- | ---------------------- | :--------: |
| shape | Graphic skeleton shape | `'square' \| 'circle'` | `'square'` |
| size | Graphic skeleton size | `'sm' \| 'md' \| 'lg'` | `'md'` |

### Type definitions

The component exports the following types

```ts
import type {
  SkeletonInstance,
  SkeletonLineProps,
  SkeletonShapeProps,
} from "@cedar-design/ui";
```

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Skeleton, SkeletonLine and SkeletonShape use independently copied source. Each library maintains its skeleton theme and size tokens.

### Managed defaults

| Token | Default |
| --- | --- |
| `--c-skeleton-content-padding` | `var(--c-sys-space-6)` |
| `--c-skeleton-card-border-radius` | `var(--c-sys-radius-md)` |
| `--c-skeleton-card-margin-bottom` | `var(--c-sys-space-6)` |
| `--c-skeleton-card-background-color` | `var(--c-sys-color-state-hover)` |
| `--c-skeleton-animation-background` | `linear-gradient(90deg, transparent, var(--c-sys-color-surface-default), transparent)` |
| `--c-skeleton-avatar-border-radius` | `50%` |
| `--c-skeleton-avatar-margin-right` | `var(--c-sys-space-6)` |
| `--c-skeleton-avatar-background-color` | `var(--c-sys-color-state-hover)` |
| `--c-skeleton-title-border-radius` | `10px` |
| `--c-skeleton-title-background-color` | `var(--c-sys-color-state-hover)` |
| `--c-skeleton-row-height` | `12px` |
| `--c-skeleton-row-border-radius` | `10px` |
| `--c-skeleton-row-margin-top` | `10px` |
| `--c-skeleton-shape-size-sm` | `36px` |
| `--c-skeleton-shape-size-md` | `48px` |
| `--c-skeleton-shape-size-lg` | `60px` |
| `--c-skeleton-shape-border-radius` | `var(--c-sys-radius-md)` |

### Motion variables

| Token | Default |
| --- | --- |
| `--c-skeleton-animation-duration` | `1s` |
| `--c-skeleton-transition-duration` | `var(--c-sys-motion-duration-slow)` |

Built-in motion follows prefers-reduced-motion: reduce, preserving content/state feedback while disabling decorative spinning, shimmer and ripples. Icon name changes skip waiting and cancel unfinished transitions. Ripple duration variables affect only CSS; the 250ms lifecycle timer remains unchanged, so each visual stage should not exceed 250ms. Callers must adapt custom animation classes.

---

Document: llms/en-US/components/slider.md

<!-- Source: src/slider/README.en-US.md; locale: en-US; page: /en/components/slider/ -->

# Slider

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/slider/__demos__/basic.vue

```vue
<template>
  <c-slider></c-slider>
</template>
<script lang="ts" setup>
</script>
```

## Layout and arrangement

### Vertical

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                                                                                 | Related examples |
| -------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `orientation`  | Horizontal/vertical axis of the slider track and interaction, default horizontal; not the direction of value increments | Vertical         |
| `aria-label`   | Name, or separate names for range thumbs                                                                                | Vertical         |
| `range`        | Fixed low/high thumbs; initial reversed values are sorted                                                               | Vertical         |
| `show-tooltip` | true on hover/focus/drag, false hidden, always persistent                                                               | Vertical         |

<!-- demo-config-notes:end -->

Preview configuration: `orientation="vertical"`, `aria-label="Vertical value"`, `range`, `show-tooltip="always"`.

Example source: src/slider/__demos__/vertical.vue

```vue
<script setup>
import { ref } from 'vue'

const value = ref(50)
const pair = ref([7, 64])
</script>

<template>
  <section class="slider-vertical-demo">
    <c-space justify="space-around">
      <div class="slider-vertical-demo__track">
        <c-slider v-model="value" orientation="vertical" aria-label="Vertical value" />
      </div>
      <div class="slider-vertical-demo__track">
        <c-slider
          v-model="pair"
          range
          show-tooltip="always"
          orientation="vertical"
          :aria-label="['Vertical minimum', 'Vertical maximum']"
        />
      </div>
    </c-space>
    <output aria-label="Vertical values">{{ value }} / {{ pair[0] }}–{{ pair[1] }}</output>
  </section>
</template>

<style scoped>
.slider-vertical-demo {
  display: flex;
  flex-direction: column;
  gap: 16px;
}
.slider-vertical-demo__track {
  height: 300px;
}
</style>
```

## Content and presentation

### Touch And Labels

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration  | Purpose                                                   | Related examples |
| -------------- | --------------------------------------------------------- | ---------------- |
| `show-tooltip` | true on hover/focus/drag, false hidden, always persistent | Touch And Labels |
| `aria-label`   | Name, or separate names for range thumbs                  | Touch And Labels |

<!-- demo-config-notes:end -->

Preview configuration: `show-tooltip="always"`, `aria-label="Always visible"`, `:show-tooltip="false"`, `active-color="#722ed1"`.

Example source: src/slider/__demos__/touch-and-labels.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(45);
</script>
<template>
  <c-space direction="column" size="36px" style="padding: 32px 12px">
    <c-slider
      v-model="value"
      show-tooltip="always"
      aria-label="Always visible"
    />
    <c-slider
      v-model="value"
      :show-tooltip="false"
      active-color="#722ed1"
      thumb-color="#f4edff"
      :track-height="8"
      :thumb-size="24"
      aria-label="Custom size"
    />
    <c-slider v-model="value" aria-label="Custom handle"
      ><template #button="{ currentValue }"
        ><span class="slider-custom-handle">{{ currentValue }}</span></template
      ></c-slider
    >
  </c-space>
</template>
<style scoped>
.slider-custom-handle {
  display: flex;
  align-items: center;
  justify-content: center;
  width: 28px;
  height: 28px;
  border: 1px solid currentColor;
  border-radius: 50%;
  background: white;
  transform: translate(-6px, -6px);
}
</style>
```

## Interaction and control

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                    | Related examples                 |
| ------------- | ---------------------------------------------------------- | -------------------------------- |
| `aria-label`  | Name, or separate names for range thumbs                   | Keyboard Input, Controlled Range |
| `range`       | Fixed low/high thumbs; initial reversed values are sorted  | Keyboard Input, Controlled Range |
| `step`        | Positive finite step aligned to min; max remains reachable | Keyboard Input                   |
| `marks`       | Map positions within the finite range to text              | Keyboard Input                   |
| `show-ticks`  | Show step ticks; dense ticks are reduced, up to 1000       | Keyboard Input                   |
| `show-input`  | InputNumber; Enter or blur commits via the same model      | Keyboard Input                   |

<!-- demo-config-notes:end -->

Example source: src/slider/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(30);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-slider v-model="value" v-bind="__demoState"></c-slider>
  </c-space>
</template>
```

### Keyboard Input

- `step`: Controls the allowed increment.

Example source: src/slider/__demos__/keyboard-input.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(30);
const pair = ref([20, 80]);
const marks = { 0: "0", 25: "25", 50: "50", 75: "75", 100: "100" };
</script>
<template>
  <c-space direction="column" size="32px" style="padding: 24px 12px">
    <c-slider
      v-model="value"
      :step="5"
      :marks="marks"
      show-ticks
      show-input
      aria-label="Volume"
    />
    <c-slider
      v-model="pair"
      range
      show-input
      :aria-label="['Minimum', 'Maximum']"
      :format-tooltip="(value) => value + '%'"
    />
  </c-space>
</template>
```

### Controlled Range

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/slider/__demos__/controlled-range.vue

```vue
<script setup>
import { ref } from "vue";

const accepted = ref([30, 70]);
const proposed = ref(50);
</script>
<template>
  <c-space direction="column" size="28px" style="padding: 24px 12px">
    <c-slider
      v-model="accepted"
      range
      show-tooltip="always"
      :aria-label="['Minimum', 'Maximum']"
    />
    <c-slider
      :model-value="50"
      aria-label="Controlled rejection"
      @update:model-value="proposed = $event"
    />
    <output>{{ proposed }}</output>
    <c-slider :default-value="40" readonly aria-label="Read only" />
    <c-slider :default-value="40" disabled aria-label="Disabled" />
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Prop                                     | Description                                                                                                             | Type                             | Default        |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------- | -------------- |
| model-value                              | Controlled value; range uses a tuple                                                                                    | `SliderValue`                    | —              |
| default-value                            | Initial uncontrolled value                                                                                              | `SliderValue`                    | `0`            |
| min / max                                | Finite bounds; numeric strings are accepted. Invalid values fall back to 0/100. max<=min blocks interaction             | `number \| string`               | `0 / 100`      |
| step                                     | Positive finite step aligned to min; max remains reachable                                                              | `number \| string`               | `1`            |
| range                                    | Fixed low/high thumbs; initial reversed values are sorted                                                               | `boolean`                        | `false`        |
| orientation                              | Horizontal/vertical axis of the slider track and interaction, default horizontal; not the direction of value increments | `horizontal \| vertical`         | `horizontal`   |
| disabled / readonly / error              | Inherits applicable FormItem/Form state when omitted; readonly is focusable but cannot change values                    | `boolean`                        | Inherited      |
| show-ticks                               | Show step ticks; dense ticks are reduced, up to 1000                                                                    | `boolean`                        | `false`        |
| marks                                    | Map positions within the finite range to text                                                                           | `Record<number,string>`          | —              |
| show-input                               | InputNumber; Enter or blur commits via the same model                                                                   | `boolean`                        | `false`        |
| show-tooltip                             | true on hover/focus/drag, false hidden, always persistent                                                               | `boolean \| 'always'`            | `true`         |
| format-tooltip                           | Formats tooltip and aria-valuetext                                                                                      | `(value:number)=>string\|number` | Original value |
| aria-label                               | Name, or separate names for range thumbs                                                                                | `string \| [string,string]`      | —              |
| active-color / track-color / thumb-color | Active track/background/thumb fill colors                                                                               | `string`                         | CSS variable   |
| label-color / label-text-color           | Tooltip background/text colors                                                                                          | `string`                         | CSS variable   |
| track-height / thumb-size                | Track thickness/thumb diameter in numeric px or CSS lengths; invalid values retain theme defaults                       | `number \| string`               | CSS variable   |

### Behavior and keyboard

Arrows adjust by step, PageUp/PageDown by 10 steps, Home/End reach available endpoints. Range-thumb ARIA min/max follow the other thumb. When overlapping, clicks left/down separate the lower thumb, right/up the upper thumb. Keyboard events inside interactive thumb content are not intercepted. Readonly retains focus/tooltips; disabled leaves the Tab sequence.

Pointer Events unify mouse, touch and pen. pointerup commits final coordinates; pointercancel/lost capture ends the latest proposal. Disabling, unmounting or KeepAlive deactivation cleans listeners/capture and stops value events. Horizontal sliders allow vertical page scrolling; vertical sliders allow horizontal scrolling.

Controlled display changes only after parent updates; normalization does not emit automatically. change/update:model-value report distinct proposals; end includes the final proposal without guaranteeing acceptance. Each keyboard/numeric-input operation has start/end; a drag has one pair. Internal InputNumber does not duplicate Form validation. label-visible is removed; use show-tooltip without a compatibility alias.

### Events

| Event              | Arguments     | Meaning                                               |
| ------------------ | ------------- | ----------------------------------------------------- |
| update:model-value | `SliderValue` | Request an update                                     |
| change             | `SliderValue` | Distinct numeric proposal paired with the model event |
| start              | —             | Interaction starts                                    |
| end                | `SliderValue` | Final proposal when interaction ends                  |

### Slots / Methods

The button slot receives `{ currentValue:number,index:number }`. Custom content retains keyboard, ARIA and tooltip behavior. focus(index=0) focuses thumbs in display order; blur() removes focus.

Exports SliderProps, SliderValue, SliderOrientation, SliderTooltipFormatter, SliderTooltipVisibility, SliderEmits, SliderSlots, SliderExpose, SliderInstance and runtime sliderProps. Component bodies/styles are independently copied; installation/Form integration remain local to each library.

### Style variables

| Variable                         | Default                                |
| -------------------------------- | -------------------------------------- |
| `--c-slider-active-color`        | `var(--c-sys-color-content-brand)`     |
| `--c-slider-track-color`         | `var(--c-sys-color-state-hover)`       |
| `--c-slider-thumb-color`         | `var(--c-sys-color-surface-default)`   |
| `--c-slider-thumb-border-color`  | `var(--c-sys-color-content-brand)`     |
| `--c-slider-text-color`          | `var(--c-sys-color-content-secondary)` |
| `--c-slider-tooltip-background`  | `var(--c-sys-color-surface-tooltip)`   |
| `--c-slider-tooltip-color`       | `var(--c-sys-color-content-on-dark)`   |
| `--c-slider-error-color`         | `var(--c-sys-color-content-danger)`    |
| `--c-slider-disabled-color`      | `var(--c-sys-color-content-disabled)`  |
| `--c-slider-track-height`        | `4px`                                  |
| `--c-slider-thumb-size`          | `16px`                                 |
| `--c-slider-control-height`      | `var(--c-sys-control-height-md)`       |
| `--c-slider-font-size`           | `var(--c-sys-font-size-sm)`            |
| `--c-slider-gap`                 | `var(--c-sys-space-4)`                 |
| `--c-slider-radius`              | `var(--c-sys-radius-md)`               |
| `--c-slider-transition-duration` | `var(--c-sys-motion-duration-fast)`    |
| `--c-slider-input-width`         | `80px`                                 |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/space.md

<!-- Source: src/space/README.en-US.md; locale: en-US; page: /en/components/space/ -->

# Space

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Example source: src/space/__demos__/basic.vue

```vue
<template>
  <c-space>
    <div>Space:</div>
    <c-tag v-if="false">Tag</c-tag>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
  </c-space>
</template>
```

## Appearance and states

### Size

- `size`: Controls the component size.

Example source: src/space/__demos__/size.vue

```vue
<template>
  <div>
    <div style="margin-bottom: 20px">
      <c-radio-group v-model="size" type="button">
        <c-radio value="xs">xs</c-radio>
        <c-radio value="sm">sm</c-radio>
        <c-radio value="md">md</c-radio>
        <c-radio value="lg">lg</c-radio>
        <c-radio value="xl">xl</c-radio>
      </c-radio-group>
    </div>
    <c-space :size="size">
      <c-button status="primary">Item1</c-button>
      <c-button status="primary">Item2</c-button>
      <c-button status="primary">Item3</c-button>
    </c-space>
  </div>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue'
export default defineComponent({
  setup() {
    const size = ref('md')

    return {
      size,
    }
  },
})
</script>
```

## Layout and arrangement

### Vertical

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `direction` | Row/column order of children, default row; column stacks them vertically. Does not use horizontal/vertical values | Vertical, Align, Layout Lab |
| `align` | Cross-axis alignment: `flex-start`, `flex-end`, `center`, `stretch` or `baseline`. When omitted, inferred from `direction`: `row` → `center`, `column` → `stretch` | Align, Layout Lab |
| `wrap` | Whether to exceed the line break | Wrap, Split |
| `size` | Gap: `xs`/`sm`/`md`/`lg`/`xl` or `[rowGap, columnGap]`, supporting CSS lengths and shorthand | Split, Layout Lab |
| `justify` | Main axis arrangement, Can be set to `flex-start` `flex-end` `center` `space-around` `space-between` `space-evenly` | Layout Lab |
<!-- demo-config-notes:end -->


- `direction`: Controls the content direction.

Example source: src/space/__demos__/vertical.vue

```vue
<template>
  <c-space direction="column">
    <c-button status="primary" long>Item1</c-button>
    <c-button status="primary" long>Item2</c-button>
    <c-button status="primary" long>Item3</c-button>
  </c-space>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  })
</script>
```

### Align

- `direction`: Controls the content direction.
- `align`: Controls alignment on the cross axis.

Example source: src/space/__demos__/align.vue

```vue
<template>
  <c-space direction="column" align="stretch">
    <c-space direction="column">
      <c-radio-group v-model="direction">
        <c-radio value="row">row</c-radio>
        <c-radio value="column">column</c-radio>
      </c-radio-group>
      <c-radio-group v-model="align">
        <c-radio value="flex-start">flex-start</c-radio>
        <c-radio value="flex-end">flex-end</c-radio>
        <c-radio value="center">center</c-radio>
        <c-radio value="stretch">stretch</c-radio>
        <c-radio value="baseline">baseline</c-radio>
      </c-radio-group>
    </c-space>
    <c-space :align="align" :direction="direction" style="padding: 10px; background-color: var(--color-fill-2)">
      <div>Space:</div>
      <c-button status="primary">Item2</c-button>
      <c-card title="Card"> Card content </c-card>
    </c-space>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const direction = ref('row')
const align = ref('center')
</script>
```

### Wrap

Example source: src/space/__demos__/wrap.vue

```vue
<template>
  <c-space wrap>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
    <c-button status="primary">Item3</c-button>
    <c-button status="primary">Item4</c-button>
    <c-button status="primary">Item5</c-button>
    <c-button status="primary">Item6</c-button>
    <c-button status="primary">Item7</c-button>
    <c-button status="primary">Item8</c-button>
    <c-button status="primary">Item9</c-button>
    <c-button status="primary">Item10</c-button>
    <c-button status="primary">Item11</c-button>
    <c-button status="primary">Item12</c-button>
    <c-button status="primary">Item13</c-button>
    <c-button status="primary">Item14</c-button>
    <c-button status="primary">Item15</c-button>
    <c-button status="primary">Item16</c-button>
    <c-button status="primary">Item17</c-button>
    <c-button status="primary">Item18</c-button>
    <c-button status="primary">Item19</c-button>
    <c-button status="primary">Item20</c-button>
  </c-space>
</template>
<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({})
</script>
```

### Split

- `size`: Controls the component size.

Example source: src/space/__demos__/split.vue

```vue
<template>
  <c-radio-group v-model="size">
    <c-radio value="xs">xs</c-radio>
    <c-radio value="sm">sm</c-radio>
    <c-radio value="md">md</c-radio>
    <c-radio value="lg">lg</c-radio>
    <c-radio value="xl">xl</c-radio>
  </c-radio-group>
  <br />
  <br />
  通过 divider 组件实现分割，并且通过 inset 和 spacing 调整分割线尺寸。
  <br />
  <br />
  <c-space :size="size" wrap>
    <template #split>
      <c-divider orientation="vertical" inset="md" spacing="0" />
    </template>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
    <c-button status="primary">Item3</c-button>
    <c-button status="primary">Item4</c-button>
    <c-button status="primary">Item5</c-button>
    <c-button status="primary">Item6</c-button>
    <c-button status="primary">Item7</c-button>
    <c-button status="primary">Item8</c-button>
    <c-button status="primary">Item9</c-button>
    <c-button status="primary">Item10</c-button>
  </c-space>
  <br />
  通过自定义分割内容实现分割。
  <br />
  <br />
  <c-space :size="size" wrap>
    <template #split> <div>/</div> </template>
    <c-button status="primary">Item1</c-button>
    <c-button status="primary">Item2</c-button>
    <c-button status="primary">Item3</c-button>
    <c-button status="primary">Item4</c-button>
    <c-button status="primary">Item5</c-button>
    <c-button status="primary">Item6</c-button>
    <c-button status="primary">Item7</c-button>
    <c-button status="primary">Item8</c-button>
    <c-button status="primary">Item9</c-button>
    <c-button status="primary">Item10</c-button>
  </c-space>
</template>
<script lang="ts" setup>
import { ref } from 'vue'
const size = ref('md')
</script>
```

### Layout Lab

- `direction`: Controls the content direction.
- `size`: Controls the component size.

Example source: src/space/__demos__/layout-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoLayout = __demoReactive({
  direction: "row",
  align: "flex-start",
  justify: "flex-start",
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="direction">
        <c-radio-group
          v-model="__demoLayout['direction']"
          aria-label="direction"
          :options="[
            { label: 'row', value: 'row' },
            { label: 'column', value: 'column' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="align">
        <c-radio-group
          v-model="__demoLayout['align']"
          aria-label="align"
          :options="[
            { label: 'flex-start', value: 'flex-start' },
            { label: 'flex-end', value: 'flex-end' },
            { label: 'center', value: 'center' },
            { label: 'baseline', value: 'baseline' },
            { label: 'stretch', value: 'stretch' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="justify">
        <c-select
          v-model="__demoLayout['justify']"
          :clearable="false"
          :options="[
            { label: 'flex-start', value: 'flex-start' },
            { label: 'flex-end', value: 'flex-end' },
            { label: 'center', value: 'center' },
            { label: 'space-around', value: 'space-around' },
            { label: 'space-between', value: 'space-between' },
            { label: 'space-evenly', value: 'space-evenly' },
          ]"
          aria-label="justify"
        />
      </c-form-item>
    </c-form>
    <c-space v-bind="__demoLayout">
      <div>Space:</div>
      <c-tag v-if="false">Tag</c-tag>
      <c-button status="primary">Item1</c-button>
      <c-button status="primary">Item2</c-button>
    </c-space>
  </c-space>
</template>
```

### Split wrapping and content state

Change wrapping, direction and order after typing a draft. A separator stays with its preceding item and may appear at a line end.

Example source: src/space/__demos__/split-wrapping.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const wrap = ref(true)
const direction = ref<'row' | 'column'>('row')
const items = ref(['A', 'B', 'C'])
</script>
<template>
  <c-space wrap :size="8">
    <c-button data-space-toggle-wrap @click="wrap = !wrap">换行 / Wrap</c-button>
    <c-button data-space-toggle-direction @click="direction = direction === 'row' ? 'column' : 'row'">方向 / Direction</c-button>
    <c-button data-space-reorder @click="items = [...items].reverse()">重排 / Reorder</c-button>
  </c-space>
  <p>输入草稿后切换布局或重排，文字仍跟随对应项。Drafts stay with their items.</p>
  <div style="max-width: 100%; overflow: auto">
    <c-space data-space-split-demo :size="12" :wrap="wrap" :direction="direction" style="width: 260px; max-width: 100%">
      <template v-for="item in items" :key="item">
        <label class="space-split-field">
          <span>Item {{ item }}</span>
          <input :aria-label="'Draft ' + item" placeholder="草稿 / Draft" />
        </label>
      </template>
      <template #split><span aria-hidden="true">/</span></template>
    </c-space>
  </div>
  <p>分隔符跟随前项，允许位于行尾。Separators stay with the preceding item.</p>
</template>
<style scoped>
.space-split-field {
  display: inline-flex;
  flex-direction: column;
  gap: 4px;
  width: 110px;
}
.space-split-field input {
  min-width: 0;
  width: 100%;
  box-sizing: border-box;
}
</style>
```

## Interaction and control

### Interactive Layout

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `wrap` | Whether to exceed the line break | Interactive Layout |
| `size` | Gap: `xs`/`sm`/`md`/`lg`/`xl` or `[rowGap, columnGap]`, supporting CSS lengths and shorthand | Interactive Layout |
| `direction` | Row/column order of children, default row; column stacks them vertically. Does not use horizontal/vertical values | Interactive Layout |
<!-- demo-config-notes:end -->


- `size`: Controls the component size.
- `direction`: Controls the content direction.

Example source: src/space/__demos__/interactive-layout.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const direction = ref<'row' | 'column'>('row')
const gap = ref(8)
const wrap = ref(false)
const count = ref(3)
</script>

<template>
  <div>
    <c-space wrap :size="8">
      <c-button @click="direction = direction === 'row' ? 'column' : 'row'">Toggle direction</c-button>
      <c-button @click="gap = gap === 8 ? 24 : 8">Toggle gap</c-button>
      <c-button @click="wrap = !wrap">Toggle wrap</c-button>
      <c-button :disabled="count >= 6" @click="count++">Add item</c-button>
      <c-button :disabled="count <= 1" @click="count--">Remove item</c-button>
    </c-space>
    <p aria-live="polite">{{ direction }} / gap {{ gap }} / wrap {{ wrap }} / items {{ count }}</p>
    <div style="max-width: 100%; overflow: auto">
      <c-space data-demo-layout :direction="direction" :size="[8, gap]" :wrap="wrap" style="width: 260px; max-width: 100%">
        <div v-for="item in count" :key="item" style="width: 72px; padding: 8px; box-sizing: border-box; border: 1px solid currentColor">Item {{ item }}</div>
      </c-space>
    </div>
  </div>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"`. Row layout follows reading order; column layout stays top to bottom. Flex-start/flex-end follows the corresponding flex axis. The size pair always means [rowGap,columnGap], including in RTL. Wrapping and split slots preserve content order. Direction changes do not reverse data or recreate children with stable keys.

## API

### Children and size boundaries

Keyed Fragment groups preserve their local child identity when reordered. Pure whitespace, empty text, comments and empty Fragments do not create spacing items; visible text, zero and empty elements remain. Empty split content also produces no separator item.

With wrap and split, separators stay with their preceding item. This permits trailing separators at line ends; it does not suppress separators at every line boundary. Items wider than the available line may still overflow. Without wrap, the existing Flex gap and justify allocation are unchanged. Layout switches preserve content nodes.

block switches the container between flex and inline-flex. align=stretch stretches item wrappers, not every control inside them: use the child control's block option or width:100% when required.

Invalid size shapes, negative/nonfinite numbers or tuples without exactly two lengths fall back to md and receive development diagnostics. Tuple entries are lengths, not presets. CSS var/calc expressions remain supported; CSS grammar and resolved values belong to the browser.


### Space Props

### Props

| Arguments | Description | Type | Default |
| --------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---------------------- |
| direction | Row/column order of children, default row; column stacks them vertically. Does not use horizontal/vertical values | _string_ | `row` |
| justify | Main axis arrangement, Can be set to `flex-start` `flex-end` `center` `space-around` `space-between` `space-evenly` | _string_ | `flex-start` |
| align | Cross-axis alignment: `flex-start`, `flex-end`, `center`, `stretch` or `baseline`. When omitted, inferred from `direction`: `row` → `center`, `column` → `stretch` | _string_ | `-` |
| size | Gap: `xs`/`sm`/`md`/`lg`/`xl` or `[rowGap, columnGap]`, supporting CSS lengths and shorthand | _string \| number \| [string \| number, string \| number]_ | `md` |
| wrap | Whether to exceed the line break | _boolean_ | `false` |
| block | Whether to use a flex container | _boolean_ | `true` |

### Slots

| Slot | Description | Arguments |
| --------- | ---------- | ---- |
| `default` | Content of space | `-` |
| `split` | Range separator | `-` |

### Type definitions

```ts
import type { SpaceProps, SpaceSize, SpaceDirection, SpaceAlign, SpaceJustify, SpaceInternalSize, SpaceInstance } from '@cedar-design/ui'
```

### Style variables

| Variable | Default |
| --- | --- |
| `--c-space-size-xs-row-gap` | `var(--c-sys-space-2)` |
| `--c-space-size-xs-column-gap` | `var(--c-sys-space-2)` |
| `--c-space-size-sm-row-gap` | `var(--c-sys-space-4)` |
| `--c-space-size-sm-column-gap` | `var(--c-sys-space-3)` |
| `--c-space-size-md-row-gap` | `var(--c-sys-space-5)` |
| `--c-space-size-md-column-gap` | `var(--c-sys-space-4)` |
| `--c-space-size-lg-row-gap` | `var(--c-sys-space-6)` |
| `--c-space-size-lg-column-gap` | `var(--c-sys-space-5)` |
| `--c-space-size-xl-row-gap` | `var(--c-sys-space-8)` |
| `--c-space-size-xl-column-gap` | `var(--c-sys-space-6)` |

## Shared implementation and platform boundaries

Each platform maintains complete local source without a common core or shared instances/reactive state. Update both implementations together. Read-only parity checks cover bodies, props, child flattening, main styles, size tokens and paired tests. Only installation entries/namespaces are adapted locally.

Both default to `size="md"`, `wrap=false`, `block=true` and `direction="row"`. Omitted align means center for row and stretch for column. Maple callers previously relying on default wrapping must add `wrap` explicitly.

`size` supports all five presets, numbers/numeric strings in px, CSS lengths/expressions such as 1rem or var(--gap), and `[rowGap, columnGap]`. Arrays are always row then column; direction does not swap them. Array entries are lengths, not preset names. Shared [row,column] presets: xs=[4,4], sm=[8,6], md=[12,8], lg=[16,12], xl=[24,16] px, overridable through CSS variables.

---

Document: llms/en-US/components/split-button.md

<!-- Source: src/split-button/README.en-US.md; locale: en-US; page: /en/components/split-button/ -->

# Split Button

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `placement`: Chooses the position relative to the trigger.

Example source: src/split-button/__demos__/basic.vue

```vue
<script setup lang="ts">
import { Message } from "@cedar-design/ui";

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-split-button
    placement="bottom-end"
    @click="publish"
    @select="handleSelect"
  >
    发布

    <template #content>
      <c-menu-option label="保存草稿" value="draft" />
      <c-menu-option label="保存并发布" value="publish" />
      <c-menu-option label="暂无权限" value="restricted" disabled />
    </template>
  </c-split-button>
</template>
```

## Appearance and states

### Variants

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `variant` | Button group variant | Variants |
| `disabled` | Whether the entire split button is disabled | Disabled |
| `button-props` | Props for the primary button | Disabled |
| `trigger-button-props` | Props for the menu trigger button | Disabled |
| `placement` | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Appearance configuration comparison |
<!-- demo-config-notes:end -->


- `variant`: Selects the visual variant.

Example source: src/split-button/__demos__/variants.vue

```vue
<script setup lang="ts">
import { Message } from "@cedar-design/ui";

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
const variants = ["default", "outline", "tonal", "text"] as const;
</script>

<template>
  <c-space wrap>
    <c-split-button
      v-for="variant in variants"
      :key="variant"
      :variant="variant"
      @click="publish"
      @select="handleSelect"
    >
      {{ variant }}

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
  </c-space>
</template>
```

### Disabled

- `disabled`: Prevents user interaction.

Example source: src/split-button/__demos__/disabled.vue

```vue
<script setup lang="ts">
import { Message } from "@cedar-design/ui";

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-space wrap>
    <c-split-button
      disabled
      :button-props="{ disabled: false }"
      :trigger-button-props="{ disabled: false }"
      @click="publish"
      @select="handleSelect"
    >
      整体禁用

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <c-split-button
      :button-props="{ disabled: true }"
      @click="publish"
      @select="handleSelect"
    >
      仅禁用主按钮

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <c-split-button
      :trigger-button-props="{ disabled: true }"
      @click="publish"
      @select="handleSelect"
    >
      仅禁用菜单按钮

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
  </c-space>
</template>
```

### Appearance configuration comparison

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/split-button/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive } from "vue";
import type { ComponentSize, SemanticStatus } from "../../_utils/constant";
import { Message } from "@cedar-design/ui";
const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
const __demoAppearance = reactive<{ status: SemanticStatus; size: ComponentSize }>({
  status: "default",
  size: "md",
});

import { computed as demoComputed, ref as demoRef } from 'vue'

const demoCompareFields = [{"name":"status","values":["default","primary","secondary","tertiary","info","success","warning","danger"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("status")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" align="flex-start" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'secondary', value: 'secondary' },
            { label: 'tertiary', value: 'tertiary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-split-button
      placement="bottom-end"
      @click="publish"
      @select="handleSelect"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    >
      发布

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Content and presentation

### Popup

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `placement` | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Popup |
| `offset-y` | Screen-vertical offset; numbers are px, strings are converted as lengths | Popup |
| `popup-max-height` | Maximum menu height | Popup |
| `hide-on-select` | Close the menu after selection | Popup |
<!-- demo-config-notes:end -->


- `placement`: Chooses the position relative to the trigger.

Example source: src/split-button/__demos__/popup.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import { Message } from "@cedar-design/ui";

const lastAction = ref("");
const handleSelect = (value: unknown, option: { label?: unknown }) => {
  lastAction.value = String(value);
  Message.info(String(option.label));
};
</script>

<template>
  <c-space direction="column" align="flex-start">
    <c-split-button
      placement="bottom-start"
      :offset-y="8"
      :popup-max-height="160"
      :hide-on-select="false"
      @click="lastAction = 'publish'"
      @select="handleSelect"
    >
      选择操作
      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <span aria-live="polite">最近操作: {{ lastAction || "暂无操作" }}</span>
    <span>选择后菜单保持展开，可连续选择；点击外部关闭。</span>
  </c-space>
</template>
```

## Customization and slots

### Custom Icon

Preview configuration: `label="保存草稿"`, `value="draft"`, `label="保存并发布"`, `value="publish"`.

Example source: src/split-button/__demos__/custom-icon.vue

```vue
<script setup lang="ts">
import { Message } from "@cedar-design/ui";

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-split-button @click="publish" @select="handleSelect">
    发布
    <template #icon="{ open }">
      <c-icon-menu-down
        :style="{
          transform: open ? 'rotate(180deg)' : undefined,
          transition: 'transform 0.2s',
        }"
      />
    </template>
    <template #content>
      <c-menu-option label="保存草稿" value="draft" />
      <c-menu-option label="保存并发布" value="publish" />
      <c-menu-option label="暂无权限" value="restricted" disabled />
    </template>
  </c-split-button>
</template>
```

## Interaction and control

### Controlled

Preview configuration: `v-model:open="open"`, `label="保存草稿"`, `value="draft"`, `label="保存并发布"`.

Example source: src/split-button/__demos__/controlled.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import { Message } from "@cedar-design/ui";

const publish = () => {
  Message.info("发布成功");
};
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
const open = ref(false);
</script>

<template>
  <c-space direction="column" align="flex-start">
    <c-space wrap>
      <c-button @click.stop="open = true">展开菜单</c-button>
      <c-button @click.stop="open = false">关闭菜单</c-button>
    </c-space>
    <c-split-button v-model:open="open" @click="publish" @select="handleSelect">
      发布

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <span aria-live="polite">{{ open ? "已展开" : "已关闭" }}</span>
  </c-space>
</template>
```

## Async and dynamic data

### Async Action

click is a normal emitted event and supports async handlers. Business state controls loading; restore it in finally. Listener Promises do not automatically drive loading. Disabled/loading links have no effective href.

Example source: src/split-button/__demos__/async-action.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import { Message } from "@cedar-design/ui";

const completed = ref(0);
const publishing = ref(false)
const publish = async () => {
  if (publishing.value) return
  publishing.value = true
  try {
    await new Promise<void>((resolve) => setTimeout(resolve, 800))
    completed.value += 1
    Message.info('发布成功 / Published')
  } finally { publishing.value = false }
}
const handleSelect = (_value: unknown, option: { label?: unknown }) => {
  Message.info(String(option.label));
};
</script>

<template>
  <c-space direction="column" align="flex-start">
    <c-split-button :button-props="{ loading: publishing }" @click="publish" @select="handleSelect">
      发布

      <template #content>
        <c-menu-option label="保存草稿" value="draft" />
        <c-menu-option label="保存并发布" value="publish" />
        <c-menu-option label="暂无权限" value="restricted" disabled />
      </template>
    </c-split-button>
    <span aria-live="polite">完成次数: {{ completed }}</span>
  </c-space>
</template>
```

## Reading direction

The primary action sits at reading start and the menu button at reading end. Direction changes neither swap actions nor select a value. Enter/Space retains native button behavior. Up/Down opens the menu and skips disabled items; Home/End focuses boundaries, Enter selects and Escape closes and restores focus. Popovers inherit the reference direction; start/end alignment follows reading direction while explicit left/right remains physical. Downward slot graphics are not mirrored.

## API

### `<split-button>` Props

| Parameter | Description | Type | Default |
| -------------------- | ----------------------------------------- | ------------------------------------------------ | :-------: |
| open **(v-model)** | Whether the menu is open | `boolean` | `-` |
| default-open | Default menu open state in uncontrolled mode | `boolean` | `false` |
| disabled | Whether the entire split button is disabled | `boolean` | `false` |
| status | Button group semantic status | `SemanticStatus` | `default` |
| variant | Button group variant | `ButtonVariant` | `default` |
| size | Button group size | `ComponentSize` | `md` |
| color | Background color | `string` | `''` |
| text-color | Custom text color | `string` | `''` |
| elevation | Button group elevation | `boolean \| number` | `true` |
| button-props | Props for the primary button | `Partial<ButtonProps>` | `-` |
| trigger-button-props | Props for the menu trigger button | `Partial<ButtonProps>` | `-` |
| trigger | Menu trigger method | `'hover' \| 'click' \| 'focus' \| 'contextMenu'` | `click` |
| placement | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `MenuPlacement`: the standard twelve placements | `bottom` |
| popup-container | Menu mount container | `PopupContainer` | `-` |
| popup-max-height | Maximum menu height | `boolean \| number` | `true` |
| popup-class | Menu popup class | `string \| array \| object` | `-` |
| offset-x | Screen-horizontal offset; numbers are px, strings are converted as lengths | `string \| number` | `0` |
| offset-y | Screen-vertical offset; numbers are px, strings are converted as lengths | `string \| number` | `0` |
| hide-on-select | Close the menu after selection | `boolean` | `true` |

### `<split-button>` Events

| Event | Description | Arguments |
| ----------- | -------------------------- | -------------------- |
| update:open | Emitted when an open-state update is requested | open: `boolean` |
| open-change | Emitted when the menu open state changes | open: `boolean` |
| click | Emitted when the primary button is clicked | event: `MouseEvent` |
| select | Emitted when a menu option is selected | value, option, event |

### `<split-button>` Slots

| Slot | Description | Arguments |
| ------- | ---------------- | --------------- |
| default | Primary button content | - |
| icon | Menu trigger button icon | open: `boolean` |
| content | Menu content | - |

### Instance methods

| Method | Description |
| -------- | -------------------------- |
| open() | Request menu opening; disabled prevents it |
| close() | Request menu closing |
| resize() | Recalculate menu position |

Controlled `open` emits update requests only; callers must update it. Main-button clicks bubble normally without opening the menu.

Like Button, `click` is a Promise-consuming `onClick` callback prop supporting `@click`, not a second emitted notification. If `button-props.onClick` is also supplied, each handler runs once.

Both platforms independently copy bodies, props, style dependency entries and contract tests. Cedar adapts positioning through Menu without shared instances/runtime.

## Type definitions

```ts
import type { SplitButtonInstance, SplitButtonProps } from '@cedar-design/ui'
```


### Placement semantics and configuration

The menu side passes through the internal Menu placement to Trigger and uses MenuPlacement, without a second positioning entry.

---

Document: llms/en-US/components/split.md

<!-- Source: src/split/README.en-US.md; locale: en-US; page: /en/components/split/ -->

# Split

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `size`: The size of the segmentation, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px
- `min`: Minimum threshold, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px

Example source: src/split/__demos__/basic.vue

```vue
<template>
  <div>
    <c-split
      :style="{
        height: '200px',
        width: '100%',
        minWidth: '500px',
        border: '1px solid var(--c-color-border-2)',
      }"
      v-model:size="size"
      min="80px"
    >
      <template #first>
        <c-typography-paragraph>Left</c-typography-paragraph>
      </template>
      <template #second>
        <c-typography-paragraph>Right</c-typography-paragraph>
      </template>
    </c-split>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const size = ref(0.5)
</script>
```

## Layout and arrangement

### Nested

- `orientation`: Direction of division

Example source: src/split/__demos__/nested.vue

```vue
<template>
  <div>
    <c-split
      :style="{
        height: '200px',
        width: '100%',
        minWidth: '500px',
        border: '1px solid var(--color-border)',
      }"
    >
      <template #first>
        <c-typography-paragraph>Left</c-typography-paragraph>
      </template>
      <template #second>
        <div>
          <c-split orientation="vertical" :style="{ height: '200px' }">
            <template #first>
              <c-typography-paragraph>Top</c-typography-paragraph>
            </template>
            <template #second>
              <c-typography-paragraph>Bottom</c-typography-paragraph>
            </template>
          </c-split>
        </div>
      </template>
    </c-split>
  </div>
</template>

<script lang="ts" setup>
</script>
```

## API

### `<split>` Props

| Parameter | Description | Type | Default |
| ------------------ | ----------------------------------------------------------------- | ---------------------------- | :------------: |
| component | The html tag of the split box | `string` | `'div'` |
| orientation | Arrangement axis of the two panels: horizontal by default means left/right panels, whose divider handle is vertical | `'horizontal' \| 'vertical'` | `'horizontal'` |
| size **(v-model)** | The size of the segmentation, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px | `number\|string` | `-` |
| default-size | Default split size, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px | `number\|string` | `0.5` |
| min | Minimum threshold, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px | `number\|string` | `-` |
| max | Maximum threshold, it can be 0~1 representing a percentage, or a specific number of pixels, such as 300px | `number\|string` | `-` |
| disabled | Whether disabled | `boolean` | `false` |

### `<split>` Events

| Event | Description | Arguments |
| ---------- | ---------------- | ---- |
| move-start | Emitted before dragging starts | - |
| moving | Emitted during dragging | - |
| move-end | Emitted after dragging ends | - |

### `<split>` Slots

| Slot | Description | Arguments |
| ------------------- | :--------------: | ---- |
| first | First panel content | - |
| resize-trigger | Resize-handle content | - |
| resize-trigger-icon | Resize-handle icon | - |
| second | Second panel content | - |

### Type definitions

The component exports the following types

```ts
import type { SplitInstance } from '@cedar-design/ui'
```

`--c-split-trigger-size-icon-wrapper` (default 6px) controls handle thickness: width for vertical handles, height for horizontal handles. It does not change their 100% length along the panel.


## Reading direction and interaction

Split inherits the nearest native dir. Size and bounds always describe the first pane, preserving ratio or pixel units. In RTL, dragging left grows the first horizontal pane; vertical movement is unchanged. Focused separators support arrows, Shift, Home and End. Direction/orientation changes, disablement and teardown cancel gestures and restore the cursor without changing the size merely because direction changed.

---

Document: llms/en-US/components/statistic.md

<!-- Source: src/statistic/README.en-US.md; locale: en-US; page: /en/components/statistic/ -->

# Statistic

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `title="Downloads"`, `:value="125670"`, `show-group-separator`, `title="Comments"`.

Example source: src/statistic/__demos__/basic.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Downloads" :value="125670" show-group-separator />
    <c-statistic title="Comments" extra="Compared to yesterday" :value="40509" :precision="2" />
    <c-statistic title="Active Users" value="1.28k" />
  </c-space>
</template>
```

## Content and presentation

### Tabular Nums

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Displayed-value title | Tabular Nums, Extra, Animation |
| `value` | Displayed value | Tabular Nums, Extra, Animation |
| `suffix` | Value suffix | Tabular Nums |
| `value-style` | Custom style of the value | Tabular Nums |
| `tabular-nums` | Use tabular digits to prevent width changes as values update | Tabular Nums |
| `prefix` | Value prefix | Extra |
<!-- demo-config-notes:end -->


Preview configuration: `title="比例数字（右侧标记会跳动）"`, `:value="count"`, `suffix="\|"`, `:value-style="{ fontVariantNumeric: 'proportional-nums' }"`.

Example source: src/statistic/__demos__/tabular-nums.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic
      title="比例数字（右侧标记会跳动）"
      :value="count"
      suffix="|"
      :value-style="{ fontVariantNumeric: 'proportional-nums' }"
    />
    <c-statistic title="等宽数字（右侧标记保持稳定）" :value="count" suffix="|" tabular-nums />
  </c-space>
</template>

<script lang="ts" setup>
import { onBeforeUnmount, onMounted, ref } from 'vue'

const values = [1111, 8888, 1010, 9090]
const index = ref(0)
const count = ref(values[0])
let timer = 0

onMounted(() => {
  timer = window.setInterval(() => {
    index.value = (index.value + 1) % values.length
    count.value = values[index.value]
  }, 800)
})

onBeforeUnmount(() => {
  window.clearInterval(timer)
})
</script>
```

### Extra

Preview configuration: `title="Revenue"`, `:value="9280"`, `prefix="$"`, `show-group-separator`.

Example source: src/statistic/__demos__/extra.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Revenue" :value="9280" prefix="$" show-group-separator extra="Compared to yesterday +12.8%" />
    <c-statistic title="New Users" :value="1280" show-group-separator>
      <template #extra>
        <span style="color: var(--c-color-success)">较上周 +8.4%</span>
      </template>
    </c-statistic>
  </c-space>
</template>
```

### Animation

Preview configuration: `title="Growth Rate"`, `:value="50.52"`, `:precision="2"`, `:value-from="0"`.

Example source: src/statistic/__demos__/animation.vue

```vue
<template>
  <c-space size="xl" align="flex-end" wrap>
    <c-statistic
      title="Growth Rate"
      :value="50.52"
      :precision="2"
      :value-from="0"
      :start="started"
      animation
    >
      <template #prefix>
        <IconArrowRise />
      </template>
      <template #suffix>%</template>
    </c-statistic>
    <c-button status="primary" @click="started = true">Start</c-button>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
import { IconArrowRise } from '@cedar-design/icons-vue'

const started = ref(false)
</script>
```

### Statistic

Preview configuration: `title="Countdown"`, `:time="2 * 60 * 60 * 1000"`, `title="Campaign"`, `:time="4 * 24 * 60 * 60 * 1000"`.

Example source: src/countdown/__demos__/statistic.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Countdown">
      <c-countdown :time="2 * 60 * 60 * 1000" />
    </c-statistic>
    <c-statistic title="Campaign">
      <c-countdown :time="4 * 24 * 60 * 60 * 1000" format="DD 天 HH 时 mm 分 ss 秒" />
    </c-statistic>
  </c-space>
</template>
```

## Customization and slots

### Prefix Suffix

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `title` | Displayed-value title | Prefix Suffix, Count To |
| `suffix` | Value suffix | Prefix Suffix, Count To |
| `value` | Displayed value | Prefix Suffix |
| `prefix` | Value prefix | Prefix Suffix |
| `show-group-separator` | Whether to show the group separator | Prefix Suffix |
| `precision` | Decimal places (number mode) | Prefix Suffix |
<!-- demo-config-notes:end -->


Preview configuration: `title="Account Balance"`, `:value="125670"`, `prefix="$"`, `show-group-separator`.

Example source: src/statistic/__demos__/prefix-suffix.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Account Balance" :value="125670" prefix="$" show-group-separator />
    <c-statistic title="Growth Rate" :value="12.8" :precision="1" suffix="%" :value-style="{ color: 'var(--c-color-success)' }">
      <template #prefix>
        <IconArrowRise />
      </template>
    </c-statistic>
    <c-statistic title="Bounce Rate" :value="3.2" :precision="1" suffix="%" :value-style="{ color: 'var(--c-color-danger)' }">
      <template #prefix>
        <IconArrowFall />
      </template>
    </c-statistic>
  </c-space>
</template>

<script lang="ts" setup>
import { IconArrowFall, IconArrowRise } from '@cedar-design/icons-vue'
</script>
```

### Count To

Preview configuration: `title="Active Users"`, `:from="0"`, `:to="125670"`, `:duration="2000"`.

Example source: src/statistic/__demos__/count-to.vue

```vue
<template>
  <c-space size="xl" wrap>
    <c-statistic title="Active Users">
      <c-count-to :from="0" :to="125670" :duration="2000" />
    </c-statistic>
    <c-statistic title="Conversion Rate" suffix="%">
      <c-count-to :from="0" :to="36.8" :duration="2000" :precision="1" />
    </c-statistic>
  </c-space>
</template>
```

## API

### `<Statistic>` Props

| Prop | Description | Type | Default |
| ---------------------- | -------------------------------------------------------------- | ------------------------- | ------------ |
| `title` | Displayed-value title | `string` | - |
| `value` | Displayed value | `number \| string \| Date` | - |
| `prefix` | Value prefix | `string` | - |
| `suffix` | Value suffix | `string` | - |
| `format` | Date format (date mode) | `string` | `'HH:mm:ss'` |
| `extra` | Extra content | `string` | - |
| `start` | Whether to start the animation | `boolean` | `true` |
| `precision` | Decimal places (number mode) | `number` | `0` |
| `separator` | Group separator (number mode) | `string` | - |
| `show-group-separator` | Whether to show the group separator | `boolean` | `false` |
| `tabular-nums` | Use tabular digits to prevent width changes as values update | `boolean` | `false` |
| `animation` | Whether to enable animation | `boolean` | `false` |
| `animation-duration` | Animation duration | `number` | `2000` |
| `value-from` | Animation start value | `number` | - |
| `placeholder` | Placeholder when `value` is `undefined` and the default slot is unused | `string` | - |
| `value-style` | Custom style of the value | `CSSProperties` | - |

### `<Statistic>` Slots

| Slot | Description | Arguments |
| --------- | ---------------------------------------- | ---- |
| `default` | Custom `value`, used when `value` is not provided | `-` |
| `title` | Title | `-` |
| `prefix` | The prepend icon of alert | `-` |
| `suffix` | Suffix | `-` |
| `extra` | Extra content | `-` |

### Type definitions

The component exports the following types

```ts
import type { StatisticProps } from '@cedar-design/ui'
```

### Style variables

| Variable | Default |
| --- | --- |
| `--c-statistic-title-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-title-font-size` | `var(--c-font-size-body-3)` |
| `--c-statistic-title-margin-bottom` | `var(--c-spacing-4)` |
| `--c-statistic-value-color` | `var(--c-sys-color-content-primary)` |
| `--c-statistic-value-font-size` | `26px` |
| `--c-statistic-value-font-weight` | `var(--c-font-weight-500)` |
| `--c-statistic-decimal-font-size` | `inherit` |
| `--c-statistic-prefix-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-prefix-font-size` | `14px` |
| `--c-statistic-prefix-spacing` | `var(--c-spacing-1)` |
| `--c-statistic-suffix-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-suffix-font-size` | `14px` |
| `--c-statistic-suffix-spacing` | `var(--c-spacing-1)` |
| `--c-statistic-extra-color` | `var(--c-sys-color-content-secondary)` |
| `--c-statistic-extra-font-size` | `var(--c-font-size-body-3)` |
| `--c-statistic-extra-margin-top` | `var(--c-spacing-4)` |

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Placeholder text updates when the default slot appears/disappears. Animation pauses on unmount/KeepAlive deactivation.

---

Document: llms/en-US/components/steps.md

<!-- Source: src/steps/README.en-US.md; locale: en-US; page: /en/components/steps/ -->

# Steps

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `status`: Selects the semantic state.

Example source: src/steps/__demos__/basic.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps :status="currentStatus">
    <c-step description="This is a description">Succeeded</c-step>
    <c-step description="This is a description">Processing</c-step>
    <c-step description="This is a description">Pending</c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

## Appearance and states

### Appearance Lab

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `type` | Steps appearance type | Step types and states |
| `status` | Current step status | Step types and states |
| `changeable` | Whether clicking can change steps | Step types and states |
<!-- demo-config-notes:end -->


Preview configuration: `layout="vertical"`, `aria-label="status"`, `options`, `variant="button"`.

Example source: src/steps/__demos__/appearance-lab.vue

```vue
<script setup lang="ts">
import { reactive as __demoReactive } from "vue";
const __demoAppearance = __demoReactive({ status: "wait", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"status","values":["wait","process","finish","error"]},{"name":"size","values":["sm","md"]}]
const demoCompareAxis = demoRef("status")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="status">
        <c-radio-group
          v-model="__demoAppearance['status']"
          aria-label="status"
          :options="[
            { label: 'wait', value: 'wait' },
            { label: 'process', value: 'process' },
            { label: 'finish', value: 'finish' },
            { label: 'error', value: 'error' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-steps :model-value="2" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">
      <c-step>Succeeded</c-step>
      <c-step>Processing</c-step>
      <c-step>Pending</c-step>
    </c-steps>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### Step types and states

All four types share one current-step and status model. Click a step or select 1–3, then choose wait, process, finish or error: default, arrow, dot and navigation update together. Status changes the current node’s semantic state without changing its index. Titles and descriptions follow the page language to fit the phone preview.

<details>
<summary>Configuration details and limits</summary>

#### Types

Preview configuration: `aria-label="Current step"`, `options`, `variant="button"`, `size="sm"`.

#### Error

- `status`: Selects the semantic state.

#### Arrow

- `status`: Selects the semantic state.

#### Dot

- `status`: Selects the semantic state.

#### Navigation

- `status`: Selects the semantic state.

</details>

Example source: src/steps/__demos__/types.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { StepsType } from "@cedar-design/ui";

const current = ref(2)
const statuses = ['wait', 'process', 'finish', 'error'] as const
const status = ref<(typeof statuses)[number]>('process')
const types: StepsType[] = ["default", "arrow", "dot", "navigation"];
</script>

<template>
  <section class="step-type-comparison">
    <c-form-item layout="vertical" size="sm" label="Current step">
      <c-radio-group
        v-model="current"
        aria-label="Current step"
        :options="[
          { label: '1', value: 1 },
          { label: '2', value: 2 },
          { label: '3', value: 3 },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-form-item layout="vertical" size="sm" label="Status"><c-radio-group v-model="status" aria-label="Step status" :options="statuses.map(value => ({ label: value, value }))" /></c-form-item>
    <p>
      点击步骤或选择序号，对比同一进度的四种外观。Click a step to compare the
      same progress.
    </p>
    <section v-for="type in types" :key="type" :data-step-type="type">
      <p>
        <code>{{ type }}</code>
      </p>
      <c-steps v-model="current" :type="type" :status="status" changeable>
        <c-step><span lang="zh-CN">提交</span><span lang="en-US">Submit</span><template #description><span lang="zh-CN">提交信息</span><span lang="en-US">Details</span></template></c-step>
        <c-step><span lang="zh-CN">审核</span><span lang="en-US">Review</span><template #description><span lang="zh-CN">审核信息</span><span lang="en-US">Review</span></template></c-step>
        <c-step><span lang="zh-CN">完成</span><span lang="en-US">Done</span><template #description><span lang="zh-CN">完成信息</span><span lang="en-US">Complete</span></template></c-step>
      </c-steps>
    </section>
  </section>
</template>

<style scoped>
html:not([lang='en-US']) .step-type-comparison [lang='en-US'],
html[lang='en-US'] .step-type-comparison [lang='zh-CN'] { display: none; }
</style>
```

## Layout and arrangement

### Content Placement

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Current step status | Content Placement, Vertical |
| `content-placement` | Content side relative to the step node: right or bottom, default right. Dot steps derive it from orientation; navigation steps always use right | Content Placement |
| `orientation` | Horizontal/vertical axis of the step flow, default horizontal; arrow and navigation variants remain horizontal | Vertical |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/steps/__demos__/content-placement.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps content-placement="bottom" :status="currentStatus">
    <c-step description="This is a description">Succeeded</c-step>
    <c-step description="This is a description">Processing</c-step>
    <c-step description="This is a description">Pending</c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

### Vertical

- `status`: Selects the semantic state.

Example source: src/steps/__demos__/vertical.vue

```vue
<template>
  <div class="frame-bg">
    <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
      <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
    </c-radio-group>
    <div class="frame-body">
      <div class="frame-aside">
        <c-steps :model-value="current" :status="currentStatus" orientation="vertical">
          <c-step>Succeeded</c-step>
          <c-step>Processing</c-step>
          <c-step>Pending</c-step>
        </c-steps>
      </div>
      <div class="frame-main">
        <div class="main-content">The content of this step.</div>
        <div class="main-bottom">
          <c-button :disabled="current === 1" @click="onPrev">
            <c-icon-left />
            Back
          </c-button>
          <c-button :disabled="current === 3" @click="onNext">
            Next
            <c-icon-right />
          </c-button>
        </div>
      </div>
    </div>
  </div>
</template>
<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const current = ref(1)
    const statuses = ['wait', 'process', 'finish', 'error'] as const
    const currentStatus = ref<(typeof statuses)[number]>('process')

    const onPrev = () => {
      current.value = Math.max(1, current.value - 1)
    }

    const onNext = () => {
      current.value = Math.min(3, current.value + 1)
    }

    return {
      current,
      statuses,
      currentStatus,
      onPrev,
      onNext,
    }
  },
}
</script>
```

## Content and presentation

### Description

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `status` | Current step status | Description, Line Less |
| `show-line` | Whether to show connectors | Line Less |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/steps/__demos__/description.vue

```vue
<template>
  <c-radio-group
    v-model="currentStatus"
    variant="button"
    style="margin-bottom: 16px"
  >
    <c-radio v-for="status in statuses" :key="status" :value="status">{{
      status
    }}</c-radio>
  </c-radio-group>
  <c-steps :model-value="2" :status="currentStatus">
    <c-step>Succeeded</c-step>
    <c-step>Processing</c-step>
    <c-step>Pending</c-step>
  </c-steps>
  <c-divider />
  <div style="line-height: 140px; color: #c9cdd4; text-align: center">
    Step 2 Content
  </div>
</template>
<script setup lang="ts">
import { ref } from "vue";

const statuses = ["wait", "process", "finish", "error"] as const;
const currentStatus = ref<(typeof statuses)[number]>("process");
</script>
```

### Line Less

- `status`: Selects the semantic state.

Example source: src/steps/__demos__/line-less.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps :model-value="2" :status="currentStatus" :show-line="false">
    <c-step description="This is a description">Succeeded</c-step>
    <c-step description="This is a description">Processing</c-step>
    <c-step description="This is a description">Pending</c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

## Customization and slots

### Custom Icon

- `status`: Selects the semantic state.

Example source: src/steps/__demos__/custom-icon.vue

```vue
<template>
  <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
    <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
  </c-radio-group>
  <c-steps :status="currentStatus">
    <c-step description="This is a description">
      Succeeded
      <template #icon>
        <c-icon-home />
      </template>
    </c-step>
    <c-step description="This is a description">
      Processing
      <template #icon>
        <c-icon-loading />
      </template>
    </c-step>
    <c-step description="This is a description">
      Pending
      <template #icon>
        <c-icon-thumb-up />
      </template>
    </c-step>
  </c-steps>
</template>
<script setup lang="ts">
import { ref } from 'vue'

const statuses = ['wait', 'process', 'finish', 'error'] as const
const currentStatus = ref<(typeof statuses)[number]>('process')
</script>
```

## Interaction and control

### Changeable

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `changeable` | Whether clicking can change steps | Changeable |
| `status` | Current step status | Changeable |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.

Example source: src/steps/__demos__/changeable.vue

```vue
<template>
  <div>
    <c-radio-group v-model="currentStatus" variant="button" style="margin-bottom: 16px">
      <c-radio v-for="status in statuses" :key="status" :value="status">{{ status }}</c-radio>
    </c-radio-group>
    <c-steps changeable :model-value="current" :status="currentStatus" @change="setCurrent">
      <c-step description="This is a description">Succeeded</c-step>
      <c-step description="This is a description">Processing</c-step>
      <c-step description="This is a description">Pending</c-step>
    </c-steps>
    <div
      :style="{
        width: '100%',
        height: '200px',
        textAlign: 'center',
        background: 'var(--color-bg-2)',
        color: '#C2C7CC',
      }"
    >
      <div style="line-height: 160px">Step{{ current }} Content</div>
      <c-space size="lg">
        <c-button status="secondary" :disabled="current <= 1" @click="onPrev">
          <c-icon-left />
          Back
        </c-button>
        <c-button status="primary" :disabled="current >= 3" @click="onNext">
          Next
          <c-icon-right />
        </c-button>
      </c-space>
    </div>
  </div>
</template>
<script lang="ts">
import { ref } from 'vue'

export default {
  setup() {
    const current = ref(1)
    const statuses = ['wait', 'process', 'finish', 'error'] as const
    const currentStatus = ref<(typeof statuses)[number]>('process')
    const onPrev = () => {
      current.value = Math.max(1, current.value - 1)
    }
    const onNext = () => {
      current.value = Math.min(3, current.value + 1)
    }

    const setCurrent = (step: number) => {
      current.value = step
    }

    return {
      current,
      statuses,
      currentStatus,
      onPrev,
      onNext,
      setCurrent,
    }
  },
}
</script>
```

## API

Use ordinary `v-model`. `modelValue` is the current step, starting at 1. `defaultValue` initializes uncontrolled state once; later changes do not reset it. Initialization emits no `update:modelValue`. When supplied, `modelValue` is controlled by the parent.

### Steps Props

| Prop | Description | Type | Default |
| -------------------- | ------------------------ | ----------------------------------------------------- | -------------- |
| type | Steps appearance type | `'default'` \| `'arrow'` \| `'dot'` \| `'navigation'` | `'default'` |
| orientation | Horizontal/vertical axis of the step flow, default horizontal; arrow and navigation variants remain horizontal | `'horizontal'` \| `'vertical'` | `'horizontal'` |
| content-placement | Content side relative to the step node: right or bottom, default right. Dot steps derive it from orientation; navigation steps always use right | `'right'` \| `'bottom'` | `'right'` |
| model-value(**v-model**) | Current step number | `number` | `-` |
| default-value | Default uncontrolled step number | `number` | `1` |
| status | Current step status | `'wait'` \| `'process'` \| `'finish'` \| `'error'` | `'process'` |
| show-line | Whether to show connectors | `boolean` | `true` |
| size | Steps size | `'sm'` \| `'md'` | `'md'` |
| changeable | Whether clicking can change steps | `boolean` | `false` |

### Steps Events

| Event | Description | Arguments |
| ------------------- | ------------------------------ | ---------------------------- |
| change | Emitted when the step number changes; requires `changeable` | current:`number`<br/>previous:`number`<br/>ev:`Event` |
| update:modelValue | `v-model` sync | step:`number` |

### Steps Slots

| Slot | Description |
| ----------- | ------------ |
| default | Step content |
| finish-icon | Finished status icon |
| error-icon | Error status icon |

### Step Props

| Prop | Description | Type | Default |
| ----------- | ------------ | -------------------------------------------------- | ------- |
| title | Step title | `string` | `-` |
| description | Step description | `string` | `-` |
| status | Step status | `'wait'` \| `'process'` \| `'finish'` \| `'error'` | `-` |
| disabled | Whether the step is disabled | `boolean` | `false` |

### Step Slots

| Slot | Description | Arguments |
| ----------- | ---- | --------------------------------- |
| default | Title | `index`、`status`、`active`、`disabled` |
| title | Title | `index`、`status`、`active`、`disabled` |
| node | Node | `index`、`status`、`active`、`disabled` |
| icon | Icon | `index`、`status`、`active`、`disabled` |
| description | Description | `index`、`status`、`active`、`disabled` |

## Type definitions

The component exports the following types

```ts
import type {
  StepsProps,
  StepProps,
  StepsType,
  StepStatus,
  StepsSize,
  StepsContentPlacement,
  StepsInstance,
  StepsStepInstance,
} from '@cedar-design/ui'
```

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Steps/Step bodies, props, context protocol and styles are source copies. Injection Symbols are defined separately per library, not shared. The four types and existing status/event contracts remain.

`active` indicates only whether the current one-based step index matches modelValue, independently of wait/process/finish/error status. A current error step remains `active`. Focus/hover do not change `active`.


### Placement semantics and configuration

content-placement shares side vocabulary and spelling, not an identical set across all components. Steps implements only right/bottom; dot and navigation variants have derived rules. Unsupported sides are not added for naming uniformity.


## Reading direction and keyboard interaction

Steps inherits the nearest native `dir` and supports live changes. Horizontal layout and directional geometry follow reading order; vertical progression stays top to bottom. With `changeable`, arrow keys move focus, Home/End reach the first/last enabled step, and Enter/Space activate it. Focus navigation and direction changes do not update progress.

---

Document: llms/en-US/components/style-provider.md

<!-- Source: src/style-provider/README.en-US.md; locale: en-US; page: /en/components/style-provider/ -->

# Style Provider

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `tag="section"`, `:style-vars="active ? { '--c-demo-color': 'teal' } : null"`, `:style-vars="{ '--c-demo-color': 'coral' }"`.

Example source: src/style-provider/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const active = ref(true)
</script>

<template>
  <div>
    <c-button variant="outline" @click="active = !active">切换局部变量 / Toggle local variables</c-button>
    <c-style-provider tag="section" :style-vars="active ? { '--c-demo-color': 'teal' } : null">
      <p style="color: var(--c-demo-color, currentColor)">局部颜色 / Local color</p>
      <c-style-provider :style-vars="{ '--c-demo-color': 'coral' }">
        <p style="color: var(--c-demo-color)">嵌套覆盖 / Nested override</p>
      </c-style-provider>
    </c-style-provider>
    <p>外部不受影响 / Outside remains unchanged</p>
  </div>
</template>
```

## Global calls

```ts
import { StyleProvider, Themes } from '@cedar-design/ui'

StyleProvider.setStyleVars(Themes.default.dark)
StyleProvider.setStyleVars(Themes.maple.light)
StyleProvider.setStyleVars(null)
```

Each call replaces previous injected values rather than merging cumulatively. Values already equal to base styles are not written again.
`dark` sets `html[cedar-theme="dark"]`; `light` removes it. Without color-scheme, existing theme attributes remain. `null` removes this library's injection/theme attributes without affecting the other library. SSR calls have no side effects.

Variables accept full CSS names or camelCase such as `cColorScheme`. Library prefixes are not added automatically. Prefer full `--c-*` names.

## Installation and defaults

```ts
import { StyleProvider } from '@cedar-design/ui'

app.use(StyleProvider)

StyleProvider.setPropsDefaults({
  tag: 'section',
  styleVars: () => ({ '--c-demo-color': 'teal' }),
})
```

Set defaults during initialization before mounting; mounted instances are not retroactively updated. Explicit props take precedence. Object defaults are copied per instance; factories/`null` are supported. Defaults are local to each library, not shared.
Installation always registers `CStyleProvider` without modifying app global config. For aliases, use `app.component('MyStyleProvider', StyleProvider)`.

## API

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| `style-vars` | Local CSS variables; null clears local overrides | `Record<string, string> \| null` | `{}` |
| `tag` | Wrapper tag | `string` | `div` |

The default slot supplies component content. No events.

## Type definitions

Exports `StyleVars`, `StyleProviderProps`, `StyleProviderDefaults` and `StyleProviderInstance`. `StyleProvider` is the only public component entry; `styleProviderProps` and resolver-facing `_StyleProviderComponent` are also exported.

No component-specific theme tokens. Variable values are strings; numeric dimensions should be unit-bearing strings.

---

Document: llms/en-US/components/style/atomic-css.md

<!-- Source: src/style/atomic-css/README.en-US.md; locale: en-US; page: /en/components/style/atomic-css/ -->

# Style Atomic Css

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Starter

Example source: src/style/atomic-css/__demos__/starter.vue

```vue
<template>
  <div class="starter-card">
    <div class="starter-title">第一张原子化卡片</div>
    <div class="starter-description">
      组合小类完成布局，不需要另外写组件样式。
    </div>

    <div class="starter-row">
      <span class="starter-tag">c-flex c-items-center c-gap-8</span>
      <span class="starter-status">Success</span>
    </div>

    <c-button class="starter-button"
      >c-bg-primary · hover:c-opacity-80</c-button
    >
  </div>
</template>

<style scoped>
/* 文档站的等价视觉预览；业务项目中的样式由 UnoCSS 或 Tailwind 生成。 */
.starter-card {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 420px;
  padding: 16px;
  border: 1px solid var(--c-color-border-2);
  border-radius: 8px;
  background: var(--c-color-body);
}

.starter-title {
  color: var(--c-color-primary);
  font-size: var(--c-font-size-lg);
  font-weight: 600;
}

.starter-description {
  color: var(--c-color-text-3);
}

.starter-row {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 8px;
  padding: 12px;
  border-radius: 6px;
  background: var(--c-color-fill-2);
}

.starter-tag {
  color: var(--c-color-text-2);
  font-family: monospace;
  font-size: 12px;
}

.starter-status {
  color: var(--c-color-success);
}

.starter-button {
  padding: 8px 16px;
  border: 0;
  border-radius: 6px;
  color: #fff;
  background: var(--c-color-primary);
  cursor: pointer;
  transition: opacity 0.2s;
}

.starter-button:hover {
  opacity: 0.8;
}
</style>
```

### Overview

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/atomic-css/__demos__/overview.vue

```vue
<template>
  <c-space direction="column" block size="md">
    <c-alert status="info">
      Preset 在构建期注入主题；固定工具类是现成 CSS。二者可同时使用。
    </c-alert>
    <c-table :columns="columns" :data="data" :pagination="false" />
  </c-space>
</template>

<script lang="ts" setup>
const columns = [
  { title: "能力", dataIndex: "kind" },
  { title: "例子", dataIndex: "example" },
  { title: "说明", dataIndex: "note" },
];

const data = [
  {
    kind: "Preset 颜色",
    example: "c-bg-primary / c-text-success",
    note: "需配置 @cedar-design/preset-*",
  },
  {
    kind: "Preset 字号",
    example: "c-text-xs / c-text-lg",
    note: "挂 --c-font-size-*",
  },
  {
    kind: "Preset 断点",
    example: "sm: / md: / lg: / xl:",
    note: "数值与设计对齐",
  },
  {
    kind: "固定 Utilities",
    example: "c-text-1 / c-fill-1",
    note: "utilities 语义色，不经 Uno/TW",
  },
];
</script>
```

## Colors, typography and spacing

### Colors

Example source: src/style/atomic-css/__demos__/colors.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <div>
      <div class="label">背景 c-bg-*</div>
      <div class="row">
        <div
          v-for="item in bgItems"
          :key="item.cls"
          class="swatch"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
    <div>
      <div class="label">文字 c-text-*</div>
      <div class="row text-row">
        <span
          v-for="item in textItems"
          :key="item.cls"
          class="text-chip"
          :style="item.style"
        >
          {{ item.cls }}
        </span>
      </div>
    </div>
    <div>
      <div class="label">边框 c-border-*</div>
      <div class="row">
        <div
          v-for="item in borderItems"
          :key="item.cls"
          class="border-chip"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const bgItems = [
  {
    cls: "c-bg-body",
    style: {
      background: "var(--c-color-body)",
      color: "var(--c-color-text-1)",
    },
  },
  {
    cls: "c-bg-primary",
    style: { background: "var(--c-color-primary)", color: "#fff" },
  },
  {
    cls: "c-bg-info",
    style: { background: "var(--c-color-info)", color: "#fff" },
  },
  {
    cls: "c-bg-success",
    style: { background: "var(--c-color-success)", color: "#fff" },
  },
  {
    cls: "c-bg-warning",
    style: { background: "var(--c-color-warning)", color: "#fff" },
  },
  {
    cls: "c-bg-danger",
    style: { background: "var(--c-color-danger)", color: "#fff" },
  },
  {
    cls: "c-bg-disabled",
    style: {
      background: "var(--c-color-disabled)",
      color: "var(--c-color-text-1)",
    },
  },
];

const textItems = [
  { cls: "c-text-primary", style: { color: "var(--c-color-primary)" } },
  { cls: "c-text-info", style: { color: "var(--c-color-info)" } },
  { cls: "c-text-success", style: { color: "var(--c-color-success)" } },
  { cls: "c-text-warning", style: { color: "var(--c-color-warning)" } },
  { cls: "c-text-danger", style: { color: "var(--c-color-danger)" } },
  { cls: "c-text-disabled", style: { color: "var(--c-color-disabled)" } },
];

const borderItems = [
  { cls: "c-border-primary", style: { borderColor: "var(--c-color-primary)" } },
  { cls: "c-border-info", style: { borderColor: "var(--c-color-info)" } },
  { cls: "c-border-success", style: { borderColor: "var(--c-color-success)" } },
  { cls: "c-border-warning", style: { borderColor: "var(--c-color-warning)" } },
  { cls: "c-border-danger", style: { borderColor: "var(--c-color-danger)" } },
];
</script>

<style scoped lang="scss">
.label {
  margin-bottom: 8px;
  color: var(--c-color-text-3);
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.swatch {
  min-width: 110px;
  padding: 10px 12px;
  border-radius: 4px;
  border: 1px solid var(--c-color-border-2);
  font-size: 12px;
  text-align: center;
}

.text-row {
  gap: 16px;
  align-items: center;
}

.text-chip {
  font-size: 14px;
  font-weight: 500;
}

.border-chip {
  min-width: 110px;
  padding: 10px 12px;
  border-width: 2px;
  border-style: solid;
  border-radius: 4px;
  text-align: center;
}
</style>
```

### Font Size

Example source: src/style/atomic-css/__demos__/font-size.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div
      v-for="item in items"
      :key="item.className"
      class="line"
      :style="{ fontSize: item.size }"
    >
      <code class="tag">{{ item.className }}</code>
      <span>Cedar Design — {{ item.label }}</span>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const items = [
  { label: "xs / 10px", className: "c-text-xs", size: "var(--c-font-size-xs)" },
  { label: "sm / 12px", className: "c-text-sm", size: "var(--c-font-size-sm)" },
  { label: "md / 14px", className: "c-text-md", size: "var(--c-font-size-md)" },
  { label: "lg / 16px", className: "c-text-lg", size: "var(--c-font-size-lg)" },
];
</script>

<style scoped lang="scss">
.line {
  display: flex;
  flex-wrap: wrap;
  align-items: baseline;
  gap: 8px;
  color: var(--c-color-text-1);
}

.tag {
  font-size: 12px;
  padding: 2px 6px;
  border-radius: 4px;
  background: var(--c-color-fill-2);
  color: var(--c-color-text-2);
}
</style>
```

### Spacing

Example source: src/style/atomic-css/__demos__/spacing.vue

```vue
<template>
  <div class="spacing-demo">
    <div class="spacing-row">
      <code>c-p-4 · 4px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-4">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-8 · 8px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-8">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-16 · 16px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-p-16">内容</div>
      </div>
    </div>
    <div class="spacing-row">
      <code>c-px-24 c-py-8 · 24px / 8px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-px-24 c-py-8">内容</div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.spacing-demo {
  display: grid;
  gap: 16px;
}

.spacing-row {
  display: grid;
  grid-template-columns: minmax(210px, 1fr) 2fr;
  align-items: center;
  gap: 16px;
}

.spacing-stage {
  background: var(--c-color-fill-2);
  border-radius: 4px;
}

.spacing-box {
  width: fit-content;
  color: #fff;
  background: var(--c-color-primary);
}

/* 文档站未接入 preset 时的等价预览，业务项目由 Uno / Tailwind 生成。 */
.c-p-4 {
  padding: 4px;
}
.c-p-8 {
  padding: 8px;
}
.c-p-16 {
  padding: 16px;
}
.c-px-24 {
  padding-right: 24px;
  padding-left: 24px;
}
.c-py-8 {
  padding-top: 8px;
  padding-bottom: 8px;
}

@media (max-width: 600px) {
  .spacing-row {
    grid-template-columns: 1fr;
    gap: 8px;
  }
}
</style>
```

## Responsive layout and composition

### Breakpoints

Preview configuration: `:columns="columns"`, `:data="rows"`, `:pagination="false"`.

Example source: src/style/atomic-css/__demos__/breakpoints.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div class="hint">
      缩小浏览器窗口可观察当前命中的断点；类名形如
      <code>sm:c-bg-info</code>。
    </div>
    <div class="box">
      <div class="label">当前 ≥</div>
      <strong class="value">{{ active }}</strong>
    </div>
    <c-table :columns="columns" :data="rows" :pagination="false" />
  </c-space>
</template>

<script lang="ts" setup>
import { computed, onMounted, onUnmounted, ref } from "vue";

const width = ref(typeof window !== "undefined" ? window.innerWidth : 0);

const onResize = () => {
  width.value = window.innerWidth;
};

onMounted(() => {
  width.value = window.innerWidth;
  window.addEventListener("resize", onResize);
});

onUnmounted(() => {
  window.removeEventListener("resize", onResize);
});

const active = computed(() => {
  const w = width.value;
  if (w >= 1920) return "xl (1920px)";
  if (w >= 1200) return "lg (1200px)";
  if (w >= 992) return "md (992px)";
  if (w >= 768) return "sm (768px)";
  return "base (< sm)";
});

const columns = [
  { title: "前缀", dataIndex: "prefix" },
  { title: "最小宽度", dataIndex: "min" },
  { title: "示例类", dataIndex: "cls" },
];

const rows = [
  { prefix: "sm:", min: "768px", cls: "sm:c-bg-info" },
  { prefix: "md:", min: "992px", cls: "md:c-bg-warning" },
  { prefix: "lg:", min: "1200px", cls: "lg:c-bg-danger" },
  { prefix: "xl:", min: "1920px", cls: "xl:c-bg-success" },
];
</script>

<style scoped lang="scss">
.hint {
  font-size: 13px;
  color: var(--c-color-text-3);
}

.box {
  display: flex;
  align-items: baseline;
  gap: 8px;
  padding: 12px 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
}

.label {
  opacity: 0.85;
  font-size: 13px;
}

.value {
  font-size: 18px;
}
</style>
```

### Combined

Example source: src/style/atomic-css/__demos__/combined.vue

```vue
<template>
  <div class="demo">
    <div class="card body">
      <div class="title">c-bg-body + c-text-md</div>
      <div class="row">
        <span class="primary">c-text-primary</span>
        <span class="success">c-text-success</span>
        <span class="danger">c-text-danger</span>
      </div>
      <div class="banner">
        <div class="banner-inner">
          c-bg-primary · Uno / TW <code>c-text-lg</code>
          <div class="sub">
            叠加：sm:c-bg-info → md:c-bg-warning → lg:c-bg-danger →
            xl:c-bg-success
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped lang="scss">
.demo {
  font-size: var(--c-font-size-md);
}

.card {
  padding: 16px;
  border-radius: 8px;
  border: 1px solid var(--c-color-border-2);
}

.body {
  background: var(--c-color-body);
  color: var(--c-color-text-1);
}

.title {
  margin-bottom: 12px;
  font-weight: 600;
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  margin-bottom: 16px;
}

.primary {
  color: var(--c-color-primary);
}

.success {
  color: var(--c-color-success);
}

.danger {
  color: var(--c-color-danger);
}

.banner {
  padding: 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
  font-size: var(--c-font-size-lg);

  @media (min-width: 768px) {
    background: var(--c-color-info);
  }

  @media (min-width: 992px) {
    background: var(--c-color-warning);
  }

  @media (min-width: 1200px) {
    background: var(--c-color-danger);
  }

  @media (min-width: 1920px) {
    background: var(--c-color-success);
  }
}

.sub {
  margin-top: 6px;
  font-size: var(--c-font-size-sm);
  opacity: 0.9;
}

code {
  font-size: 12px;
  opacity: 0.95;
}
</style>
```

## UnoCSS

### Installation

```shell
pnpm add -D @cedar-design/preset-unocss unocss
```

### Configuration

```js
// uno.config.ts
import { defineConfig } from "unocss";
import { presetCedar } from "@cedar-design/preset-unocss";

export default defineConfig({
  presets: [presetCedar()],
});
```

Optional `presetCedar({ colors, fontSize, breakpoints })`; `false` disables a section.

### Load theme variables first

```js
import "@cedar-design/ui/dist/index.css";
// Or import a theme stylesheet containing --c-* variables
```

---

## Tailwind CSS

### Installation

```shell
pnpm add -D @cedar-design/preset-tailwindcss tailwindcss
```

### Tailwind v3

```js
// tailwind.config.js
import { presetCedar } from "@cedar-design/preset-tailwindcss";

export default {
  content: ["./index.html", "./src/**/*.{vue,js,ts,jsx,tsx}"],
  presets: [presetCedar()],
};
```

### Tailwind v4

```js
// tailwind.config.js
import { presetCedar } from "@cedar-design/preset-tailwindcss";

export default {
  presets: [presetCedar()],
};
```

```css
/* src/style.css */
@import "tailwindcss";
@config '../tailwind.config.js';
```

---

See [Common patterns](llms/en-US/components/style/atomic-usage.md) for all Flex/spacing/sizing/overflow/radius classes. Only utilities mapped to Cedar tokens are listed below.

## Optional configuration

```js
presetCedar({
  colors: true, // or false / partial key overrides
  fontSize: true, // false disables it; custom fontSize maps are accepted
  // Uno:
  breakpoints: true,
  // TW:
  // screens: true,
});
```

### Custom theme mapping

`colors`/`fontSize` may override part of the defaults; omitted keys retain default mappings:

```js
presetCedar({
  colors: {
    primary: "var(--app-color-brand)",
    danger: "var(--app-color-error)",
  },
  fontSize: {
    md: "15px",
  },
});
```

`false` disables the corresponding Cedar theme mapping. Generator-native utilities may still exist but no longer bind Cedar variables.

---

## Corresponding Maple configuration

Maple's UnoCSS preset includes `presetUno` with an `mp-` prefix:

```js
import { defineConfig } from "unocss";
import { presetMaple } from "@nio-pow/maple-preset-unocss";

export default defineConfig({
  presets: [presetMaple()],
});
```

Both Maple UnoCSS/Tailwind presets generate `mp-bg-primary`, `mp-text-primary` and `mp-border mp-border-primary` without unprefixed aliases.

Tailwind `prefix` is global; one Tailwind instance should not load Cedar/Maple presets with different prefixes simultaneously.

---

## Notes

- The preset includes the framework's full atomic classes with `c-` prefixes, e.g. `c-flex`/`c-p-16`.
- Classes must start with `c-`, e.g. `c-bg-primary`; no unprefixed aliases.
- Choose UnoCSS or Tailwind CSS; do not enable both generators in one app.
- Cedar/Maple share theme key names. Even with different UnoCSS utility prefixes, avoid merging both themes in one config or matching colors may overwrite by preset order.

---

Document: llms/en-US/components/style/atomic-usage.md

<!-- Source: src/style/atomic-usage/README.en-US.md; locale: en-US; page: /en/components/style/atomic-usage/ -->

# Style Atomic Usage

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Combined

Example source: src/style/atomic-css/__demos__/combined.vue

```vue
<template>
  <div class="demo">
    <div class="card body">
      <div class="title">c-bg-body + c-text-md</div>
      <div class="row">
        <span class="primary">c-text-primary</span>
        <span class="success">c-text-success</span>
        <span class="danger">c-text-danger</span>
      </div>
      <div class="banner">
        <div class="banner-inner">
          c-bg-primary · Uno / TW <code>c-text-lg</code>
          <div class="sub">
            叠加：sm:c-bg-info → md:c-bg-warning → lg:c-bg-danger →
            xl:c-bg-success
          </div>
        </div>
      </div>
    </div>
  </div>
</template>

<style scoped lang="scss">
.demo {
  font-size: var(--c-font-size-md);
}

.card {
  padding: 16px;
  border-radius: 8px;
  border: 1px solid var(--c-color-border-2);
}

.body {
  background: var(--c-color-body);
  color: var(--c-color-text-1);
}

.title {
  margin-bottom: 12px;
  font-weight: 600;
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  margin-bottom: 16px;
}

.primary {
  color: var(--c-color-primary);
}

.success {
  color: var(--c-color-success);
}

.danger {
  color: var(--c-color-danger);
}

.banner {
  padding: 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
  font-size: var(--c-font-size-lg);

  @media (min-width: 768px) {
    background: var(--c-color-info);
  }

  @media (min-width: 992px) {
    background: var(--c-color-warning);
  }

  @media (min-width: 1200px) {
    background: var(--c-color-danger);
  }

  @media (min-width: 1920px) {
    background: var(--c-color-success);
  }
}

.sub {
  margin-top: 6px;
  font-size: var(--c-font-size-sm);
  opacity: 0.9;
}

code {
  font-size: 12px;
  opacity: 0.95;
}
</style>
```

## Spacing and responsive layout

### Spacing

Example source: src/style/atomic-css/__demos__/spacing.vue

```vue
<template>
  <div class="spacing-demo">
    <div class="spacing-row">
      <code>c-p-4 · 4px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-4">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-8 · 8px</code>
      <div class="spacing-stage"><div class="spacing-box c-p-8">内容</div></div>
    </div>
    <div class="spacing-row">
      <code>c-p-16 · 16px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-p-16">内容</div>
      </div>
    </div>
    <div class="spacing-row">
      <code>c-px-24 c-py-8 · 24px / 8px</code>
      <div class="spacing-stage">
        <div class="spacing-box c-px-24 c-py-8">内容</div>
      </div>
    </div>
  </div>
</template>

<style scoped>
.spacing-demo {
  display: grid;
  gap: 16px;
}

.spacing-row {
  display: grid;
  grid-template-columns: minmax(210px, 1fr) 2fr;
  align-items: center;
  gap: 16px;
}

.spacing-stage {
  background: var(--c-color-fill-2);
  border-radius: 4px;
}

.spacing-box {
  width: fit-content;
  color: #fff;
  background: var(--c-color-primary);
}

/* 文档站未接入 preset 时的等价预览，业务项目由 Uno / Tailwind 生成。 */
.c-p-4 {
  padding: 4px;
}
.c-p-8 {
  padding: 8px;
}
.c-p-16 {
  padding: 16px;
}
.c-px-24 {
  padding-right: 24px;
  padding-left: 24px;
}
.c-py-8 {
  padding-top: 8px;
  padding-bottom: 8px;
}

@media (max-width: 600px) {
  .spacing-row {
    grid-template-columns: 1fr;
    gap: 8px;
  }
}
</style>
```

### Breakpoints

Preview configuration: `:columns="columns"`, `:data="rows"`, `:pagination="false"`.

Example source: src/style/atomic-css/__demos__/breakpoints.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div class="hint">
      缩小浏览器窗口可观察当前命中的断点；类名形如
      <code>sm:c-bg-info</code>。
    </div>
    <div class="box">
      <div class="label">当前 ≥</div>
      <strong class="value">{{ active }}</strong>
    </div>
    <c-table :columns="columns" :data="rows" :pagination="false" />
  </c-space>
</template>

<script lang="ts" setup>
import { computed, onMounted, onUnmounted, ref } from "vue";

const width = ref(typeof window !== "undefined" ? window.innerWidth : 0);

const onResize = () => {
  width.value = window.innerWidth;
};

onMounted(() => {
  width.value = window.innerWidth;
  window.addEventListener("resize", onResize);
});

onUnmounted(() => {
  window.removeEventListener("resize", onResize);
});

const active = computed(() => {
  const w = width.value;
  if (w >= 1920) return "xl (1920px)";
  if (w >= 1200) return "lg (1200px)";
  if (w >= 992) return "md (992px)";
  if (w >= 768) return "sm (768px)";
  return "base (< sm)";
});

const columns = [
  { title: "前缀", dataIndex: "prefix" },
  { title: "最小宽度", dataIndex: "min" },
  { title: "示例类", dataIndex: "cls" },
];

const rows = [
  { prefix: "sm:", min: "768px", cls: "sm:c-bg-info" },
  { prefix: "md:", min: "992px", cls: "md:c-bg-warning" },
  { prefix: "lg:", min: "1200px", cls: "lg:c-bg-danger" },
  { prefix: "xl:", min: "1920px", cls: "xl:c-bg-success" },
];
</script>

<style scoped lang="scss">
.hint {
  font-size: 13px;
  color: var(--c-color-text-3);
}

.box {
  display: flex;
  align-items: baseline;
  gap: 8px;
  padding: 12px 16px;
  border-radius: 4px;
  background: var(--c-color-primary);
  color: #fff;
}

.label {
  opacity: 0.85;
  font-size: 13px;
}

.value {
  font-size: 18px;
}
</style>
```

## Colors and typography

### Colors

Example source: src/style/atomic-css/__demos__/colors.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <div>
      <div class="label">背景 c-bg-*</div>
      <div class="row">
        <div
          v-for="item in bgItems"
          :key="item.cls"
          class="swatch"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
    <div>
      <div class="label">文字 c-text-*</div>
      <div class="row text-row">
        <span
          v-for="item in textItems"
          :key="item.cls"
          class="text-chip"
          :style="item.style"
        >
          {{ item.cls }}
        </span>
      </div>
    </div>
    <div>
      <div class="label">边框 c-border-*</div>
      <div class="row">
        <div
          v-for="item in borderItems"
          :key="item.cls"
          class="border-chip"
          :style="item.style"
        >
          <code>{{ item.cls }}</code>
        </div>
      </div>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const bgItems = [
  {
    cls: "c-bg-body",
    style: {
      background: "var(--c-color-body)",
      color: "var(--c-color-text-1)",
    },
  },
  {
    cls: "c-bg-primary",
    style: { background: "var(--c-color-primary)", color: "#fff" },
  },
  {
    cls: "c-bg-info",
    style: { background: "var(--c-color-info)", color: "#fff" },
  },
  {
    cls: "c-bg-success",
    style: { background: "var(--c-color-success)", color: "#fff" },
  },
  {
    cls: "c-bg-warning",
    style: { background: "var(--c-color-warning)", color: "#fff" },
  },
  {
    cls: "c-bg-danger",
    style: { background: "var(--c-color-danger)", color: "#fff" },
  },
  {
    cls: "c-bg-disabled",
    style: {
      background: "var(--c-color-disabled)",
      color: "var(--c-color-text-1)",
    },
  },
];

const textItems = [
  { cls: "c-text-primary", style: { color: "var(--c-color-primary)" } },
  { cls: "c-text-info", style: { color: "var(--c-color-info)" } },
  { cls: "c-text-success", style: { color: "var(--c-color-success)" } },
  { cls: "c-text-warning", style: { color: "var(--c-color-warning)" } },
  { cls: "c-text-danger", style: { color: "var(--c-color-danger)" } },
  { cls: "c-text-disabled", style: { color: "var(--c-color-disabled)" } },
];

const borderItems = [
  { cls: "c-border-primary", style: { borderColor: "var(--c-color-primary)" } },
  { cls: "c-border-info", style: { borderColor: "var(--c-color-info)" } },
  { cls: "c-border-success", style: { borderColor: "var(--c-color-success)" } },
  { cls: "c-border-warning", style: { borderColor: "var(--c-color-warning)" } },
  { cls: "c-border-danger", style: { borderColor: "var(--c-color-danger)" } },
];
</script>

<style scoped lang="scss">
.label {
  margin-bottom: 8px;
  color: var(--c-color-text-3);
}

.row {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.swatch {
  min-width: 110px;
  padding: 10px 12px;
  border-radius: 4px;
  border: 1px solid var(--c-color-border-2);
  font-size: 12px;
  text-align: center;
}

.text-row {
  gap: 16px;
  align-items: center;
}

.text-chip {
  font-size: 14px;
  font-weight: 500;
}

.border-chip {
  min-width: 110px;
  padding: 10px 12px;
  border-width: 2px;
  border-style: solid;
  border-radius: 4px;
  text-align: center;
}
</style>
```

Example source: src/style/atomic-css/__demos__/font-size.vue

```vue
<template>
  <c-space direction="column" fill size="md">
    <div
      v-for="item in items"
      :key="item.className"
      class="line"
      :style="{ fontSize: item.size }"
    >
      <code class="tag">{{ item.className }}</code>
      <span>Cedar Design — {{ item.label }}</span>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
const items = [
  { label: "xs / 10px", className: "c-text-xs", size: "var(--c-font-size-xs)" },
  { label: "sm / 12px", className: "c-text-sm", size: "var(--c-font-size-sm)" },
  { label: "md / 14px", className: "c-text-md", size: "var(--c-font-size-md)" },
  { label: "lg / 16px", className: "c-text-lg", size: "var(--c-font-size-lg)" },
];
</script>

<style scoped lang="scss">
.line {
  display: flex;
  flex-wrap: wrap;
  align-items: baseline;
  gap: 8px;
  color: var(--c-color-text-1);
}

.tag {
  font-size: 12px;
  padding: 2px 6px;
  border-radius: 4px;
  background: var(--c-color-fill-2);
  color: var(--c-color-text-2);
}
</style>
```

---

Document: llms/en-US/components/style/color.md

<!-- Source: src/style/color/README.en-US.md; locale: en-US; page: /en/components/style/color/ -->

# Style Color

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Fill

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/color/__demos__/fill.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-fill-1)",
    description: "浅/禁用",
    class: "c-fill-1",
  },
  {
    properties: "var(--c-color-fill-2)",
    description: "常规/白底悬浮",
    class: "c-fill-2",
  },
  {
    properties: "var(--c-color-fill-3)",
    description: "深/灰底悬浮",
    class: "c-fill-3",
  },
  {
    properties: "var(--c-color-fill-4)",
    description: "重/特殊场景",
    class: "c-fill-4",
  },
]);
</script>
<style lang="scss" scoped></style>
```

## Applying colors

### Border

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/color/__demos__/border.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-border-1)",
    description: "浅色",
    class: "c-color-border-1",
  },
  {
    properties: "var(--c-color-border-2)",
    description: "一般",
    class: "c-color-border-2",
  },
  {
    properties: "var(--c-color-border-3)",
    description: "深/悬浮",
    class: "c-color-border-3",
  },
  {
    properties: "var(--c-color-border-4)",
    description: "重/按钮描边",
    class: "c-color-border-4",
  },
]);
</script>
<style lang="scss" scoped></style>
```

### Text

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/color/__demos__/text.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-text-1)",
    description: "强调/正文标题、一级文字",
    class: "c-text-1",
  },
  {
    properties: "var(--c-color-text-2)",
    description: "次强调/正文标题、二级文字 图标",
    class: "c-text-2",
  },
  {
    properties: "var(--c-color-text-3)",
    description: "次要信息、三级文字",
    class: "c-text-3",
  },
  {
    properties: "var(--c-color-text-4)",
    description: "置灰禁用 / 占位",
    class: "c-text-4",
  },
]);
</script>
<style lang="scss" scoped></style>
```

### Background

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/color/__demos__/background.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from "vue";
import { columns } from "./columns";

const data = reactive([
  {
    properties: "var(--c-color-bg-white)",
    description: "顶层的白色背景",
    class: "c-bg-0",
  },
  {
    properties: "var(--c-color-bg-1)",
    description: "一般/常规",
    class: "c-bg-1",
  },
  {
    properties: "var(--c-color-bg-2)",
    description: "重/特殊场景",
    class: "c-bg-2",
  },
]);
</script>
<style lang="scss" scoped></style>
```

---

Document: llms/en-US/components/style/elevation.md

<!-- Source: src/style/elevation/README.en-US.md; locale: en-US; page: /en/components/style/elevation/ -->

# Style Elevation

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Class

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/elevation/__demos__/class.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <c-table :columns="columns" :data="data" :pagination="false" />
  </c-space>
</template>
<script lang="ts" setup>
import { h } from "vue";
import { Message } from "@cedar-design/ui";

const columns = [
  {
    title: "Class",
    dataIndex: "class",
    render: (data) => {
      return h(
        "div",
        {
          style: {
            cursor: "pointer",
          },
          onClick: () => {
            navigator.clipboard
              .writeText(data.record.class)
              .then(() => {
                Message.success("copy success");
              })
              .catch(() => {
                Message.fail("copy fail");
              });
          },
        },
        data.record.class,
      );
    },
  },
  {
    title: "Properties",
    dataIndex: "properties",
  },
];

const data = Array.from({ length: 25 }, (_, i) => ({
  class: `c-elevation--${i}`,
  properties: `Material elevation level ${i}`,
}));
</script>
```

## Shadow composition

### Demo

Example source: src/style/elevation/__demos__/demo.vue

```vue
<template>
  <c-space class="elevation-demo" :size="[24, 24]" wrap>
    <div
      v-for="level in 25"
      :key="level"
      class="elevation-item"
      :class="`c-elevation--${level - 1}`"
    >
      {{ level - 1 }}
    </div>
  </c-space>
</template>

<style lang="scss">
.elevation-demo {
  margin-top: 8px;
}

.elevation-item {
  display: flex;
  justify-content: center;
  align-items: center;
  width: 72px;
  height: 72px;
  border-radius: 4px;
  background: var(--c-color-bg-1);
}
</style>
```

---

Document: llms/en-US/components/style/typography.md

<!-- Source: src/style/typography/README.en-US.md; locale: en-US; page: /en/components/style/typography/ -->

# Style Typography

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Font

Preview configuration: `:columns="columns2"`, `:data="dataFont"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/font.vue

```vue
<template>
  <c-table :columns="columns2" :data="dataFont" :pagination="false" />
</template>
<script lang="ts" setup>
import { h } from "vue";
import { Message } from "@cedar-design/ui";

const columns2 = [
  {
    title: "Class",
    dataIndex: "class",
    render: (data) => {
      return h(
        "div",
        {
          style: {
            cursor: "pointer",
          },
          onClick: () => {
            navigator.clipboard
              .writeText(data.record.class)
              .then(() => {
                Message.success("copy success");
              })
              .catch((err) => {
                Message.fail("copy fail");
              });
          },
        },
        data.record.class,
      );
    },
  },
  {
    title: "Properties/Effective CSS",
    dataIndex: "properties",
    render: (data) => {
      return [
        h("div", {
          innerHTML: `<div>${data.record.properties.replaceAll("\n", "<br/>")}</div>`, // 等效于 v-html
        }),
        h("div", {
          class: data.record.class,
          style: "margin-top: 10px;",
          innerHTML: `<div>${data.record.effective?.replaceAll("\n", "<br/>")}</div>`, // 等效于 v-html
        }),
      ];
    },
  },
];
const dataFont = [
  {
    class: "c-text-body-2-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-1);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 12px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-body-2-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-1);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 12px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-body-1-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 14px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-body-1-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 14px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-2-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 16px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-2-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 16px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-1-regular",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-2);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 18px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "c-text-subtitle-1-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-subtitle-2);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 18px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-4-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-1);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 20px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-3-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-2);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 24px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-2-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-3);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 32px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "c-text-heading-1-semibold",
    properties:
      "font-family: var(--c-font-regular);\nfont-size: var(--c-font-size-heading-4);\nfont-weight: var(--c-font-weight-semibold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family:Auto;\nfont-size: 40px;\nfont-weight: 600;\nline-height: 1.5;",
  },
  {
    class: "text-number-7-regular",
    properties:
      "font-family: var(--c-font-number-regular);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 14px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "text-number-7-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-body-2);\nfont-weight: var(--c-font-weight-blod);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 14px;\nfont-weight: 700;\nline-height: 1.5;",
  },
  {
    class: "text-number-6-regular",
    properties:
      "font-family: var(--c-font-number-regular);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-regular);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 16px;\nfont-weight: 400;\nline-height: 1.5;",
  },
  {
    class: "text-number-6-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-subtitle-1);\nfont-weight: var(--c-font-weight-bold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 16px;\nfont-weight: 700;\nline-height: 1.5;",
  },
  {
    class: "text-number-5-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-subtitle-2);\nfont-weight: var(--c-font-weight-bold);\nline-height: var(--c-line-height-default);",
    effective:
      "font-family: Barlow;\nfont-size: 18px;\nfont-weight: 700;\nline-height: 1.5;",
  },
  {
    class: "text-number-4-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-1);\nfont-weight: var(--c-font-weight-bold);\nline-height: 24px;",
    effective:
      "font-family: Barlow;\nfont-size: 20px;\nfont-weight: 700;\nline-height: 1;",
  },
  {
    class: "text-number-3-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-2);\nfont-weight: var(--c-font-weight-bold);\nline-height: 29px;",
    effective:
      "font-family: Barlow;\nfont-size: 24px;\nfont-weight: 700;\nline-height: 1;",
  },
  {
    class: "text-number-2-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-3);\nfont-weight: var(--c-font-weight-bold);\nline-height: 38px;",
    effective:
      "font-family: Barlow;\nfont-size: 32px;\nfont-weight: 700;\nline-height: 1;",
  },
  {
    class: "text-number-1-bold",
    properties:
      "font-family: var(--c-font-number-bold);\nfont-size: var(--c-font-size-heading-4);\nfont-weight: var(--c-font-weight-bold);\nline-height: 48px;",
    effective:
      "font-family: Barlow;\nfont-size: 40px;\nfont-weight: 700;\nline-height: 1;",
  },
];
</script>

<style lang="scss">
.table-line-height-unset .c-table-td {
  line-height: unset;
}
</style>
```

## Font size and face

### Font Size

Preview configuration: `:columns="columns"`, `:data="dataSize"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/font-size.vue

```vue
<template>
  <c-table
    :columns="columns"
    :data="dataSize"
    :pagination="false"
    class="table-line-height-unset"
  />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataSize = [
  {
    class: "font-size-body-1",
    properties: "font-size: var(--c-font-size-body-1);",
    effective: "font-size: 12px;",
  },
  {
    class: "font-size-body-2",
    properties: "font-size: var(--c-font-size-body-2);",
    effective: "font-size: 14px;",
  },
  {
    class: "font-size-subtitle-1",
    properties: "font-size: var(--c-font-size-subtitle-1);",
    effective: "font-size: 16px;",
  },
  {
    class: "font-size-subtitle-2",
    properties: "font-size: var(--c-font-size-subtitle-2);",
    effective: "font-size: 18px;",
  },
  {
    class: "font-size-heading-1",
    properties: "font-size: var(--c-font-size-heading-1);",
    effective: "font-size: 20px;",
  },
  {
    class: "font-size-heading-2",
    properties: "font-size: var(--c-font-size-heading-2);",
    effective: "font-size: 24px;",
  },
  {
    class: "font-size-heading-3",
    properties: "font-size: var(--c-font-size-heading-3);",
    effective: "font-size: 32px;",
  },
  {
    class: "font-size-heading-4",
    properties: "font-size: var(--c-font-size-heading-4);",
    effective: "font-size: 40px;",
  },
  {
    class: "font-size-display-1",
    properties: "font-size: var(--c-font-size-display-1);",
    effective: "font-size: 48px;",
  },
  {
    class: "font-size-display-2",
    properties: "font-size: var(--c-font-size-display-2);",
    effective: "font-size: 56px;",
  },
];
</script>

<style lang="scss">
.table-line-height-unset .c-table-td {
  line-height: unset;
}
</style>
```

### Font Family

Preview configuration: `:columns="columns"`, `:data="dataFamily"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/font-family.vue

```vue
<template>
  <c-table :columns="columns" :data="dataFamily" :pagination="false" />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataFamily = [
  {
    class: "font-regular",
    properties: "font-family: var(--c-font-regular);",
    effective: "font-family: Auto;",
  },
  {
    class: "font-number",
    properties: "font-family: var(--c-font-number-bold);",
    effective: "font-family: Barlow-Bold;",
  },
  {
    class: "font-number-regular",
    properties: "font-family: var(--c-font-number-regular);",
    effective: "font-family: Barlow-Regular;",
  },
  {
    class: "font-number-bold",
    properties: "font-family: var(--c-font-number-bold);",
    effective: "font-family: Barlow-Bold;",
  },
];
</script>

<style lang="scss">
.table-line-height-unset .c-table-td {
  line-height: unset;
}
</style>
```

### Font Weight

Preview configuration: `:columns="columns"`, `:data="dataWeight"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/font-weight.vue

```vue
<template>
  <c-table :columns="columns" :data="dataWeight" :pagination="false" />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataWeight = [
  {
    class: "font-weight-thin",
    properties: "font-weight: var(--c-font-weight-thin);",
    effective: "font-weight: 100;",
  },
  {
    class: "font-weight-x-light",
    properties: "font-weight: var(--c-font-weight-x-light);",
    effective: "font-weight: 200;",
  },
  {
    class: "font-weight-light",
    properties: "font-weight: var(--c-font-weight-light);",
    effective: "font-weight: 300;",
  },
  {
    class: "font-weight-regular",
    properties: "font-weight: var(--c-font-weight-regular);",
    effective: "font-weight: 400;",
  },
  {
    class: "font-weight-medium",
    properties: "font-weight: var(--c-font-weight-medium);",
    effective: "font-weight: 500;",
  },
  {
    class: "font-weight-semibold",
    properties: "font-weight: var(--c-font-weight-semibold);",
    effective: "font-weight: 600;",
  },
  {
    class: "font-weight-bold",
    properties: "font-weight: var(--c-font-weight-bold);",
    effective: "font-weight: 700;",
  },
  {
    class: "font-weight-x-bold",
    properties: "font-weight: var(--c-font-weight-x-bold);",
    effective: "font-weight: 800;",
  },
  {
    class: "font-weight-xx-bold",
    properties: "font-weight: var(--c-font-weight-xx-bold);",
    effective: "font-weight: 900;",
  },
];
</script>

<style lang="scss"></style>
```

## Alignment and line height

### Text Align

Preview configuration: `:columns="columns"`, `:data="data"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/text-align.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>
<script lang="ts" setup>
import { h } from "vue";
import { Message } from "@cedar-design/ui";

const columns = [
  {
    title: "Class",
    dataIndex: "class",
    render: (data) => {
      return h(
        "div",
        {
          style: {
            cursor: "pointer",
          },
          onClick: () => {
            navigator.clipboard
              .writeText(data.record.class)
              .then(() => {
                Message.success("copy success");
              })
              .catch((err) => {
                Message.fail("copy fail");
              });
          },
        },
        data.record.class,
      );
    },
  },
  {
    title: "Effective CSS",
    dataIndex: "effective",
    render: (data) => {
      return h("div", {
        innerHTML: `<div>${data.record.effective?.replaceAll("\n", "<br/>")}</div>`, // 等效于 v-html
      });
    },
  },
];
const data = [
  {
    class: "c-text-left",
    properties: "text-align: left !important;",
    effective: "text-align: left !important;",
  },
  {
    class: "c-text-center",
    properties: "text-align: center !important;",
    effective: "text-align: center !important;",
  },
  {
    class: "c-text-right",
    properties: "text-align: right !important;",
    effective: "text-align: right !important;",
  },
  {
    class: "c-text-justify",
    properties: "text-align: justify !important;",
    effective: "text-align: justify !important;",
  },
];
</script>

<style lang="scss"></style>
```

### Line Height

Preview configuration: `:columns="columns"`, `:data="dataLineHeight"`, `:pagination="false"`.

Example source: src/style/typography/__demos__/line-height.vue

```vue
<template>
  <c-table :columns="columns" :data="dataLineHeight" :pagination="false" />
</template>
<script lang="ts" setup>
import { columns } from "./columns";

const dataLineHeight = [
  {
    class: "line-height-1",
    properties: "line-height: var(--c-line-height-default);",
    effective: "line-height: 1.5;",
  },
];
</script>

<style lang="scss"></style>
```

---

Document: llms/en-US/components/style/utilities.md

<!-- Source: src/style/utilities/README.en-US.md; locale: en-US; page: /en/components/style/utilities/ -->

# Style Utilities

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Overview

Example source: src/style/utilities/__demos__/overview.vue

```vue
<template>
  <div class="overview">
    <section class="block">
      <div class="label c-text-3">Color text</div>
      <div class="row c-flex c-items-center">
        <span class="c-text-1 c-mr-16">c-text-1</span>
        <span class="c-text-2 c-mr-16">c-text-2</span>
        <span class="c-text-3 c-mr-16">c-text-3</span>
        <span class="c-text-4">c-text-4</span>
      </div>
    </section>

    <section class="block c-mt-24">
      <div class="label c-text-3">Background</div>
      <div class="row c-flex c-items-center">
        <div class="swatch c-bg-0 border-box c-p-8 c-mr-8">c-bg-0</div>
        <div class="swatch c-bg-1 c-p-8 c-mr-8">c-bg-1</div>
        <div class="swatch c-bg-2 c-p-8">c-bg-2</div>
      </div>
    </section>

    <section class="block c-mt-24">
      <div class="label c-text-3">Spacing</div>
      <div class="spacing-stage c-fill-2 c-p-16">
        <div class="box c-fill-2 c-mt-16 c-px-8">
          <div class="inner c-bg-0">c-mt-16 c-px-8</div>
        </div>
        <div class="box c-fill-3 c-mx-16 c-py-8">
          <div class="inner c-bg-0">c-mx-16 c-py-8</div>
        </div>
        <div class="box c-fill-4 c-p-24">
          <div class="inner c-bg-0">c-p-24</div>
        </div>
      </div>
    </section>

    <section class="block c-mt-24">
      <div class="label c-text-3">Flex</div>
      <div class="c-flex c-justify-between c-items-center c-fill-2 c-p-16">
        <div class="chip c-fill-1 c-p-8">start</div>
        <div class="chip c-fill-2 c-p-8">between</div>
        <div class="chip c-fill-3 c-p-8">end</div>
      </div>
    </section>
  </div>
</template>

<script lang="ts" setup></script>

<style lang="scss" scoped>
.overview {
  font-size: 13px;
}

.label {
  margin-bottom: 8px;
}

.swatch {
  min-width: 72px;
  text-align: center;
  border: 1px solid var(--c-color-border-2);
}

.border-box {
  border: 1px solid var(--c-color-border-2);
}

.spacing-stage {
  display: flex;
  flex-wrap: wrap;
  gap: 8px;
}

.box {
  display: inline-block;
}

.inner {
  min-width: 88px;
  text-align: center;
  line-height: 32px;
}

.chip {
  min-width: 64px;
  text-align: center;
}
</style>
```

---

Document: llms/en-US/components/switch.md

<!-- Source: src/switch/README.en-US.md; locale: en-US; page: /en/components/switch/ -->

# Switch

The same scenarios, parameters and interactions as Cedar. Only component prefixes differ; themes and site shells remain independent.

## Reading direction

Switch inherits source dir: its unchecked handle starts at inline start and moves toward inline end when checked. Space/Enter still toggle. Direction changes do not modify values; disabled, readonly and loading states block commits.

## Basic examples

### Controlled and default value

Example source: src/switch/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const enabled = ref(false)
</script>

<template>
  <c-space wrap
    ><c-switch v-model="enabled" aria-label="Enable notifications" /><output>{{ enabled }}</output
    ><c-switch :default-value="true" aria-label="Initially enabled"
  /></c-space>
</template>
```

## Appearance and states

### Appearance configuration comparison

Choose a dimension to compare all its values side by side while keeping other settings and content identical. Change the other settings to inspect combinations; input specimens share one model.

Example source: src/switch/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(false);
const __demoAppearance = __demoReactive({ variant: "circle", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["circle","round","line","tonal"]},{"name":"size","values":["sm","md","lg"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'circle', value: 'circle' },
            { label: 'round', value: 'round' },
            { label: 'line', value: 'line' },
            { label: 'tonal', value: 'tonal' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-switch v-model="value" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"></c-switch>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Customization and slots

### Custom colors

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose               | Related examples            |
| ----------------- | --------------------- | --------------------------- |
| `variant`         | Appearance            | Custom text, Custom icons   |
| `checked-color`   | Checked track color   | Custom colors               |
| `unchecked-color` | Unchecked track color | Custom colors               |
| `checked-text`    | Checked label         | Custom text                 |
| `unchecked-text`  | Unchecked label       | Custom text                 |
| `ripple`          | Click ripple          | Ripple and handle elevation |

<!-- demo-config-notes:end -->

Example source: src/switch/__demos__/custom-color.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const enabled = ref(false)
</script>

<template>
  <c-switch
    v-model="enabled"
    checked-color="#005f73"
    unchecked-color="#9b2226"
    aria-label="Custom color switch"
  />
</template>
```

### Custom text

Example source: src/switch/__demos__/custom-text.vue

```vue
<template>
  <c-space wrap
    ><c-switch checked-text="ON" unchecked-text="OFF" aria-label="Text props" /><c-switch
      variant="round"
      aria-label="Text slots"
      ><template #checked>ON</template><template #unchecked>OFF</template></c-switch
    ></c-space
  >
</template>
```

### Custom icons

Example source: src/switch/__demos__/custom-icon.vue

```vue
<script setup lang="ts">
const variants = ['circle', 'round', 'line', 'tonal'] as const
</script>

<template>
  <c-space wrap
    ><c-switch v-for="variant in variants" :key="variant" :variant="variant" :aria-label="variant"
      ><template #checked-icon>✓</template><template #unchecked-icon>×</template></c-switch
    ></c-space
  >
</template>
```

### Ripple and handle elevation

Example source: src/switch/__demos__/custom.vue

```vue
<template>
  <c-space wrap
    ><c-switch :ripple="false" :handle-elevation="false" aria-label="No ripple or shadow" /><c-switch
      :handle-elevation="4"
      aria-label="Elevated handle"
  /></c-space>
</template>
```

## Interaction and control

### Interaction state comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                      | Related examples             |
| --------------- | ------------------------------------------------------------ | ---------------------------- |
| `disabled`      | Disable interaction, including inherited form disabled state | Interaction state comparison |
| `readonly`      | Read only; focus and click remain available without toggling | Interaction state comparison |
| `variant`       | Appearance                                                   | Loading                      |
| `loading`       | Loading; blocks clicks and changes                           | Loading                      |
| `default-value` | Initial uncontrolled value; falls back to uncheckedValue     | Loading                      |
| `size`          | Size; omitted value follows platform rules below             | Focus and event order        |

<!-- demo-config-notes:end -->

Toggle disabled, read-only and error states, then interact with the same instance. Recovery controls remain outside the target; error appearance alone does not validate data.

Example source: src/switch/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(false);
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-switch v-model="value" v-bind="__demoState"></c-switch>
  </c-space>
</template>
```

### Loading

Example source: src/switch/__demos__/loading.vue

```vue
<script setup lang="ts">
const variants = ['circle', 'round', 'line', 'tonal'] as const
</script>

<template>
  <c-space wrap
    ><template v-for="variant in variants" :key="variant"
      ><c-switch :variant="variant" loading :aria-label="variant + ' off'" /><c-switch
        :variant="variant"
        :default-value="true"
        loading
        :aria-label="variant + ' on'" /></template
  ></c-space>
</template>
```

### Focus and event order

Example source: src/switch/__demos__/events.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref(false)
const events = ref<string[]>([])
function record(name: string) {
  events.value = [...events.value.slice(-7), name]
}
</script>

<template>
  <p>Use Tab to focus, then Space or Enter to toggle.</p>
  <c-switch
    v-model="value"
    size="md"
    aria-label="Event sequence"
    @focus="record('focus')"
    @blur="record('blur')"
    @click="record('click')"
    @update:model-value="record(`update: ${$event}`)"
    @change="record(`change: ${$event}`)"
  />
  <p aria-live="polite">{{ events.join(' → ') || 'No events yet' }}</p>
  <c-button @click="events = []">Clear events</c-button>
</template>
```

### Custom values and events

Example source: src/switch/__demos__/custom-value.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('disabled')
const lastChange = ref('—')
</script>

<template>
  <c-space direction="column"
    ><c-switch
      v-model="value"
      checked-value="enabled"
      unchecked-value="disabled"
      aria-label="String value"
      @change="lastChange = String($event)"
    /><output aria-live="polite">Value: {{ value }}; change: {{ lastChange }}</output></c-space
  >
</template>
```

## Async and dynamic data

### Async allow, deny and rejection

Example source: src/switch/__demos__/switch-interception.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const result = ref('Ready')
const wait = () => new Promise<void>((resolve) => setTimeout(resolve, 500))
async function allow() {
  await wait()
  result.value = 'Allowed'
  return true
}
async function deny() {
  await wait()
  result.value = 'Blocked'
  return false
}
async function reject() {
  await wait()
  result.value = 'Rejected'
  throw new Error('Demo rejection')
}
</script>

<template>
  <c-space direction="column">
    <label>Allow after 500ms <c-switch :before-change="allow" aria-label="Async allow" /></label>
    <label>Return false <c-switch :before-change="deny" aria-label="Async deny" /></label>
    <label>Reject Promise <c-switch :before-change="reject" aria-label="Async rejection" /></label>
    <output aria-live="polite">{{ result }}</output>
  </c-space>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Value and default value

Use ordinary `v-model`. `modelValue` is the actual switch value and matches checkedValue/uncheckedValue types. `defaultValue` initializes uncontrolled state once; later changes do not reset it. Explicit binding takes precedence, with no initialization `update:modelValue`.

<!-- same-source-api:start -->

### Props

| Prop             | Meaning                                                                                                 | Type                                                                 | Default   |
| ---------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | --------- |
| model-value      | Controlled value; managed internally when omitted                                                       | string / number / boolean                                            | undefined |
| default-value    | Initial uncontrolled value; falls back to uncheckedValue                                                | string / number / boolean                                            | undefined |
| clearable        | Show clearing in popup editing                                                                          | boolean                                                              | false     |
| empty-value      | Value committed after clearing; accepts a value or factory                                              | SwitchValue \| null \| (() => SwitchValue \| null)                   | undefined |
| edit-mode        | Editing mode; inherits FormItem/Form when unset. See editing-mode guidance for platform-specific values | FieldEditMode                                                        | undefined |
| read-pretty      | Plain reading display, independent of readonly                                                          | boolean                                                              | undefined |
| before-commit    | Cancelable interceptor before saving the editor                                                         | BeforeFieldCommit                                                    | undefined |
| open             | Controlled editor open state                                                                            | boolean                                                              | undefined |
| default-open     | Initial uncontrolled editor state                                                                       | boolean                                                              | false     |
| popup-container  | Editor mount container                                                                                  | PopupContainer                                                       | undefined |
| checked-value    | Checked value                                                                                           | string / number / boolean                                            | true      |
| unchecked-value  | Unchecked value                                                                                         | string / number / boolean                                            | false     |
| variant          | Appearance                                                                                              | circle / round / line / tonal                                        | circle    |
| size             | Size; omitted value follows platform rules below                                                        | sm / md / lg                                                         | undefined |
| disabled         | Disable interaction, including inherited form disabled state                                            | boolean                                                              | undefined |
| readonly         | Read only; focus and click remain available without toggling                                            | boolean                                                              | undefined |
| loading          | Loading; blocks clicks and changes                                                                      | boolean                                                              | false     |
| before-change    | Switch interceptor, not an event                                                                        | (payload, done, context) => boolean / void / Promise<boolean / void> | —         |
| checked-text     | Checked label                                                                                           | string                                                               | —         |
| unchecked-text   | Unchecked label                                                                                         | string                                                               | —         |
| checked-color    | Checked track color                                                                                     | string                                                               | —         |
| unchecked-color  | Unchecked track color                                                                                   | string                                                               | —         |
| loading-color    | Loading-icon color                                                                                      | string                                                               | —         |
| ripple           | Click ripple                                                                                            | boolean                                                              | true      |
| handle-elevation | Thumb elevation: true means level 2; numbers are integer-clamped to 0–24                                | boolean / number                                                     | true      |

before-change returning false, throwing or rejecting cancels switching. Other normal completion allows it. While awaiting a Promise or done, loading is automatic and repeated input is blocked.
Pending results become stale after unmount, KeepAlive deactivation, external value updates or changes to disabled/readonly/loading.
Controlled mode only requests updates. Selection changes after the parent updates model-value. Without model-value, internal state is used.

### Events

| Event              | Arguments and timing                                                   |
| ------------------ | ---------------------------------------------------------------------- |
| click              | (event: Event), before interception when clicking is allowed           |
| update:model-value | (nextValue: SwitchValue), after switching is allowed and before change |
| change             | (nextValue: SwitchValue, event: Event), once per commit                |
| focus              | (event: FocusEvent), on focus                                          |
| blur               | (event: FocusEvent), on blur                                           |

Supports Enter/Space without repeated toggles on key repeat. disabled/loading emit neither click nor value changes; readonly may emit click without running the interceptor.
External model-value updates do not emit an extra change.

### Slots

| Slot           | Description                                                   | Arguments |
| -------------- | ------------------------------------------------------------- | --------- |
| checked        | Checked label; overrides checked-text; hidden for line/sm     | —         |
| unchecked      | Unchecked label; overrides unchecked-text; hidden for line/sm | —         |
| checked-icon   | Checked thumb icon; replaced while loading                    | —         |
| unchecked-icon | Unchecked thumb icon; replaced while loading                  | —         |

### Methods

No public methods.

### Platform notes

Props, event arguments and slots match. Cedar inherits omitted size from Form/global settings: xs/sm map to sm; lg/xl map to lg. Maple defaults to md. Both inherit disabled/readonly from field > FormItem > Form, with explicit false overriding the parent. Form integration is local to each platform.
<!-- same-source-api:end -->

### Types

SwitchProps, SwitchVariant, SwitchSize, SwitchValue, SwitchBeforeChange and SwitchInstance are exported from both root and component entries.

### Style variables

| Token: Cedar uses --c-, Maple uses --mp-                  | Default                                                 |
| --------------------------------------------------------- | ------------------------------------------------------- |
| --c-switch-width / height / handle-size                   | 40px / 24px / 16px                                      |
| --c-switch-size-sm-scale / size-lg-scale                  | .8 / 1.2                                                |
| --c-switch-tonal-width / tonal-height / tonal-handle-size | 52px / 32px / 24px                                      |
| --c-switch-line-height / line-handle-size                 | 12px / 20px                                             |
| --c-switch-hit-area                                       | 0px; outward hit-area expansion without changing layout |
| --c-switch-track-background / track-active-background     | Neutral / theme color                                   |
| --c-switch-handle-background / handle-color               | White / theme color                                     |
| --c-switch-disabled-opacity                               | .5                                                      |
| --c-switch-round-radius / gap                             | 4px / 4px                                               |

See style/token.less for all variables. Legacy platform-specific Switch geometry tokens are not guaranteed to remain.

## Migration

Maple standard becomes line. Omitting variant now selects circle. Both platforms use four variants; standard is not retained as an alias.
lazy-change is removed. before-change moves from a (value, change) callback to return-value/Promise control; applications no longer call change manually.
Maple change now includes the original event as its second argument. checked-color/unchecked-color control the track consistently; tokens customize thumbs.

### Color variables and tonal foreground migration

| Variable suffix: --c-switch- | Default system role | Responsibility                                                   |
| ---------------------------- | ------------------- | ---------------------------------------------------------------- |
| track-background             | content-secondary   | Ordinary unchecked solid track                                   |
| track-active-background      | content-brand       | Checked track and keyboard-focus ring                            |
| track-error-background       | content-danger      | Interactive error track and tonal error border                   |
| handle-background            | surface-default     | Ordinary/checked/error thumb fill                                |
| handle-color                 | content-brand       | Ordinary/checked/error thumb icon color                          |
| text-color                   | surface-default     | Text on a solid track                                            |
| checked-text-color           | switch-text-color   | Checked-track text; error retains existing foreground precedence |
| tonal-track-background       | surface-muted       | Tonal unchecked-track background                                 |
| tonal-border-color           | content-secondary   | Tonal unchecked border and thumb fill                            |
| tonal-text-color             | content-secondary   | Added: tonal unchecked-track text                                |
| tonal-handle-color           | surface-default     | Added: tonal unchecked-thumb icon                                |

Defaults reference matching system roles, e.g. var(--c-sys-color-content-secondary). Unchecked tonal uses tonal-text-color / tonal-handle-color; customize both ordinary and tonal foregrounds for all variants. Interactive errors use ordinary text/thumb pairing; disabled/loading suppress error colors. Custom tracks require foreground-contrast checks. Shadows, geometry and motion are outside this color contract.

### Theme names and variant names

Theme entries are Themes.default.light/dark and Themes.maple.light/dark. Switch tonal is a variant, not a theme. Public variants and eight dedicated variables consistently use tonal without old-name aliases.

### Motion variables

Built-in motion follows `prefers-reduced-motion: reduce`. Reduced motion does not prevent loading-state or close-event updates.

| Token                         | Default |
| ----------------------------- | ------- |
| `--c-switch-loading-duration` | `1s`    |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

### Form state inheritance

Omitted `disabled` / `readonly` inherit FormItem, then Form; an explicit `false` overrides inherited state. Becoming `disabled` or read-only invalidates a pending `beforeChange`, so a late result cannot toggle the value. Outside a form, omitted values behave as `false`.

## Inheriting Form disabled state

The default disabled=undefined means inheritance, resolved as local ?? FormItem ?? Form ?? false. Explicit false remains effective, allowing one field to stay enabled while unspecified fields follow Form. Form disabled is the form-wide default, not a lock preventing child overrides.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

```vue
<c-switch v-model="flag" :before-change="beforeChange" />
```

```ts
const beforeChange = (next, done) => {
  canChange(next).then((allowed) => done(allowed));
};
```

Cancellable hooks use `(payload, done, context)`: closure payloads contain `{ action }`, change/commit payloads contain `{ value, previousValue }`, and Popup uses `{ reason }`. Context provides `signal` and an optional original `event`. Return a boolean/Promise, or call done()/done(false). Synchronous void waits for done; Promise&lt;void&gt; allows the operation. First completion wins. Pending state controls loading/disabled automatically. Cancellation invalidates stale results. Button refs are not exposed.

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading.

---

Document: llms/en-US/components/table-column-manager.md

<!-- Source: src/table-column-manager/README.en-US.md; locale: en-US; page: /en/components/table-column-manager/ -->

# Table Column Manager

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `options`: Supplies the available options.

Example source: src/table-column-manager/__demos__/basic.vue

```vue
<template>
  <c-space>
    <c-button @click="openDrawer = true">抽屉中管理列</c-button>
    <c-button @click="openDialog = true">弹窗中管理列</c-button>
  </c-space>

  <c-table-column-manager
    v-model:open="openDrawer"
    v-model="items"
    :columns="columns"
    :options="columnDefinitions"
    :fallback-item="fallbackItem"
    @confirm="applyResult"
  />

  <c-dialog v-model:open="openDialog" title="列管理" :width="720" :body-padding="false" unmount-on-close>
    <div style="height: 480px">
      <c-table-column-manager
        inline
        v-model="items"
        :columns="columns"
        :options="columnDefinitions"
      />
    </div>
  </c-dialog>

  <pre style="margin-top: 16px; font-size: 12px">
items: {{ items }}
columns: {{ columns.map((c) => c.dataIndex).join(', ') }}</pre
  >
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type {
  ColumnDefinition,
  ColumnDefinitions,
  ColumnManagerItem,
  ColumnManagerResult,
  TableColumnData,
} from '@cedar-design/ui'

const openDrawer = ref(false)
const openDialog = ref(false)

const items = ref<ColumnManagerItem[]>([
  { dataIndex: 'connectorId', fixed: 'left' },
  { dataIndex: 'connectorName' },
  { dataIndex: 'deviceName' },
])

const columns = ref<TableColumnData[]>([
  { dataIndex: 'connectorId', title: '枪ID', width: 100, fixed: 'left' },
  { dataIndex: 'connectorName', title: '枪名称', width: 120 },
  { dataIndex: 'deviceName', title: '设备名称', width: 120 },
])

const columnDefinitions = ref<ColumnDefinitions>([
  {
    title: '基本信息',
    key: 'basic',
    children: [
      {
        dataIndex: 'connectorId',
        title: '枪ID',
        required: true,
        tip: '必选列',
      },
      {
        dataIndex: 'connectorName',
        title: '枪名称',
      },
      {
        dataIndex: 'areaCompany',
        title: '区域公司区域公司区域公司区域公司区域公司区域公司',
        tip: '区域公司说明',
      },
    ],
  },
  {
    title: '设备信息',
    key: 'device',
    children: [
      { dataIndex: 'deviceId', title: '设备ID' },
      { dataIndex: 'deviceName', title: '设备名称' },
      { dataIndex: 'lockStatus', title: '地锁' },
    ],
  },
  { dataIndex: 'workingStatus', title: '工作状态' },
  { dataIndex: 'connectStatus', title: '连接状态' },
])

const fallbackItem = (dataIndex: string): ColumnDefinition => {
  return { dataIndex, title: dataIndex }
}

const applyResult = (result: ColumnManagerResult) => {
  columns.value = result.columns
  items.value = result.items
}
</script>
```

## Table integration and persistence

### With Table Ungrouped

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `open` | Drawer visibility; `v-model:open` | With Table |
| `columns` | Current Table columns; assembled back into full definitions on confirmation | With Table |
| `options` | Left-side column definitions | With Table |
| `drawer-title` | Drawer title | With Table |
| `inline` | Render only the inline panel without a drawer | With Table |
<!-- demo-config-notes:end -->


Preview configuration: `v-model:columns="columns"`, `extra-column`, `column-resizable`, `:data="data"`.

Example source: src/table-column-manager/__demos__/with-table-ungrouped.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      不分组列示例：目录就是普通数组。工号为必选左冻结列，备注和入职日期默认隐藏；支持搜索、显隐、拖拽排序、冻结、删除、重命名和列宽记忆。
    </c-alert>

    <div class="demo-toolbar">
      <c-button status="secondary" size="sm" @click="open">管理列</c-button>
      <c-link @click="resetToDefault">恢复默认</c-link>
      <span class="demo-summary"
        >已展示 {{ leafColumns.length }} /
        {{ columnDefinitions.length }} 列</span
      >
    </div>

    <c-table
      v-model:columns="columns"
      extra-column
      column-resizable
      :data="data"
      :pagination="false"
      :bordered="{ cell: true, headerCell: true }"
      size="xs"
      @column-resize="handleColumnResize"
    >
      <template #extra-column-header>
        <c-button variant="text" size="xs" aria-label="管理列" @click="open"
          ><c-icon-settings
        /></c-button>
      </template>
      <template #extra-column-cell />

      <template #header-cell-actions="{ column, dataIndex }">
        <HeaderAction :data-index="dataIndex" :column="column" />
      </template>

      <template #status="{ record }">
        <c-tag :color="record.status === '在职' ? 'green' : 'gray'" size="sm">{{
          record.status
        }}</c-tag>
      </template>
    </c-table>

    <c-table-column-manager v-bind="managerProps" />
  </c-space>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { useTableColumnManager } from "@cedar-design/ui";
import type { ColumnDefinitions, ManagedTableColumn } from "@cedar-design/ui";

const defaultColumns: ManagedTableColumn[] = [
  {
    dataIndex: "employeeId",
    title: "工号",
    manager: { required: true },
    fixed: "left",
    width: 110,
  },
  { dataIndex: "name", title: "姓名", minWidth: 140 },
  { dataIndex: "department", title: "部门", width: 140 },
  { dataIndex: "position", title: "职位", minWidth: 160 },
  { dataIndex: "phone", title: "手机号", width: 150 },
  { dataIndex: "status", title: "状态", width: 100, slotName: "status" },
];

const columnDefinitions: ColumnDefinitions = [
  {
    dataIndex: "employeeId",
    title: "工号",
    tip: "必选规则来自 defaultColumns",
  },
  { dataIndex: "name", title: "姓名" },
  { dataIndex: "department", title: "部门" },
  { dataIndex: "position", title: "职位" },
  { dataIndex: "phone", title: "手机号" },
  { dataIndex: "status", title: "状态" },
  { dataIndex: "joinedAt", title: "入职日期" },
  { dataIndex: "remark", title: "备注", tip: "不在默认列中，可从弹窗添加" },
];

const {
  columns,
  managerProps,
  leafColumns,
  open,
  handleColumnResize,
  HeaderAction,
  resetToDefault,
} = useTableColumnManager({
  defaultColumns,
  columnDefinitions,
  columnDefaults: { width: 130, ellipsis: true },
  createColumn: (definition) =>
    definition.dataIndex === "remark"
      ? {
          dataIndex: definition.dataIndex,
          title: definition.title,
          minWidth: 220,
          width: undefined,
        }
      : { dataIndex: definition.dataIndex, title: definition.title },
});

const data = ref([
  {
    employeeId: "E-1001",
    name: "张三",
    department: "产品研发部",
    position: "前端工程师",
    phone: "138****1024",
    status: "在职",
    joinedAt: "2023-04-18",
    remark: "负责组件库和中后台基础设施",
  },
  {
    employeeId: "E-1002",
    name: "李四",
    department: "质量保障部",
    position: "测试工程师",
    phone: "139****3072",
    status: "在职",
    joinedAt: "2022-11-07",
    remark: "负责自动化测试平台",
  },
  {
    employeeId: "E-1003",
    name: "王五",
    department: "数据平台部",
    position: "数据分析师",
    phone: "136****8841",
    status: "离职",
    joinedAt: "2021-08-23",
    remark: "历史项目成员",
  },
]);
</script>

<style scoped>
.demo-toolbar {
  display: flex;
  align-items: center;
  gap: 12px;
}

.demo-summary {
  margin-left: auto;
  color: var(--c-color-text-3);
}
</style>
```

### With Table Header Menu

Preview configuration: `checked-text="fit"`, `unchecked-text="fit"`, `size="sm"`, `checked-text="fixed"`.

Example source: src/table-column-manager/__demos__/with-table-header-menu.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      分组列示例：左侧 <code>优先级</code> 冻结，右侧 <code>状态</code> 冻结；
      <code>名称</code>、<code>更新时间</code> 只设
      <code>min-width</code> 作为弹性列。表格始终铺满父容器：<code>fit</code>
      开启时剩余空间按 min-width
      比例分给弹性列，关闭时按各列宽度比例放大；extra-column 固定 28px
      不参与分配。<code>table-layout="auto"</code> 时 colgroup 不渲染
      <code>col</code>，列宽交给浏览器按内容分配，且不显示拖拽把手（拖拽仅
      <code>fixed</code> 布局可用）。
    </c-alert>

    <c-space wrap size="16px" align="center">
      <c-button status="secondary" size="sm" @click="open">列管理</c-button>
      <c-link @click="resetToDefault">重置</c-link>
      <c-switch
        v-model="fit"
        checked-text="fit"
        unchecked-text="fit"
        size="sm"
      />
      <c-switch
        v-model="isFixedLayout"
        checked-text="fixed"
        unchecked-text="auto"
        size="sm"
      />
      <span style="color: var(--c-color-text-3); margin-left: 8px">
        当前 {{ leafColumns.length }} 列
      </span>
    </c-space>

    <c-space wrap size="8px" align="center">
      <c-tag
        v-for="col in leafColumns"
        :key="col.dataIndex"
        size="sm"
        color="gray"
      >
        {{ col.title }}
        <template v-if="col.width"> · {{ col.width }}px</template>
        <template v-if="col.fixed"
          >（{{ col.fixed === "left" ? "左冻" : "右冻" }}）</template
        >
      </c-tag>
    </c-space>

    <c-table
      v-model:columns="columns"
      extra-column
      column-resizable
      :data="data"
      :pagination="false"
      :bordered="{ cell: true, headerCell: true }"
      :fit="fit"
      :table-layout="tableLayout"
      size="xs"
      @column-resize="handleColumnResize"
    >
      <template #extra-column-header>
        <c-button variant="text" size="xs" aria-label="管理列" @click="open">
          <c-icon-settings />
        </c-button>
      </template>
      <template #extra-column-cell />

      <template #header-cell-actions="{ column, dataIndex }">
        <HeaderAction :data-index="dataIndex" :column="column" />
      </template>

      <template #priority="{ record }">
        <c-tag :color="priorityColor(record.priority)" size="sm">{{
          record.priority
        }}</c-tag>
      </template>
      <template #status="{ record }">
        <c-tag :color="statusColor(record.status)" size="sm">{{
          record.status
        }}</c-tag>
      </template>
    </c-table>

    <!-- 列管理抽屉 + 插入/编辑弹窗 -->
    <c-table-column-manager v-bind="managerProps" />
  </c-space>
</template>

<script lang="ts" setup>
import { computed, onMounted, ref, watch } from "vue";
import { useTableColumnManager } from "@cedar-design/ui";
import type { ColumnDefinitions, ManagedTableColumn } from "@cedar-design/ui";

const STORAGE_KEY = "cedar-demo:table-column-manager:with-table-header-menu";
let storage: Storage | undefined;
const storageReady = ref(false);

const fit = ref(true);
// fixed：列宽由布局引擎计算写入 col，不被内容撑开；auto：不渲染 col，交给浏览器按内容分配
const tableLayout = ref<"fixed" | "auto">("fixed");
const isFixedLayout = computed({
  get: () => tableLayout.value === "fixed",
  set: (val: boolean) => {
    tableLayout.value = val ? "fixed" : "auto";
  },
});

const defaultColumns: ManagedTableColumn[] = [
  {
    title: "基本信息",
    children: [
      {
        dataIndex: "priority",
        title: "优先级",
        manager: { required: true },
        fixed: "left",
        width: 120,
        slotName: "priority",
      },
      {
        dataIndex: "name",
        title: "名称",
        minWidth: 200,
      },
      {
        dataIndex: "bizLine",
        title: "业务线",
        width: 120,
      },
    ],
  },
  {
    title: "人员与状态",
    children: [
      {
        dataIndex: "owner",
        title: "负责人",
        width: 100,
      },
      {
        dataIndex: "updatedAt",
        title: "更新时间",
        minWidth: 140,
      },
      {
        dataIndex: "status",
        title: "状态",
        fixed: "right",
        width: 120,
        slotName: "status",
      },
    ],
  },
];

// 候选定义只服务于弹窗展示和搜索，不重复配置 Table 宽度、插槽或必选规则。
const columnDefinitions: ColumnDefinitions = [
  {
    key: "base",
    title: "基本信息",
    children: [
      {
        dataIndex: "priority",
        title: "优先级",
        tip: "必选规则来自 defaultColumns",
      },
      { dataIndex: "name", title: "名称" },
      { dataIndex: "bizLine", title: "业务线" },
      {
        dataIndex: "description",
        title: "任务描述",
        tip: "候选的新列，通过 createColumn 设置特殊宽度",
      },
    ],
  },
  {
    key: "people",
    title: "人员与状态",
    children: [
      { dataIndex: "owner", title: "负责人" },
      { dataIndex: "updatedAt", title: "更新时间" },
      { dataIndex: "status", title: "状态" },
      { dataIndex: "deadline", title: "截止时间" },
    ],
  },
];

// ---------- 核心：一行接入列管理 ----------

const manager = useTableColumnManager({
  defaultColumns,
  columnDefinitions,
  // 普通新增列统一使用该默认 Table 配置。
  columnDefaults: { width: 140, ellipsis: true },
  // 少量特殊候选列在这里补充本地渲染配置。
  createColumn: (definition) =>
    definition.dataIndex === "description"
      ? {
          dataIndex: definition.dataIndex,
          title: definition.title,
          minWidth: 240,
          width: undefined,
        }
      : { dataIndex: definition.dataIndex, title: definition.title },
});
const {
  columns,
  state,
  restore,
  managerProps,
  leafColumns,
  open,
  handleColumnResize,
  HeaderAction,
  resetToDefault: resetManagerToDefault,
} = manager;

// 持久化属于业务层：组件和 useTableColumnManager 不读写 localStorage。
onMounted(async () => {
  storage = window.localStorage;
  try {
    const raw = storage.getItem(STORAGE_KEY);
    if (raw) await restore(JSON.parse(raw));
  } catch {
    storage.removeItem(STORAGE_KEY);
  } finally {
    storageReady.value = true;
  }
});

watch(
  state,
  (value) => {
    if (!storageReady.value) return;
    storage?.setItem(STORAGE_KEY, JSON.stringify(value));
  },
  { deep: true },
);

const resetToDefault = () => {
  storage?.removeItem(STORAGE_KEY);
  resetManagerToDefault();
};

// ---------- 渲染辅助 ----------

const priorityColor = (value: string) => {
  if (value === "P0") return "red";
  if (value === "P1") return "orange";
  return "gray";
};

const statusColor = (value: string) => {
  if (value === "进行中") return "blue";
  if (value === "已完成") return "green";
  if (value === "已阻塞") return "red";
  return "gray";
};

const data = ref([
  {
    priority: "P0",
    name: "任务 A",
    bizLine: "交易",
    description: "修复支付链路并补充异常监控",
    owner: "张三",
    updatedAt: "2026-07-21 10:30",
    status: "进行中",
    deadline: "2026-08-10",
  },
  {
    priority: "P1",
    name: "任务 B",
    bizLine: "物流",
    description: "优化仓配系统的库存同步效率",
    owner: "李四",
    updatedAt: "2026-07-22 14:00",
    status: "已完成",
    deadline: "2026-08-05",
  },
  {
    priority: "P0",
    name: "任务 C",
    bizLine: "交易",
    description: "排查高峰期订单重复提交问题",
    owner: "王五",
    updatedAt: "2026-07-25 09:15",
    status: "已阻塞",
    deadline: "2026-08-12",
  },
]);
</script>
```

### With Table

- `options`: Supplies the available options.

Example source: src/table-column-manager/__demos__/with-table.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      <code>c-table-column-manager</code> 自身包含抽屉；弹窗场景传入
      <code>inline</code> 后以内联面板形式放入自定义容器。
    </c-alert>

    <c-space wrap size="8px" justify="flex-end">
      <c-button variant="outline" @click="openAs('drawer')"
        >抽屉管理列</c-button
      >
      <c-button variant="outline" @click="openAs('dialog')"
        >弹窗管理列</c-button
      >
    </c-space>

    <c-table
      v-model:columns="columns"
      :data="data"
      :pagination="false"
      size="xs"
    />

    <!-- 抽屉模式：组件自带抽屉 -->
    <c-table-column-manager
      v-if="container === 'drawer'"
      v-model:open="visible"
      v-model="items"
      :columns="columns"
      :options="columnDefinitions"
      drawer-title="列管理"
      @confirm="handleConfirm"
    />

    <!-- 弹窗模式：inline 内联面板放入 c-dialog -->
    <c-dialog
      v-else
      v-model:open="visible"
      title="列管理"
      :width="720"
      :body-padding="false"
      unmount-on-close
    >
      <div style="height: 480px">
        <c-table-column-manager
          inline
          v-model:open="visible"
          v-model="items"
          :columns="columns"
          :options="columnDefinitions"
          @confirm="handleConfirm"
        />
      </div>
    </c-dialog>
  </c-space>
</template>

<script setup lang="ts">
import { ref, watch } from "vue";
import { stateFromColumns } from "@cedar-design/ui";
import type {
  ColumnDefinitions,
  ColumnManagerResult,
  TableColumnData,
} from "@cedar-design/ui";

const visible = ref(false);
const container = ref<"drawer" | "dialog">("drawer");
const items = ref([]);

const columns = ref<TableColumnData[]>([
  { dataIndex: "name", title: "姓名", width: 120, fixed: "left" },
  { dataIndex: "salary", title: "薪资", width: 100 },
  { dataIndex: "address", title: "地址" },
]);

const columnDefinitions: ColumnDefinitions = [
  {
    title: "基础信息",
    key: "basic",
    children: [
      { dataIndex: "name", title: "姓名", required: true, tip: "必选列" },
      { dataIndex: "salary", title: "薪资" },
      { dataIndex: "email", title: "邮箱" },
    ],
  },
  {
    title: "扩展信息",
    key: "extra",
    children: [
      { dataIndex: "address", title: "地址" },
      { dataIndex: "department", title: "部门" },
      {
        dataIndex: "action",
        title: "操作",
      },
    ],
  },
];

const syncManagerState = () => {
  const state = stateFromColumns(columns.value, columnDefinitions);
  items.value = state.items;
};

watch(visible, (val) => {
  if (val) syncManagerState();
});

const openAs = (type: "drawer" | "dialog") => {
  container.value = type;
  visible.value = true;
};

const handleConfirm = (result: ColumnManagerResult) => {
  columns.value = result.columns;
};
</script>
```

## Async catalog and search

### Remote

Preview configuration: `v-model:columns="columns"`, `:data="data"`, `:pagination="false"`, `size="xs"`.

Example source: src/table-column-manager/__demos__/remote.vue

```vue
<template>
  <c-space direction="column" size="md">
    <c-alert type="info" :show-icon="false">
      弹窗候选列由 <code>columnSource.search</code> 远程搜索；恢复缓存遇到本地未知列时，通过
      <code>columnSource.resolve</code> 批量反显。远程接口只返回 dataIndex、title 和分组信息。
    </c-alert>

    <div class="demo-toolbar">
      <c-button status="secondary" size="sm" @click="open">远程管理列</c-button>
      <c-link @click="resetToDefault">恢复本地默认列</c-link>
    </div>

    <c-table v-model:columns="columns" :data="data" :pagination="false" size="xs" />
    <c-table-column-manager v-bind="managerProps" />
  </c-space>
</template>

<script setup lang="ts">
import { onMounted, ref } from 'vue'
import { useTableColumnManager } from '@cedar-design/ui'
import type { ColumnDefinition, ColumnDefinitionSource, ManagedTableColumn } from '@cedar-design/ui'

const defaultColumns: ManagedTableColumn[] = [
  { dataIndex: 'id', title: '编号', width: 100, fixed: 'left', manager: { required: true } },
  { dataIndex: 'name', title: '名称', minWidth: 180 },
]

// 模拟服务端保存的轻量字段目录。
const remoteFields: Array<ColumnDefinition & { group?: string }> = [
  { dataIndex: 'id', title: '编号', group: '基础信息' },
  { dataIndex: 'name', title: '名称', group: '基础信息' },
  { dataIndex: 'owner', title: '负责人', group: '基础信息' },
  { dataIndex: 'remoteConfig1', title: '远程配置 1', group: '远程配置' },
  { dataIndex: 'remoteConfig2', title: '远程配置 2', group: '远程配置' },
  { dataIndex: 'remoteStatus', title: '远程状态', group: '远程配置' },
]

const wait = (duration: number) => new Promise((resolve) => setTimeout(resolve, duration))
const groupDefinitions = (items: typeof remoteFields) =>
  [...new Set(items.map((item) => item.group ?? '其他'))].map((group) => ({
    key: group,
    title: group,
    children: items
      .filter((item) => (item.group ?? '其他') === group)
      .map(({ group: _group, ...definition }) => definition),
  }))

const columnSource: ColumnDefinitionSource = {
  async search({ keyword }) {
    await wait(300)
    const normalized = keyword.trim().toLowerCase()
    const matched = normalized
      ? remoteFields.filter(
          (item) => item.title.toLowerCase().includes(normalized) || item.dataIndex.toLowerCase().includes(normalized)
        )
      : remoteFields
    return { items: groupDefinitions(matched), total: matched.length }
  },
  async resolve(dataIndexes) {
    await wait(200)
    const keys = new Set(dataIndexes)
    return remoteFields.filter((item) => keys.has(item.dataIndex)).map(({ group: _group, ...item }) => item)
  },
}

const { columns, managerProps, open, restore, resetToDefault } = useTableColumnManager({
  defaultColumns,
  columnSource,
  columnDefaults: { width: 140, ellipsis: true },
  createColumn: (definition) =>
    definition.dataIndex === 'remoteStatus'
      ? { dataIndex: definition.dataIndex, title: definition.title, width: 110 }
      : { dataIndex: definition.dataIndex, title: definition.title },
})

onMounted(async () => {
  // 模拟缓存中包含一个不在本地 defaultColumns 里的远程列。
  await restore({
    version: 2,
    items: [{ dataIndex: 'id', fixed: 'left' }, { dataIndex: 'name' }, { dataIndex: 'remoteConfig2' }],
  })
})

const data = ref([
  {
    id: 'T-001',
    name: '远程字段示例',
    owner: '张三',
    remoteConfig1: '配置 A',
    remoteConfig2: '配置 B',
    remoteStatus: '已同步',
  },
])
</script>

<style scoped>
.demo-toolbar {
  display: flex;
  align-items: center;
  gap: 12px;
}
</style>
```

## API

### State and persistence structure

Column order, titles and fixed positions are stored together in `items`. The component/`useTableColumnManager` do not cache state. Business code may persist
the following state to localStorage, Pinia or a server:

```ts
const state: ColumnManagerState = {
  version: 2,
  items: [
    { dataIndex: 'id', fixed: 'left', width: 120 },
    { dataIndex: 'name', title: 'User name' },
  ],
  layout: [],
}
```

This is a major breaking change: legacy `keys`, `fixedMap` and `titleMap` structures are no longer read.

```ts
const { state, restore } = useTableColumnManager({ defaultColumns, columnDefinitions })
const storageReady = ref(false)

onMounted(async () => {
  const raw = window.localStorage.getItem(STORAGE_KEY)
  if (raw) await restore(JSON.parse(raw))
  storageReady.value = true
})

watch(
  state,
  (value) => {
    if (!storageReady.value) return
    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(value))
  },
  { deep: true }
)
```

`restore()` validates versions, removes stale/duplicate columns, cleans invalid widths/layouts, adds `required` columns and repairs fixed-region ordering.
`state` records only user-renamed titles and widths changed through `handleColumnResize`. Debounce server persistence in business code if needed.

### Default columns and candidate definitions

`defaultColumns` supplies complete initial Table columns and the reset baseline. `columnDefinitions` supplies popup candidates only and may contain just
`dataIndex`, `title`, grouping and hints:

```ts
const defaultColumns: ManagedTableColumn[] = [
  {
    title: 'Basic information',
    children: [
      {
        dataIndex: 'id',
        title: 'ID',
        fixed: 'left',
        width: 120,
        manager: { required: true },
      },
      { dataIndex: 'name', title: 'Name', minWidth: 180 },
    ],
  },
]

const columnDefinitions: ColumnDefinitions = [
  {
    key: 'base',
    title: 'Basic information',
    children: [
      { dataIndex: 'id', title: 'ID' },
      { dataIndex: 'name', title: 'Name' },
      { dataIndex: 'remark', title: 'Notes', tip: 'Optional column' },
    ],
  },
]

const manager = useTableColumnManager({
  defaultColumns,
  columnDefinitions,
  columnDefaults: { width: 140, ellipsis: true },
  createColumn: (definition) => ({ dataIndex: definition.dataIndex, title: definition.title }),
})
```

- `defaultColumns` determines initial display, reset, default width, fixed position, slots, rendering and `manager.required`.
- `columnDefinitions` determines popup candidates, not Table rendering configuration.
- `columnDefaults` supplies common Table defaults for new ordinary columns.
- `createColumn` handles a few candidates requiring special width, slots or rendering.
- For remote data, `columnSource.search` searches and `columnSource.resolve` restores unknown selected columns. `restore()` then returns a Promise.

### `<TableColumnManager>` Props

| Parameter | Description | Type | Default |
| ------------- | ---------------------------------- | ------------------------------------------------------- | ---------- |
| model-value | Complete ordered selected-column state, including titles/fixed positions | `ColumnManagerItem[]` | `-` |
| default-value | Initial uncontrolled selected state | `ColumnManagerItem[]` | `-` |
| columns | Current Table columns; assembled back into full definitions on confirmation | `TableColumnData[]` | `[]` |
| options | Left-side column definitions | `ColumnDefinitions` | `[]` |
| load-options | Asynchronously load column definitions | `() => Promise<ColumnDefinitions>` | `-` |
| remote-search | Remote search; hides top select-all when provided | `(keyword: string) => Promise<void>` | `-` |
| fallback-item | Resolve display for values absent from definitions | `(dataIndex: string) => ColumnDefinition \| undefined` | `-` |
| insert-at | Insertion context determining where new columns land | `{ dataIndex: string; side: 'left' \| 'right' }` | `-` |
| open | Drawer visibility; `v-model:open` | `boolean` | `-` |
| drawer-title | Drawer title | `string` | `自定义列` |
| drawer-width | Drawer width | `number \| string` | `720` |
| inline | Render only the inline panel without a drawer | `boolean` | `false` |
| placeholder | Search placeholder | `string` | `-` |

### Events

| Event | Description | Arguments |
| ----------------- | ------------------------------- | --------------------- |
| update:model-value | Complete selected-state changes | `ColumnManagerItem[]` |
| update:open | Drawer visibility changes | `boolean` |
| confirm | Assembled result after drawer/dialog confirmation | `ColumnManagerResult` |
| change | Selection, order, fixed-position or title changes | `ColumnManagerItem[]` |

### Methods

| Method | Description | Returns |
| ----------- | ------------------------ | --------------------- |
| getResult | Assemble Table columns from current selection | `ColumnManagerResult` |
| loadCatalog | Manually invoke `loadOptions` | `Promise<void>` |

### `useTableColumnManager`

Recommended with `c-table`. Returns `columns`, `state`, `restore`, `managerProps`, `HeaderAction` and others.
`HeaderAction` obtains context directly through `inject`; templates only need:

```vue
<template #header-cell-actions="{ column, dataIndex }">
  <HeaderAction :data-index="dataIndex" :column="column" />
</template>
```

`headerActions` configures visible header-action keys; all are shown by default.

Header-action behavior:

- Insert left/right: new columns enter the anchor's first-level group, preserving group titles/`colspan`. If the anchor is fixed, new columns inherit its fixed position.
- Fix/unfix: reorder leaf columns so fixed columns collect at the left/right edge.
- Edit columns: edit first-level group titles and column names; adjacent equal-name groups merge automatically.

Required rules need declaration only in `defaultColumns`. Transfer, clearing and header deletion all follow them:

```ts
{
  dataIndex: 'priority',
  title: 'Priority',
  manager: { required: true },
  fixed: 'left',
  width: 120,
  slotName: 'priority',
}
```

`columnDefinitions` need not duplicate width, fixed-position or required rules. User-resized widths persist in `items[].width`.

### Extra-column width

`c-table` `extra-column`, e.g. a settings control, defaults to 28px. Override with `extraColumn: { width: number }`.

### Utility functions in the column-management package

`buildColumnsResult` / `stateFromColumns` / `applyColumnEdit` / `applyColumnFixed` / `applyInsertToLayout` / `mapLeafColumns` support external assembly, group editing, fixed reordering and insertion. Traverse `columns` in business code for flat leaf lists; Table exports are unnecessary.

Catalog loading and remote searching own independent pending state; older completion cannot unlock newer work. loadOptions runs at creation, loader replacement and explicit loadCatalog calls. Manual calls retain Promise rejection; automatic reads use the Vue error path. Hook catalog/search jobs share current catalog ownership, restore has its own ownership, and newer column edits or disposal invalidate older restore results.

---

Document: llms/en-US/components/table.md

<!-- Source: src/table/README.en-US.md; locale: en-US; page: /en/components/table/ -->

# Table

## Basic examples

### Basic usage

Example source: src/table/__demos__/basic.vue

```vue
<script setup lang="ts">
const columns = [
  { title: 'Name', dataIndex: 'name' },
  { title: 'Salary', dataIndex: 'salary' },
  { title: 'Address', dataIndex: 'address' },
]
const data = [
  { key: '1', name: 'Jane Doe', salary: 23000, address: '32 Park Road, London' },
  { key: '2', name: 'Alisa Ross', salary: 25000, address: '35 Park Road, London' },
  { key: '3', name: 'Kevin Sandra', salary: 22000, address: '31 Park Road, London' },
]
</script>
<template>
  <c-table :columns="columns" :data="data" :pagination="false" />
</template>
```

### Manual loading

Boolean/object loading applies to both data and native-slot modes. Object options require `loading: true`. Rows and drafts remain mounted; notifications do not manage loading.

Example source: src/table/__demos__/loading.vue

```vue
<template>
  <c-space direction="column" style="width: 100%">
    <c-space
      ><c-switch v-model="loading" edit-mode="direct" /><span
        >手动控制两种表格的加载状态</span
      ></c-space
    >
    <c-table
      :columns="columns"
      :data="data"
      :loading="loading"
      :pagination="false"
    />
    <c-table :loading="loading" :pagination="false">
      <thead>
        <tr>
          <th>原生插槽</th>
          <th>保留编辑内容</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>切换加载不会重建行</td>
          <td><input v-model="draft" aria-label="表格草稿" /></td>
        </tr>
      </tbody>
    </c-table>
    <small>loading 仅由业务状态控制。输入草稿后切换加载，内容继续保留。</small>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const loading = ref(false);
const draft = ref("可编辑草稿");
const columns = [{ title: "数据模式", dataIndex: "name" }];
const data = [{ key: "row", name: "与原生插槽使用相同的 loading 合同" }];
</script>
```

### Empty State

- `columns`: Column info of the table
- `data`: Table data
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/empty-state.vue

```vue
<script setup lang="ts">
const columns = [{ title: 'Name', dataIndex: 'name' }, { title: 'Address', dataIndex: 'address' }]
</script>
<template>
  <c-table :columns="columns" :data="[]" :pagination="false">
    <template #empty>暂无记录，请调整筛选条件后重试。</template>
  </c-table>
</template>
```

## Column widths, layout and fixed columns

### Column width scenarios

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Column width scenarios, Fixed columns, Grouped headers with fixed columns |
| `data` | Table data | Column width scenarios, Fixed columns, Grouped headers with fixed columns |
| `pagination` | Pagination properties configuration | Column width scenarios, Layout, sizing and column resizing |
| `bordered` | Whether to show border | Grouped headers with fixed columns, Layout, sizing and column resizing |
| `sticky-pagination` | Sticky pagination relative to the page/outer scroller; numeric values are bottom offsets in px | Column width scenarios |
| `row-selection` | Table row selector configuration | Column width scenarios |
<!-- demo-config-notes:end -->


Container width and column width are separate settings. Use `style="width: 100%"` or `style="width: 480px"` for the container, and `columns[].width` / `minWidth` for individual columns. No `scroll.x` or `scroll.y` configuration is required.

Compare seven combinations and switch between 100%, 480px and 360px to observe recalculation and horizontal overflow.

| Configuration | Distribution with default `table-layout="fixed"`, `fit=true` |
| --- | --- |
| No column width | Each column starts at 80px and shares remaining space proportionally |
| `minWidth` | Base width of a flexible column; overflow preserves this width |
| `width` plus flexible columns | Explicit widths remain exact; flexible columns share remaining space in proportion to their base widths |
| Every column has `width` | Preserve widths on overflow; proportionally enlarge ordinary data columns when they do not fill the container |
| `fit=false` | Still fill the container; distribute remaining space proportionally across ordinary data columns |
| Selection / extra columns | Preserve selection operation width; exclude the extra column from proportional expansion |

Flexible columns have no explicit `width`. `minWidth` does not turn an explicit-width column into a flexible column. These distribution rules apply to `fixed` layout.

Example source: src/table/__demos__/column-width-scenarios.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { TableColumnData } from '@cedar-design/ui'

const tableWidth = ref('100%')
const data = [{ key: '1', name: '设备巡检', owner: '张三', status: '进行中' }]
const base: TableColumnData[] = [
  { title: '任务', dataIndex: 'name' },
  { title: '负责人', dataIndex: 'owner' },
  { title: '状态', dataIndex: 'status' },
]
const scenarios = [
  { title: '不指定列宽', description: '每列以 80px 为基础，均分剩余空间。', columns: base },
  { title: '全部使用 minWidth', description: '按 160 : 80 : 80 的基础宽度比例分配剩余空间。', columns: base.map((column, index) => ({ ...column, minWidth: index === 0 ? 160 : 80 })) },
  { title: '定宽列与弹性列混合', description: '负责人、状态各保持 120px，任务列吸收剩余空间。', columns: base.map((column, index) => ({ ...column, ...(index === 0 ? { minWidth: 160 } : { width: 120 }) })) },
  { title: '全部指定 width', description: '列宽之和不足容器时，Cedar 按比例放大普通数据列以铺满容器。', columns: base.map((column, index) => ({ ...column, width: index === 0 ? 160 : 80 })) },
  { title: '列宽之和超出容器', description: '三列各 280px，保留列宽并自动出现横向滚动条，无需 scroll.x。', columns: base.map(column => ({ ...column, width: 280 })) },
  { title: '左右固定列与混合列宽', description: '左右各固定 140px、120px，中间列 minWidth 为 440px；无需 scroll.x，底部粘性滚动条随表格悬浮显示。', columns: [{ ...base[0], width: 140, fixed: 'left' as const }, { ...base[1], minWidth: 440 }, { ...base[2], width: 120, fixed: 'right' as const }], sticky: true },
  { title: '选择列、弹性列与扩展列', description: '选择列保持 40px，扩展列保持 28px，任务列分配剩余空间。', columns: base.map((column, index) => ({ ...column, ...(index === 0 ? { minWidth: 160 } : { width: 120 }) })), operations: true },
]
</script>

<template>
  <div class="column-width-scenarios">
    <c-radio-group v-model="tableWidth" type="button" aria-label="表格宽度">
      <c-radio value="480px">定宽 480px</c-radio>
      <c-radio value="100%">100% 宽度</c-radio>
      <c-radio value="360px">窄屏 360px</c-radio>
    </c-radio-group>
    <section v-for="scenario in scenarios" :key="scenario.title">
      <h4>{{ scenario.title }}</h4>
      <p>{{ scenario.description }}</p>
      <c-table
        :columns="scenario.columns"
        :data="data"
        :style="{ width: tableWidth }"
        :pagination="scenario.sticky ? { pageSize: 5 } : false"
        :sticky-pagination="scenario.sticky ? 0 : false"
        :row-selection="scenario.operations ? { width: 40 } : undefined"
        :extra-column="scenario.operations"
      />
    </section>
  </div>
</template>

<style scoped>
.column-width-scenarios { width: 640px; max-width: 100%; }
.column-width-scenarios > section { margin-top: 24px; }
h4 { margin: 0 0 8px; }
p { margin: 0 0 12px; }
</style>
```

### Fixed columns

Set `fixed: 'left'` or `fixed: 'right'` on a column. Explicit widths are recommended. Horizontal overflow is detected automatically.

Example source: src/table/__demos__/fixed.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :height="200" :expandable="expandable" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 200,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 400,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    fixed: 'right',
    width: 200,
  },
]

const expandable = {
  title: 'Expand',
  width: 80,
}

const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    expand: 'Expand Content',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Grouped headers with fixed columns

Configure fixed positions on leaf columns. Mark a whole group as fixed only when all its leaf columns belong to the same fixed side.

Example source: src/table/__demos__/columns-children-and-fixed.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :bordered="{ cell: true }" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'User Info',
    children: [
      {
        title: 'Birthday',
        dataIndex: 'birthday',
        fixed: 'left',
        width: 200,
      },
      {
        title: 'Address',
        children: [
          {
            title: 'City',
            dataIndex: 'city',
            fixed: 'left',
            width: 100,
          },
          {
            title: 'Road',
            dataIndex: 'road',
            minWidth: 200,
          },
          {
            title: 'No.',
            dataIndex: 'no',
            minWidth: 120,
          },
        ],
      },
    ],
  },
  {
    title: 'Information',
    children: [
      {
        title: 'Email',
        dataIndex: 'email',
        minWidth: 240,
      },
      {
        title: 'Phone',
        dataIndex: 'phone',
        minWidth: 160,
      },
    ],
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    fixed: 'right',
    width: 120,
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    birthday: '1994-04-21',
    city: 'London',
    road: 'Park',
    no: '34',
    phone: '12345678',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    birthday: '1994-05-21',
    city: 'London',
    road: 'Park',
    no: '37',
    phone: '12345678',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    birthday: '1992-02-11',
    city: 'Paris',
    road: 'Cedar',
    no: '67',
    phone: '12345678',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    birthday: '1991-06-21',
    city: 'London',
    road: 'Park',
    no: '317',
    phone: '12345678',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    birthday: '1996-08-21',
    city: 'Paris',
    road: 'Park',
    no: '114',
    phone: '12345678',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Layout, sizing and column resizing

Compare the same columns by switching layout, fit, grouped headers, resizing and container width in one table.

| Configuration | Behavior |
| --- | --- |
| `table-layout="fixed"` (default) | Computed widths are written to `<col>`; long content does not stretch columns arbitrarily |
| `table-layout="auto"` | The browser allocates actual widths based on content; fixed-column offsets use measured widths |
| `column-resizable` | Resize handles appear only in `fixed` layout; resized widths participate in recalculation |
| `max-height` or column `ellipsis` | Force `fixed` layout |

An explicit `width` stays exact with flexible columns and `fit=true`. If every column has a width, or `fit=false`, proportional expansion still fills the container.

Example source: src/table/__demos__/en-US/column-sizing-playground.vue

```vue
<script setup lang="ts">
import ColumnSizingPlayground from '../column-sizing-playground.vue'
</script>
<template>
  <ColumnSizingPlayground english />
</template>
```

### Automatic scrolling and height

Horizontal overflow follows computed total column width and available container width. Use `height` for a fixed body height or `max-height` for a shrinking body that scrolls when needed. Without either constraint, the page or outer container owns vertical scrolling. Sticky positioning is controlled separately by `sticky-header` / `sticky-pagination`. With horizontal overflow and sticky pagination enabled, hovering over Table or focusing inside Table reveals the synchronized bottom scrollbar.

See the next group for height, header and pagination combinations.

## Headers and column structure

### Columns Children

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Columns Children, Ellipsis And Tooltip, Span Method |
| `data` | Table data | Columns Children, Ellipsis And Tooltip, Span Method |
| `bordered` | Whether to show border | Columns Children, Span Method |
| `span-method` | Cell merge method (The index starts counting from the data item) | Span Method |
| `row-selection` | Table row selector configuration | Span Method |
| `span-all` | Whether to make the index of the span method contain all | Span Method |
<!-- demo-config-notes:end -->


- `columns`: Column info of the table
- `data`: Table data
- `bordered`: Whether to show the border

Example source: src/table/__demos__/columns-children.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :bordered="{ headerCell: true }" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'User Info',
    children: [
      {
        title: 'Birthday',
        dataIndex: 'birthday',
      },
      {
        title: 'Address',
        children: [
          {
            title: 'City',
            dataIndex: 'city',
          },
          {
            title: 'Road',
            dataIndex: 'road',
          },
          {
            title: 'No.',
            dataIndex: 'no',
          },
        ],
      },
    ],
  },
  {
    title: 'Information',
    children: [
      {
        title: 'Email',
        dataIndex: 'email',
      },
      {
        title: 'Phone',
        dataIndex: 'phone',
      },
    ],
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    fixed: 'right',
    width: 120,
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    birthday: '1994-04-21',
    city: 'London',
    road: 'Park',
    no: '34',
    phone: '12345678',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    birthday: '1994-05-21',
    city: 'London',
    road: 'Park',
    no: '37',
    phone: '12345678',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    birthday: '1992-02-11',
    city: 'Paris',
    road: 'Cedar',
    no: '67',
    phone: '12345678',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    birthday: '1991-06-21',
    city: 'London',
    road: 'Park',
    no: '317',
    phone: '12345678',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    birthday: '1996-08-21',
    city: 'Paris',
    road: 'Park',
    no: '114',
    phone: '12345678',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Ellipsis And Tooltip

- `columns`: Column info of the table
- `data`: Table data

Example source: src/table/__demos__/ellipsis-and-tooltip.vue

```vue
<template>
  <c-table :columns="columns" :data="data" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    ellipsis: true,
    tooltip: true,
    width: 100,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
    ellipsis: true,
    width: 150,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    ellipsis: true,
    tooltip: { placement: 'left' },
    width: 200,
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Span Method

- `columns`: Column info of the table
- `data`: Table data
- `span-method`: Cell merge method (The index starts counting from the data item)
- `bordered`: Whether to show the border

Example source: src/table/__demos__/span-method.vue

```vue
<template>
  <c-space direction="column" size="lg" style="width: 100%">
    <c-table :columns="columns" :data="data" :span-method="spanMethod" />
    <c-table :columns="columns" :data="data" :span-method="dataSpanMethod" :bordered="{ wrapper: true, cell: true }" />
    <c-table
      :columns="columns"
      :data="data"
      :row-selection="{ type: 'checkbox' }"
      :span-method="spanMethodAll"
      span-all
      :bordered="{ wrapper: true, cell: true }" />
  </c-space>
</template>

<script lang="ts" setup>
const spanMethod = ({ rowIndex, columnIndex }) => {
  if (rowIndex === 1 && columnIndex === 1) {
    return {
      rowspan: 2,
      colspan: 3,
    }
  }
}
const dataSpanMethod = ({ record, column }) => {
  if (record.name === 'Alisa Ross' && column.dataIndex === 'salary') {
    return {
      rowspan: 2,
    }
  }
}
const spanMethodAll = ({ rowIndex, columnIndex }) => {
  if (rowIndex === 1 && columnIndex === 0) {
    return { rowspan: 2 }
  }

  if (rowIndex === 1 && columnIndex === 2) {
    return {
      rowspan: 2,
      colspan: 3,
    }
  }
}
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
]
</script>
```

### Summary

- `columns`: Column info of the table
- `data`: Table data
- `summary`: Show footer summary row
- `summary-span-method`: Cell Merge Method for Summarizing Rows

Example source: src/table/__demos__/summary.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :summary="true" :summary-span-method="spanMethod" />
  <c-table :columns="columns" :data="data" :height="200" :expandable="expandable" :summary="summary">
    <template #summary-cell="{ column, record, rowIndex }">
      <div :style="getColorStyle(column, record)">{{ record[column.dataIndex] }}</div>
    </template>
  </c-table>
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const expandable = {
  title: 'Expand',
  width: 80,
}
const columns = reactive([
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 200,
    summaryCellStyle: (record) => {
      if (record.salary > 100000) {
        return {
          backgroundColor: 'rgb(var(--brand-6))',
          color: '#fff',
        }
      }
    },
  },
  {
    title: 'Data1',
    dataIndex: 'data1',
    minWidth: 300,
  },
  {
    title: 'Data2',
    dataIndex: 'data2',
    minWidth: 300,
  },
])
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    data1: 10,
    data2: 8,
    expand: 'Expand Content',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    data1: 9,
    data2: -12,
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    data1: 15,
    data2: -2,
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    data1: 2,
    data2: 3,
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    data1: 11,
    data2: 0,
  },
])

const summary = ({ columns, data }) => {
  let countData = {
    salary: 0,
    data1: 0,
    data2: 0,
  }
  data.forEach((record) => {
    countData.salary += record.salary
    countData.data1 += record.data1
    countData.data2 += record.data2
  })

  return [
    {
      name: 'Avg',
      salary: countData.salary / data.length,
      data1: countData.data1 / data.length,
      data2: countData.data2 / data.length,
    },
    {
      name: 'Sum',
      salary: countData.salary,
      data1: countData.data1,
      data2: countData.data2,
    },
  ]
}

const getColorStyle = (column, record) => {
  if (['data1', 'data2'].includes(column.dataIndex)) {
    return { color: record[column.dataIndex] > 0 ? 'red' : 'green' }
  }
  return undefined
}

const spanMethod = ({ rowIndex, columnIndex }) => {
  if (rowIndex === 0 && columnIndex === 1) {
    return {
      colspan: 2,
    }
  }
}
</script>
```

## Scrolling and sticky positioning

### Scroll

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Scroll, Fluid Height, Fixed Column And Header |
| `data` | Table data | Scroll, Fluid Height, Fixed Column And Header |
| `pagination` | Pagination properties configuration | Scroll, Fluid Height, Fixed Column And Header |
| `height` | Table height; fixes the header and scrolls the body. Numbers are px | Scroll, Fixed Column And Header |
| `sticky-header` | Sticky header relative to the page/outer scroller; numeric values are top offsets in px | Sticky Header, Sticky header, pagination and horizontal scrolling |
| `sticky-pagination` | Sticky pagination relative to the page/outer scroller; numeric values are bottom offsets in px | Sticky Panation, Sticky header, pagination and horizontal scrolling |
<!-- demo-config-notes:end -->


- `columns`: Column info of the table
- `data`: Table data
- `height`: Table height. Fixes the header and scrolls the body when set. Number values are in px
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/scroll.vue

```vue
<template>
  <div style="margin-bottom: 16px">
    <c-switch v-model="scrollbar" />
    Virtual Scrollbar
  </div>
  <p style="margin-bottom: 8px">固定高度 <code>height</code>：表头固定，表体纵向滚动。</p>
  <c-table :columns="columns" :data="data" :height="200" :pagination="false" :scrollbar="scrollbar" />
  <br />
  <p style="margin-bottom: 8px">百分比高度：外层定高，表格 <code>height="100%"</code> 填满。</p>
  <div style="height: 220px">
    <c-table :columns="columns" :data="data" height="100%" :pagination="false" :scrollbar="scrollbar" />
  </div>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'

const scrollbar = ref(true)

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 200,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 180,
  },
]

const data = reactive(
  Array.from({ length: 8 }, (_, index) => ({
    key: String(index + 1),
    name: `User ${index + 1}`,
    salary: 17000 + index * 1000,
    address: `${30 + index} Park Road, London`,
    email: `user.${index + 1}@example.com`,
  })),
)
</script>
```

### Fluid Height

- `columns`: Column info of the table
- `data`: Table data
- `max-height`: Table max height. Table shrinks when content is short; body scrolls when exceeded. Number values are in px
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/fluid-height.vue

```vue
<template>
  <p style="margin-bottom: 8px">
    <code>max-height</code> 场景下会强制 <code>table-layout: fixed</code>（与 Element 一致）。内容少时表格收缩，超出后表体滚动；可点按钮增减行观察。
  </p>
  <c-table :columns="columns" :data="data" :max-height="250" :pagination="false" />
  <c-button style="margin-top: 12px; width: 100%" @click="onAddItem">Add Item</c-button>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const columns = [
  {
    title: 'Date',
    dataIndex: 'date',
    fixed: 'left',
    width: 150,
  },
  {
    title: 'Name',
    dataIndex: 'name',
    width: 120,
  },
  {
    title: 'State',
    dataIndex: 'state',
    width: 120,
  },
  {
    title: 'City',
    dataIndex: 'city',
    width: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    width: 600,
  },
  {
    title: 'Zip',
    dataIndex: 'zip',
    width: 120,
  },
  {
    title: 'Operations',
    dataIndex: 'operations',
    fixed: 'right',
    minWidth: 120,
  },
]

let seed = 3
const data = ref([
  {
    key: '1',
    date: '2016-05-01',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  },
  {
    key: '2',
    date: '2016-05-02',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  },
  {
    key: '3',
    date: '2016-05-03',
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  },
])

const onAddItem = () => {
  seed += 1
  data.value.push({
    key: String(seed),
    date: `2016-05-${String(seed).padStart(2, '0')}`,
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Remove',
  })
}
</script>
```

### Fixed Column And Header

- `columns`: Column info of the table
- `data`: Table data
- `height`: Table height. Fixes the header and scrolls the body when set. Number values are in px
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/fixed-column-and-header.vue

```vue
<template>
  <p style="margin-bottom: 8px">
    同时设置 <code>height</code> 与左右 <code>fixed</code> 列：表头固定 + 横向滚动时固定列保持可见。
  </p>
  <c-table :columns="columns" :data="data" :height="250" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = [
  {
    title: 'Date',
    dataIndex: 'date',
    fixed: 'left',
    width: 150,
  },
  {
    title: 'Name',
    dataIndex: 'name',
    width: 120,
  },
  {
    title: 'State',
    dataIndex: 'state',
    width: 120,
  },
  {
    title: 'City',
    dataIndex: 'city',
    width: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 600,
  },
  {
    title: 'Zip',
    dataIndex: 'zip',
    width: 120,
  },
  {
    title: 'Operations',
    dataIndex: 'operations',
    fixed: 'right',
    width: 120,
  },
]

const data = reactive(
  Array.from({ length: 10 }, (_, index) => ({
    key: String(index + 1),
    date: `2016-05-${String(index + 1).padStart(2, '0')}`,
    name: 'Tom',
    state: 'California',
    city: 'Los Angeles',
    address: 'No. 189, Grove St, Los Angeles',
    zip: 'CA 90036',
    operations: 'Detail',
  })),
)
</script>
```

### Sticky Header

- `columns`: Column info of the table
- `data`: Table data
- `sticky-header`: Sticky header relative to the page/outer scroll container (not table body scroll). Number is top offset in px
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/sticky-header.vue

```vue
<template>
  <p style="margin-bottom: 8px; color: var(--color-text-3); font-size: 13px">
    <code>sticky-header</code> 相对页面/外层滚动容器吸顶。传数字可指定距顶部偏移，例如导航高度
    <code>60</code> → <code>top: 60px</code>。请滚动文档页查看效果。
  </p>
  <c-table :columns="columns" :data="data" :sticky-header="60" :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 200,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 180,
  },
]

const data = reactive(
  Array.from({ length: 40 }, (_, index) => ({
    key: String(index + 1),
    name: `User ${index + 1}`,
    salary: 17000 + index * 500,
    address: `${30 + (index % 20)} Park Road, London`,
    email: `user.${index + 1}@example.com`,
  })),
)
</script>
```

### Sticky Panation

- `columns`: Column info of the table
- `data`: Table data
- `sticky-pagination`: Sticky pagination relative to the page/outer scroll container. Number is bottom offset in px
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/sticky-panation.vue

```vue
<template>
  <p style="margin-bottom: 8px; color: var(--color-text-3); font-size: 13px">
    <code>sticky-pagination</code> 相对<strong>页面/外层滚动容器</strong>吸底。适合长列表翻页时分页条常驻视口底部；数字为距底部偏移（px）。
  </p>
  <c-table
    :columns="columns"
    :data="data"
    sticky-pagination
    :pagination="{ pageSize: 20 }"
  />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    width: 140,
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    minWidth: 120,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 200,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 180,
  },
]

const data = reactive(
  Array.from({ length: 80 }, (_, index) => ({
    key: String(index + 1),
    name: `User ${index + 1}`,
    salary: 17000 + index * 500,
    address: `${30 + (index % 20)} Park Road, London`,
    email: `user.${index + 1}@example.com`,
  })),
)
</script>
```

### Sticky header, pagination and horizontal scrolling

Example source: src/table/__demos__/en-US/sticky-layout.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const pageScroll = ref(false)
const custom = ref(false)
const external = ref(false)
const pagerHost = ref<HTMLElement>()
const page = ref(1)
const rows = Array.from({ length: 160 }, (_, index) => ({ key: index + 1, name: `User ${index + 1}`, city: 'Shanghai', email: `user${index + 1}@example.com`, description: `Rightmost field ${index + 1}` }))
const columns = [{ title: 'Name', dataIndex: 'name', width: 200 }, { title: 'City', dataIndex: 'city', width: 200 }, { title: 'Email', dataIndex: 'email', width: 360 }, { title: 'Description', dataIndex: 'description', width: 480 }]
</script>
<template>
 <c-space direction="column">
  <c-space>
   <c-checkbox v-model="pageScroll">Page scrolling</c-checkbox>
   <c-checkbox v-model="custom">Custom pagination</c-checkbox>
   <c-checkbox v-model="external">Move footer outside Table</c-checkbox>
  </c-space>
  <p>The outer container scrolls; Table has no height or vertical scroll setting. Switch to page scrolling to verify the same header/footer.</p>
  <p role="status">Page: {{ page }}</p>
  <div :class="['sticky-table-demo', { 'sticky-table-demo--page': pageScroll }]">
   <c-table
    :columns="columns" :data="rows"
    :sticky-header="0" :sticky-pagination="0"
    :pagination="{ modelValue: page, pageSize: 40, container: external ? pagerHost : undefined }"
    @page-change="page = $event"
   >
    <template v-if="custom" #pagination="{ page: current, pageSize, total, onChange }">
     <c-space>
      <c-button :disabled="current <= 1" @click="onChange(current - 1)">Previous</c-button>
      <span>{{ current }} / {{ Math.max(1, Math.ceil(total / pageSize)) }}</span>
      <c-button :disabled="current * pageSize >= total" @click="onChange(current + 1)">Next</c-button>
     </c-space>
    </template>
   </c-table>
   <div ref="pagerHost" class="sticky-table-pagination-host" />
  </div>
 </c-space>
</template>
<style scoped>
.sticky-table-demo { max-height: 420px; overflow: auto; isolation: isolate; }
.sticky-table-demo--page { max-height: none; overflow: visible; }
.sticky-table-pagination-host { display: contents; }
</style>
```

sticky-header and sticky-pagination follow the page or outer scroll container. A numeric zero enables the feature with zero offset. This differs from using height/max-height to constrain internal body scrolling. Avoid an extra overflow:hidden ancestor that interrupts sticky positioning.

Built-in sticky pagination keeps a synchronized horizontal rail above the pagination in the same sticky footer. The rail follows body scroll in both directions, and is omitted when content fits. Pagination no longer obscures the only reachable horizontal scroll control.

| Property | Behavior |
| --- | --- |
| pagination=true | Built-in pagination with its defaults |
| pagination={ pageSize, total, ... } | Configure built-in pagination; total does not fetch server data |
| pagination=false | No built-in pagination UI or slicing; the caller owns the current-page rows |
| sticky-header=true or number | Stick the header; a number sets its top offset |
| sticky-pagination=true or number | Stick the pagination and horizontal rail; a number sets its bottom offset |
| style="width: 100%" | Set the table container width; column widths determine horizontal overflow automatically |

For external pagination, pass pagination=false and render a separate Pagination component. Slice local data before passing it to Table, or request a server page. The business layout owns positioning and scrollbar clearance in that mode. The example switches between built-in sticky pagination and this fully external mode.

### Replace pagination content inside the managed footer

The pagination slot receives { page, pageSize, total, onChange, onPageSizeChange }. Render a business pagination component there to replace the built-in widget while Table keeps data slicing and the scrollbar-above-pagination layout. Keep this content in normal flow inside the footer. pagination=false instead disables the entire built-in pagination protocol.

`--c-table-sticky-scrollbar-height` sets the minimum horizontal rail height (16px by default); intrinsic sizing also reserves the native scrollbar height.

### Mount pagination externally

`pagination.container` accepts a CSS selector or HTMLElement. Omitting it keeps the footer inside Table. Only placement changes: page state, slicing, events and the sticky horizontal rail remain managed by Table. No slot or separate pager state is required. Keep the host in the same scroll context and use display: contents when needed. The target must exist; Vue 3.5 defer supports targets created in the same render batch. SSR hosts must handle Teleport output. pagination=false still disables Table pagination and slicing entirely.

```vue
<c-table
  :data="rows" :columns="columns"
  :sticky-header="0" :sticky-pagination="0"
  :pagination="{ pageSize: 10, total: 500, container: '#table-pagination' }"
/>
<div id="table-pagination" style="display: contents" />
```

The sticky layout demo provides an outer scrolling container. Table itself has no height/max-height or vertical scroll limit. Toggle page scrolling, custom pagination, and an external footer host. The Table-owned footer groups the synchronized horizontal scrollbar and the pagination slot, and moves them together when pagination.container is set. The external host must remain in the intended scrolling/layout boundary; arbitrary destinations do not remove CSS sticky constraints.

Sticky pagination suppresses the internal horizontal thumb/native scrollbar and reuses the shared Scrollbar in embed mode above the footer. It appears while the pointer is over Table or keyboard focus is inside Table, including when the footer is mounted externally; dragging, track clicks and trackpad scrolling remain synchronized. Vertical scrolling remains owned by the demo container unless Table height/max-height is explicitly set.

## Selection and data interaction

### Row Selection

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Row Selection, Row Selection Single, Expandable |
| `data` | Table data | Row Selection, Row Selection Single, Expandable |
| `row-selection` | Table row selector configuration | Row Selection, Row Selection Single, Tree Children |
| `draggable` | Table drag and drop sorting configuration | Droppable Table, Droppable Anchor |
| `selected-keys` | Selected row (controlled mode) takes precedence over `rowSelection` | Row Selection |
| `pagination` | Pagination properties configuration | Row Selection |
<!-- demo-config-notes:end -->


- `selected-keys`: Selected row (controlled mode) takes precedence over `rowSelection`
- `columns`: Column info of the table
- `data`: Table data
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/row-selection.vue

```vue
<template>
  <c-space direction="column" fill size="lg">
    <div>
      <span>OnlyCurrent:</span>
      <c-switch v-model="rowSelection.onlyCurrent" />
    </div>
    <c-table
      v-model:selectedKeys="selectedKeys"
      :columns="columns"
      :data="data"
      :pagination="pagination"
      :row-selection="rowSelection"
      row-key="name" />
  </c-space>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const selectedKeys = ref(['Jane Doe', 'Alisa Ross'])

const rowSelection = reactive({
  type: 'checkbox',
  showCheckedAll: true,
  onlyCurrent: false,
})
const pagination = { pageSize: 5 }

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
    disabled: true,
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
  {
    key: '6',
    name: 'Jane Doe 2',
    salary: 15000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '7',
    name: 'Alisa Ross 2',
    salary: 28000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '8',
    name: 'Kevin Sandra 2',
    salary: 26000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '9',
    name: 'Ed Hellen 2',
    salary: 18000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '10',
    name: 'William Smith 2',
    salary: 12000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Row Selection Single

- `columns`: Column info of the table
- `data`: Table data
- `row-selection`: Table row selector configuration

Example source: src/table/__demos__/row-selection-single.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :row-selection="rowSelection" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const rowSelection = {
  type: 'radio',
}
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Expandable

- `columns`: Column info of the table
- `data`: Table data
- `expandable`: Expand row configuration of the table

Example source: src/table/__demos__/expandable.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :expandable="expandable" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const expandable = reactive({
  title: 'Expand',
  width: 80,
  expandedRowRender: (record) => {
    if (record.key === '3') {
      return `My Name is ${record.name}`
    }
  },
})

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]

const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    expand: 'Expand Data',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
</script>
```

### Tree Children

- `columns`: Column info of the table
- `data`: Table data
- `expanded-keys`: Displayed Expanded Row, Subtree (Controlled Mode) takes precedence over `expandable`
- `row-selection`: Table row selector configuration

Example source: src/table/__demos__/tree-children.vue

```vue
<template>
  <c-space>
    <span>checkStrictly:</span>
    <c-switch v-model="rowSelection.checkStrictly" />
  </c-space>
  <c-table
    :columns="columns"
    :data="data"
    v-model:expandedKeys="expandedKeys"
    :row-selection="rowSelection"
    show-empty-tree
    style="margin-top: 20px" />
</template>

<script lang="ts" setup>
import { ref, reactive } from 'vue'
const expandedKeys = ref([])

const rowSelection = reactive({
  type: 'checkbox',
  showCheckedAll: true,
  checkStrictly: true,
})

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    children: [
      {
        key: '2',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
        children: [
          {
            key: '3',
            name: 'Ed Hellen',
            salary: 17000,
            address: '42 Park Road, London',
            email: 'ed.hellen@example.com',
          },
          {
            key: '4',
            name: 'William Smith',
            salary: 27000,
            address: '62 Park Road, London',
            email: 'william.smith@example.com',
          },
        ],
      },
      {
        key: '5',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
      },
    ],
  },
  {
    key: '6',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '7',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '8',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '9',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
    children: [],
  },
]
</script>
```

### Sort And Filter

- `columns`: Column info of the table
- `data`: Table data
- `filter-icon-align-left`: Whether the filter icon is aligned to the left

Example source: src/table/__demos__/sort-and-filter.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-space>
      <c-switch v-model="alignLeft" />
      <span>Filter icon align left: {{ alignLeft }}</span>
    </c-space>
    <c-table :columns="columns" :data="data" :filter-icon-align-left="alignLeft" @change="handleChange" />
  </c-space>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const alignLeft = ref(false)

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    sortable: {
      sortDirections: ['ascend', 'descend'],
    },
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    sortable: {
      sortDirections: ['ascend'],
    },
    filterable: {
      filters: [
        {
          text: '> 20000',
          value: '20000',
        },
        {
          text: '> 30000',
          value: '30000',
        },
      ],
      filter: (value, record) => record.salary > value,
      multiple: true,
    },
  },
  {
    title: 'Address',
    dataIndex: 'address',
    filterable: {
      filters: [
        {
          text: 'London',
          value: 'London',
        },
        {
          text: 'Paris',
          value: 'Paris',
        },
      ],
      filter: (value, row) => row.address.includes(value),
    },
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])

const handleChange = (data, extra, currentDataSource) => {
  console.log('change', data, extra, currentDataSource)
}
</script>
```

### Droppable Table

- `columns`: Column info of the table
- `data`: Table data
- `draggable`: Table drag and drop sorting configuration

Example source: src/table/__demos__/droppable-table.vue

```vue
<template>
  <c-table :columns="columns" :data="data" @change="handleChange" :draggable="{}"></c-table>
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const columns = reactive([
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
])
const data = ref([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
const handleChange = (_data) => {
  console.log(_data)
  data.value = _data
}
</script>
```

### Droppable Anchor

- `columns`: Column info of the table
- `data`: Table data
- `draggable`: Table drag and drop sorting configuration

Example source: src/table/__demos__/droppable-anchor.vue

```vue
<template>
  <c-table :columns="columns" :data="data" @change="handleChange" :draggable="{ type: 'handle', width: 40 }" />
</template>

<script lang="ts" setup>
import { reactive, ref } from 'vue'
const columns = reactive([
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
])
const data = ref([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])
const handleChange = (_data) => {
  console.log(_data)
  data.value = _data
}
</script>
```

### Editable Form

- `columns`: Column info of the table
- `data`: Table data

Example source: src/table/__demos__/editable-form.vue

```vue
<template>
  <c-table :columns="columns" :data="data">
    <template #name="{ rowIndex }">
      <c-input v-model="data[rowIndex].name" />
    </template>
    <template #province="{ rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          v-model="data[rowIndex].province"
          @change="() => handleChange(rowIndex)"
        >
          <c-option v-for="value of Object.keys(options)">{{ value }}</c-option>
        </c-select>
      </c-form-item>
    </template>
    <template #city="{ rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          :options="options[data[rowIndex].province] || []"
          v-model="data[rowIndex].city"
        />
      </c-form-item>
    </template>
  </c-table>
  <!-- support from v2.25.0  -->
  <c-table :columns="columns" :data="data" style="margin-top: 20px">
    <template #name="{ record, rowIndex }">
      <c-input v-model="record.name" />
    </template>
    <template #province="{ record, rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          v-model="record.province"
          @change="
            () => {
              record.city = '';
            }
          "
        >
          <c-option v-for="value of Object.keys(options)">{{ value }}</c-option>
        </c-select>
      </c-form-item>
    </template>
    <template #city="{ record, rowIndex }">
      <c-form-item layout="vertical" hide-label>
        <c-select
          :options="options[record.province] || []"
          v-model="record.city"
        />
      </c-form-item>
    </template>
  </c-table>
</template>

<script lang="ts" setup>
import { reactive } from "vue";
const options = {
  Beijing: ["Haidian", "Chaoyang", "Changping"],
  Sichuan: ["Chengdu", "Mianyang", "Aba"],
  Guangdong: ["Guangzhou", "Shenzhen", "Shantou"],
};
const columns = [
  {
    title: "Name",
    dataIndex: "name",
    slotName: "name",
  },
  {
    title: "Salary",
    dataIndex: "salary",
  },
  {
    title: "Address",
    dataIndex: "address",
  },
  {
    title: "Province",
    dataIndex: "province",
    slotName: "province",
  },
  {
    title: "City",
    dataIndex: "city",
    slotName: "city",
  },
  {
    title: "Email",
    dataIndex: "email",
  },
];

const data = reactive([
  {
    key: "1",
    name: "Jane Doe",
    salary: 23000,
    address: "32 Park Road, London",
    province: "Beijing",
    city: "Haidian",
    email: "jane.doe@example.com",
  },
  {
    key: "2",
    name: "Alisa Ross",
    salary: 25000,
    address: "35 Park Road, London",
    email: "alisa.ross@example.com",
  },
  {
    key: "3",
    name: "Kevin Sandra",
    salary: 22000,
    address: "31 Park Road, London",
    province: "Sichuan",
    city: "Mianyang",
    email: "kevin.sandra@example.com",
  },
  {
    key: "4",
    name: "Ed Hellen",
    salary: 17000,
    address: "42 Park Road, London",
    email: "ed.hellen@example.com",
  },
  {
    key: "5",
    name: "William Smith",
    salary: 27000,
    address: "62 Park Road, London",
    email: "william.smith@example.com",
  },
]);

const handleChange = (rowIndex) => {
  data[rowIndex].city = "";
};
</script>
```

## Column management and rendering

### Column Manager Basic

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Column Manager Basic, Custom Filter, Custom Rendering |
| `data` | Table data | Column Manager Basic, Custom Filter, Custom Rendering |
| `pagination` | Pagination properties configuration | Column Manager Basic |
| `size` | The size of the table | Column Manager Basic |
| `row-class` | Class for table-row elements | Customize Table Elements |
<!-- demo-config-notes:end -->


- `columns`: Column info of the table
- `data`: Table data
- `pagination`: Pagination properties configuration
- `size`: The size of the table

Example source: src/table/__demos__/column-manager-basic.vue

```vue
<template>
  <c-space wrap justify="flex-end" style="margin-bottom: 8px">
    <c-link @click="visible = true">列管理</c-link>
  </c-space>

  <c-table
    v-model:columns="columns"
    :data="data"
    :pagination="false"
    size="xs"
  />

  <c-drawer
    v-model:open="visible"
    title="列管理"
    :width="720"
    unmount-on-close
    @confirm="handleConfirm"
  >
    <div style="height: calc(100vh - 120px)">
      <c-table-column-manager
        ref="mgrRef"
        v-model="items"
        :columns="columns"
        :options="columnDefinitions"
      />
    </div>
  </c-drawer>
</template>

<script setup lang="ts">
import { ref, watch } from "vue";
import { stateFromColumns } from "@cedar-design/ui";
import type {
  ColumnDefinitions,
  TableColumnData,
  TableColumnManagerInstance,
} from "@cedar-design/ui";

const visible = ref(false);
const mgrRef = ref<TableColumnManagerInstance>();
const items = ref([]);

const columns = ref<TableColumnData[]>([
  { dataIndex: "name", title: "姓名", width: 120 },
  { dataIndex: "salary", title: "薪资", width: 100 },
  { dataIndex: "address", title: "地址", width: 180 },
]);

const columnDefinitions: ColumnDefinitions = [
  {
    title: "基础",
    key: "basic",
    children: [
      { dataIndex: "name", title: "姓名", required: true },
      { dataIndex: "salary", title: "薪资" },
      { dataIndex: "email", title: "邮箱" },
      { dataIndex: "address", title: "地址" },
    ],
  },
];

watch(visible, (val) => {
  if (!val) return;
  const state = stateFromColumns(columns.value, columnDefinitions);
  items.value = state.items;
});

const handleConfirm = () => {
  const result = mgrRef.value?.getResult?.();
  if (result) columns.value = result.columns;
  visible.value = false;
};

const data = ref([
  { name: "Jane", salary: 23000, address: "London", email: "jane@example.com" },
  {
    name: "Alisa",
    salary: 25000,
    address: "Paris",
    email: "alisa@example.com",
  },
]);
</script>
```

Example source: src/table/__demos__/custom-table-columns.vue

```vue
<template>
  <c-space wrap size="12px" justify="flex-end" style="margin-bottom: 8px">
    <c-link @click="open">列管理</c-link>
    <c-link @click="resetColumns">重置列</c-link>
  </c-space>

  <c-table
    v-model:columns="columns"
    :data="data"
    :pagination="false"
    size="xs"
  />

  <c-table-column-manager v-bind="managerProps" />
</template>

<script lang="ts" setup>
import { onMounted, ref, watch } from "vue";
import { useTableColumnManager } from "@cedar-design/ui";
import type { ColumnDefinitions, ManagedTableColumn } from "@cedar-design/ui";

const STORAGE_KEY = "cedar-demo-table-columns";
let storage: Storage | undefined;
const storageReady = ref(false);

const defaultColumns: ManagedTableColumn[] = [
  {
    dataIndex: "connectorId",
    title: "枪ID",
    width: 100,
    fixed: "left",
    manager: { required: true },
  },
  { dataIndex: "connectorName", title: "枪名称", width: 120 },
  {
    dataIndex: "deviceName",
    title: "设备名称",
    width: 140,
    manager: { required: true },
  },
];

const columnDefinitions: ColumnDefinitions = [
  {
    title: "枪基本信息",
    key: "connectorBasicInfo",
    children: [
      {
        dataIndex: "connectorId",
        title: "枪ID",
        tip: "必选列",
      },
      { dataIndex: "connectorName", title: "枪名称" },
      { dataIndex: "connectorNo", title: "枪序号" },
      { dataIndex: "workingStatus", title: "工作状态" },
      { dataIndex: "connectStatus", title: "连接状态" },
      { dataIndex: "parkNo", title: "停车位" },
    ],
  },
  {
    title: "桩基本信息",
    key: "chargerBasicInfo",
    children: [
      { dataIndex: "deviceId", title: "设备ID" },
      {
        dataIndex: "deviceName",
        title: "设备名称",
        tip: "必选规则来自 defaultColumns",
      },
      { dataIndex: "lockStatus", title: "地锁" },
      { dataIndex: "ratedVoltage", title: "额定电压" },
    ],
  },
  {
    title: "其他信息",
    key: "other",
    children: [
      { dataIndex: "batteryStatus", title: "电池状态" },
      { dataIndex: "temperature", title: "温度" },
      { dataIndex: "current", title: "电流" },
      { dataIndex: "power", title: "功率" },
      { dataIndex: "action", title: "操作" },
    ],
  },
];

const { columns, state, restore, managerProps, open, resetToDefault } =
  useTableColumnManager({
    defaultColumns,
    columnDefinitions,
    columnDefaults: { width: 110, ellipsis: true },
    createColumn: (definition) => ({
      dataIndex: definition.dataIndex,
      title: definition.title,
      ...(definition.dataIndex === "action"
        ? { width: 100, fixed: "right" }
        : {}),
    }),
  });

onMounted(async () => {
  storage = window.localStorage;
  try {
    const raw = storage.getItem(STORAGE_KEY);
    if (raw) await restore(JSON.parse(raw));
  } catch {
    storage.removeItem(STORAGE_KEY);
  } finally {
    storageReady.value = true;
  }
});

watch(
  state,
  (value) => {
    if (!storageReady.value) return;
    storage?.setItem(STORAGE_KEY, JSON.stringify(value));
  },
  { deep: true },
);

const resetColumns = () => {
  try {
    storage?.removeItem(STORAGE_KEY);
  } catch {
    // ignore
  }
  resetToDefault();
};

const data = ref([
  {
    connectorId: "1",
    connectorName: "Jane Doe",
    connectorNo: "001",
    workingStatus: "正常",
    connectStatus: "连接中",
    parkNo: "A1",
    deviceId: "D001",
    deviceName: "Device A",
    lockStatus: "解锁",
    ratedVoltage: "220V",
    batteryStatus: "良好",
    temperature: "36",
    current: "10A",
    power: "2kW",
    action: "详情",
  },
]);
</script>
```

### Custom Filter

- `columns`: Column info of the table
- `data`: Table data

Example source: src/table/__demos__/custom-filter.vue

```vue
<template>
  <c-table :columns="columns" :data="data" @change="handleChange">
    <template #name-filter="{ filterValue, setFilterValue, handleFilterConfirm, handleFilterReset }">
      <div class="custom-filter">
        <c-space direction="column">
          <c-input :model-value="filterValue[0]" @input="(value) => setFilterValue([value])" />
          <div class="custom-filter-footer">
            <c-button @click="handleFilterConfirm">Confirm</c-button>
            <c-button @click="handleFilterReset">Reset</c-button>
          </div>
        </c-space>
      </div>
    </template>
  </c-table>
</template>

<script lang="ts" setup>
import { reactive, h } from 'vue'
import { Search } from '@cedar-design/ui'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    filterable: {
      filter: (value, record) => record.name.includes(value),
      slotName: 'name-filter',
      icon: () => h(Search),
    },
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
    sortable: {
      sortDirections: ['ascend'],
    },
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
])

const handleChange = (data, extra, currentDataSource) => {
  console.log('change', data, extra, currentDataSource)
}
</script>

<style>
.custom-filter {
  padding: 20px;
  background: var(--color-bg-5);
  border: 1px solid var(--color-neutral-3);
  border-radius: var(--border-radius-medium);
  box-shadow: 0 2px 5px rgb(0 0 0 / 10%);
}

.custom-filter-footer {
  display: flex;
  justify-content: space-between;
}
</style>
```

### Custom Rendering

- `columns`: Column info of the table
- `data`: Table data

Example source: src/table/__demos__/custom-rendering.vue

```vue
<template>
  <c-table :columns="columns" :data="data">
    <template #optional="{ record }">
      <c-button @click="$dialog.info({ title: 'Name', content: record.name })">view</c-button>
    </template>
  </c-table>
  <c-table :data="data" style="margin-top: 30px">
    <template #columns>
      <c-table-column title="Name">
        <c-table-column data-index="first" title="First Name"></c-table-column>
        <c-table-column data-index="last" title="Last Name"></c-table-column>
      </c-table-column>
      <c-table-column data-index="salary" title="Salary"></c-table-column>
      <c-table-column data-index="address" title="Address"></c-table-column>
      <c-table-column data-index="email" title="Email"></c-table-column>
      <c-table-column title="Optional">
        <template #cell="{ record }">
          <c-button @click="$dialog.info({ title: 'Name', content: record.name })">view</c-button>
        </template>
      </c-table-column>
    </template>
  </c-table>
</template>

<script>
import { ref } from 'vue'
export default {
  setup() {
    const show = ref(true)

    const columns = [
      {
        title: 'Name',
        dataIndex: 'name',
      },
      {
        title: 'Salary',
        dataIndex: 'salary',
      },
      {
        title: 'Address',
        dataIndex: 'address',
      },
      {
        title: 'Email',
        dataIndex: 'email',
      },
      {
        title: 'Optional',
        slotName: 'optional',
      },
    ]
    const data = [
      {
        key: '1',
        name: 'Jane Doe',
        first: 'Jane',
        last: 'Doe',
        salary: 23000,
        address: '32 Park Road, London',
        email: 'jane.doe@example.com',
      },
      {
        key: '2',
        name: 'Alisa Ross',
        first: 'Alisa',
        last: 'Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
      },
      {
        key: '3',
        name: 'Kevin Sandra',
        first: 'Kevin',
        last: 'Sandra',
        salary: 22000,
        address: '31 Park Road, London',
        email: 'kevin.sandra@example.com',
      },
      {
        key: '4',
        name: 'Ed Hellen',
        first: 'Ed',
        last: 'Hellen',
        salary: 17000,
        address: '42 Park Road, London',
        email: 'ed.hellen@example.com',
      },
      {
        key: '5',
        name: 'William Smith',
        first: 'William',
        last: 'Smith',
        salary: 27000,
        address: '62 Park Road, London',
        email: 'william.smith@example.com',
      },
    ]

    return {
      columns,
      data,
      show,
    }
  },
}
</script>
```

### Customize Table Elements

- `columns`: Column info of the table
- `data`: Table data
- `row-class`: The class name of the table row element. The `2.34.0` version adds support for function values.

Example source: src/table/__demos__/customize-table-elements.vue

```vue
<template>
  <c-table :columns="columns" :data="data" row-class="common-row">
    <template #tr>
      <tr class="my-tr" @contextmenu.prevent="onContextMenu" />
    </template>
    <template #td>
      <td class="my-td" />
    </template>
  </c-table>
  <c-tag>行右键回调：{{ contextMenus }}</c-tag>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const contextMenus = ref(0)
const onContextMenu = () => {
  contextMenus.value++
}

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
]
</script>
```

## Async and large datasets

### Load More

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Load More, Column Manager Async, Virtual List Props |
| `data` | Table data | Load More, Column Manager Async, Virtual List Props |
| `pagination` | Pagination properties configuration | Column Manager Async, Virtual List Props |
| `load-more` | Load children asynchronously; call done(children), or done() to allow retry | Load More |
| `size` | The size of the table | Column Manager Async |
| `row-selection` | Table row selector configuration | Virtual List Props |
<!-- demo-config-notes:end -->


- `columns`: Column info of the table
- `data`: Table data
- `load-more`: Data lazy loading function, open the lazy loading function when it is passed in

Example source: src/table/__demos__/load-more.vue

```vue
<template>
  <c-table :columns="columns" :data="data" :load-more="loadMore" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]
const data = reactive([
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
    children: [
      {
        key: '2',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
      },
      {
        key: '5',
        name: 'Alisa Ross',
        salary: 25000,
        address: '35 Park Road, London',
        email: 'alisa.ross@example.com',
        isLeaf: true,
      },
    ],
  },
  {
    key: '6',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '7',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
    isLeaf: true,
  },
  {
    key: '8',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
    isLeaf: true,
  },
  {
    key: '9',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
    isLeaf: true,
  },
])

const loadMore = (record, done) => {
  window.setTimeout(() => {
    done([
      {
        key: `${record.key}-1`,
        name: 'Ed Hellen',
        salary: 17000,
        address: '42 Park Road, London',
        email: 'ed.hellen@example.com',
        isLeaf: true,
      },
      {
        key: `${record.key}-2`,
        name: 'William Smith',
        salary: 27000,
        address: '62 Park Road, London',
        email: 'william.smith@example.com',
        isLeaf: true,
      },
    ])
  }, 2000)
}
</script>
```

### Column Manager Async

- `columns`: Column info of the table
- `data`: Table data
- `pagination`: Pagination properties configuration
- `size`: The size of the table

Example source: src/table/__demos__/column-manager-async.vue

```vue
<template>
  <c-space wrap justify="flex-end" style="margin-bottom: 8px">
    <c-link @click="visible = true">列管理</c-link>
  </c-space>

  <c-table
    v-model:columns="columns"
    :data="data"
    :pagination="false"
    size="xs"
  />

  <c-drawer
    v-model:open="visible"
    title="列管理"
    :width="720"
    unmount-on-close
    @confirm="handleConfirm"
  >
    <div style="height: calc(100vh - 120px)">
      <c-table-column-manager
        ref="mgrRef"
        v-model="items"
        :columns="columns"
        :load-options="loadOptions"
      />
    </div>
  </c-drawer>
</template>

<script setup lang="ts">
import { ref, watch } from "vue";
import { stateFromColumns } from "@cedar-design/ui";
import type {
  ColumnDefinitions,
  TableColumnData,
  TableColumnManagerInstance,
} from "@cedar-design/ui";

const visible = ref(false);
const mgrRef = ref<TableColumnManagerInstance>();
const items = ref([]);

const columns = ref<TableColumnData[]>([
  { dataIndex: "name", title: "姓名", width: 120 },
  { dataIndex: "salary", title: "薪资", width: 100 },
]);

const loadOptions = async (): Promise<ColumnDefinitions> => {
  await new Promise((r) => setTimeout(r, 400));
  return [
    {
      title: "基础",
      key: "basic",
      children: [
        { dataIndex: "name", title: "姓名", required: true },
        { dataIndex: "salary", title: "薪资" },
        { dataIndex: "email", title: "邮箱" },
        { dataIndex: "address", title: "地址" },
      ],
    },
  ];
};

watch(visible, async (val) => {
  if (!val) return;
  const columnDefinitions = await loadOptions();
  const state = stateFromColumns(columns.value, columnDefinitions);
  items.value = state.items;
});

const handleConfirm = () => {
  const result = mgrRef.value?.getResult?.();
  if (result) columns.value = result.columns;
  visible.value = false;
};

const data = ref([
  { name: "Jane", salary: 23000, address: "London", email: "jane@example.com" },
]);
</script>
```

### Virtual List Props

- `columns`: Column info of the table
- `data`: Table data
- `row-selection`: Table row selector configuration
- `virtual-list-props`: Pass the virtual list attribute, pass in this parameter to turn on virtual scrolling [VirtualListProps](#VirtualListProps)

Example source: src/table/__demos__/virtual-list-props.vue

```vue
<template>
  <c-table
    :columns="columns"
    :data="data"
    :row-selection="rowSelection"
    :virtual-list-props="{ height: 400 }"
    :pagination="false" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
    fixed: 'left',
    width: 140,
  },
  {
    title: 'Address',
    dataIndex: 'address',
    minWidth: 400,
  },
  {
    title: 'Email',
    dataIndex: 'email',
    minWidth: 300,
  },
]
const data = reactive(
  Array(1000)
    .fill(null)
    .map((_, index) => ({
      key: String(index),
      name: `User ${index + 1}`,
      address: '32 Park Road, London',
      email: `user.${index + 1}@example.com`,
    })),
)
const rowSelection = {
  type: 'checkbox',
  showCheckedAll: true,
}
</script>
```

## Business workflows

### Typed Config

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `columns` | Column info of the table | Task Workbench, Form Attribute |
| `data` | Table data | Task Workbench, Form Attribute |
| `pagination` | Pagination properties configuration | Task Workbench |
| `bordered` | Whether to show border | Form Attribute |
| `hoverable` | Whether to show the hover effect | Form Attribute |
| `stripe` | Whether to enable the stripe effect | Form Attribute |
<!-- demo-config-notes:end -->


Example source: src/table/__demos__/typed-config.vue

```vue
<script setup lang="ts">
import { computed, ref } from 'vue'
import { defineTableConfig } from '@cedar-design/ui'
interface User {
  id: string
  name: string
  age: number
  profile: { city: string }
}
const rows = ref<User[]>([
  { id: 'alice', name: 'Alice', age: 28, profile: { city: '杭州' } },
  { id: 'bob', name: 'Bob', age: 16, profile: { city: '宁波' } },
])
const config = computed(() => defineTableConfig<User>({
  rowKey: 'id',
  data: rows.value,
  pagination: false,
  columns: [
    { title: '姓名', dataIndex: 'name', render: ({ record }) => record.name.toUpperCase() },
    { title: '城市', dataIndex: 'profile.city' },
    { title: '年龄', dataIndex: 'age',
      sortable: { sortDirections: ['ascend', 'descend'], sorter: (a, b) => a.age - b.age },
      filterable: { filters: [{ text: '仅成年人', value: 'adult' }], filter: (values, record) => !values.length || !values.includes('adult') || record.age >= 18 },
    },
  ],
}))
function addRow() {
  if (rows.value.length < 3) rows.value = [...rows.value, { id: 'carol', name: 'Carol', age: 35, profile: { city: '上海' } }]
}
</script>
<template>
  <c-space direction="column" fill>
    <c-button :disabled="rows.length >= 3" @click="addRow">增加一行</c-button>
    <c-table v-bind="config" />
    <p role="status">业务数据：{{ rows.length }} 行；年龄列支持排序和筛选。</p>
  </c-space>
</template>
```

### Task Workbench

- `columns`: Column info of the table
- `data`: Table data
- `pagination`: Pagination properties configuration

Example source: src/table/__demos__/task-workbench.vue

```vue
<script setup>
import { computed, ref } from "vue";
const original = () => [
  { key: "01", name: "展厅设备巡检", department: "运营部", status: "待处理" },
  { key: "02", name: "网站交互验收", department: "研发部", status: "进行中" },
  { key: "03", name: "品牌物料审核", department: "设计部", status: "待处理" },
  { key: "04", name: "移动端体验走查", department: "研发部", status: "已完成" },
  { key: "05", name: "会议室设备维护", department: "运营部", status: "进行中" },
];
const rows = ref(original());
const keyword = ref("");
const status = ref("全部");
const applied = ref({ keyword: "", status: "全部" });
const message = ref("显示全部任务。输入条件后点击查询。");
const options = ["全部", "待处理", "进行中", "已完成"].map((value) => ({
  value,
  label: value,
}));
const filtered = computed(() =>
  rows.value.filter(
    (row) =>
      (!applied.value.keyword ||
        `${row.name} ${row.department}`.includes(applied.value.keyword)) &&
      (applied.value.status === "全部" || row.status === applied.value.status),
  ),
);
const completed = computed(
  () => rows.value.filter((row) => row.status === "已完成").length,
);
const columns = [
  { title: "任务", dataIndex: "name" },
  { title: "部门", dataIndex: "department" },
  { title: "状态", dataIndex: "status" },
  { title: "操作", slotName: "action" },
];
function search() {
  applied.value = { keyword: keyword.value.trim(), status: status.value };
  message.value = `查询完成，找到 ${filtered.value.length} 条任务。`;
}
function clear() {
  keyword.value = "";
  status.value = "全部";
  applied.value = { keyword: "", status: "全部" };
  message.value = "已清空筛选条件。";
}
function finish(row) {
  row.status = "已完成";
  message.value = `已完成“${row.name}”，统计与列表已同步。`;
}
function reset() {
  rows.value = original();
  clear();
  message.value = "任务和筛选已恢复，可以重新演示。";
}
</script>
<template>
  <section class="task-workbench" aria-label="巡检任务数据联动">
    <div class="task-workbench__metrics">
      <span
        >全部 <strong>{{ rows.length }}</strong></span
      ><span
        >已完成 <strong>{{ completed }}</strong></span
      ><span
        >当前结果 <strong>{{ filtered.length }}</strong></span
      >
    </div>
    <c-form :model="applied" layout="vertical" @submit="search">
      <c-form-item label="搜索任务或部门"
        ><c-input
          v-model="keyword"
          edit-mode="direct"
          placeholder="搜索任务或部门"
          clearable
      /></c-form-item>
      <c-form-item label="任务状态"
        ><c-select v-model="status" :options="options" edit-mode="direct"
      /></c-form-item>
      <c-space wrap
        ><c-button html-type="submit" status="primary">查询任务</c-button
        ><c-button @click="clear">清空筛选</c-button
        ><c-button @click="reset">恢复全部任务</c-button></c-space
      >
    </c-form>
    <p role="status" aria-live="polite">{{ message }}</p>
    <c-table :columns="columns" :data="filtered" :pagination="false"
      ><template #action="{ record }"
        ><c-button
          :disabled="record.status === '已完成'"
          :aria-label="`完成${record.name}`"
          @click="finish(record)"
          >完成</c-button
        ></template
      ></c-table
    >
    <p v-if="!filtered.length">
      没有匹配任务。修改关键词或点击“清空筛选”恢复结果。
    </p>
    <small
      >先查询“运营部”，完成一条任务，再用状态过滤；统计与结果来自同一份本地任务数据。</small
    >
  </section>
</template>
<style scoped>
.task-workbench {
  min-width: 0;
  width: 100%;
}
.task-workbench__metrics {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  margin-bottom: 16px;
}
.task-workbench__metrics > span {
  padding: 12px 16px;
  background: var(--c-color-fill-1);
  border-radius: 8px;
}
.task-workbench__metrics strong {
  margin-left: 8px;
  color: var(--c-color-primary);
}
.task-workbench small {
  display: block;
  margin-top: 8px;
  color: var(--c-color-text-2);
}
</style>
```

### Form Attribute

- `columns`: Column info of the table
- `data`: Table data
- `bordered`: Whether to show the border
- `hoverable`: Whether to show the hover effect

Example source: src/table/__demos__/form-attribute.vue

```vue
<template>
  <c-form layout="inline" :model="form">
    <c-form-item label="Border" field="border">
      <c-switch v-model="form.border" />
    </c-form-item>
    <c-form-item label="Hover" field="hover">
      <c-switch v-model="form.hover" />
    </c-form-item>
    <c-form-item label="stripe" field="stripe">
      <c-switch v-model="form.stripe" />
    </c-form-item>
    <c-form-item label="checkbox" field="checkbox">
      <c-switch v-model="form.checkbox" />
    </c-form-item>
    <c-form-item label="checkAll" field="checkAll">
      <c-switch v-model="rowSelection.showCheckedAll" />
    </c-form-item>
    <c-form-item label="loading" field="loading">
      <c-switch v-model="form.loading" />
    </c-form-item>
    <c-form-item label="tableHeader" field="tableHeader">
      <c-switch v-model="form.tableHeader" />
    </c-form-item>
    <c-form-item label="noData" field="noData">
      <c-switch v-model="form.noData" />
    </c-form-item>
  </c-form>
  <c-table
    :columns="columns"
    :data="form.noData ? [] : data"
    :bordered="form.border"
    :hoverable="form.hover"
    :stripe="form.stripe"
    :loading="form.loading"
    :show-header="form.tableHeader"
    :row-selection="form.checkbox ? rowSelection : undefined" />
</template>

<script lang="ts" setup>
import { reactive } from 'vue'
const form = reactive({
  border: true,
  borderCell: false,
  hover: true,
  stripe: false,
  checkbox: true,
  loading: false,
  tableHeader: true,
  noData: false,
})

const rowSelection = reactive({
  type: 'checkbox',
  showCheckedAll: true,
})

const columns = [
  {
    title: 'Name',
    dataIndex: 'name',
  },
  {
    title: 'Salary',
    dataIndex: 'salary',
  },
  {
    title: 'Address',
    dataIndex: 'address',
  },
  {
    title: 'Email',
    dataIndex: 'email',
  },
]

const data = [
  {
    key: '1',
    name: 'Jane Doe',
    salary: 23000,
    address: '32 Park Road, London',
    email: 'jane.doe@example.com',
  },
  {
    key: '2',
    name: 'Alisa Ross',
    salary: 25000,
    address: '35 Park Road, London',
    email: 'alisa.ross@example.com',
  },
  {
    key: '3',
    name: 'Kevin Sandra',
    salary: 22000,
    address: '31 Park Road, London',
    email: 'kevin.sandra@example.com',
  },
  {
    key: '4',
    name: 'Ed Hellen',
    salary: 17000,
    address: '42 Park Road, London',
    email: 'ed.hellen@example.com',
  },
  {
    key: '5',
    name: 'William Smith',
    salary: 27000,
    address: '62 Park Road, London',
    email: 'william.smith@example.com',
  },
]
</script>
```

## API

### `<Table>` Props

| Parameter | Description | Type | Default |
| --------------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------: |
| columns | Column info of the table | `TableColumnData[]` | `[]` |
| data | Table data | `TableData[]` | `[]` |
| bordered | Whether to show border | `boolean \| TableBorder` | `true` |
| hoverable | Whether to show the hover effect | `boolean` | `true` |
| stripe | Whether to enable the stripe effect | `boolean` | `false` |
| size | The size of the table | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| table-layout | Table layout algorithm, matching CSS `table-layout`. Defaults to `fixed`; calculated column widths are not expanded by content | `'fixed' \| 'auto'` | `'fixed'` |
| loading | Loading state | `boolean\|object` | `false` |
| row-selection | Table row selector configuration | `TableRowSelection` | `-` |
| expandable | Expand row configuration of the table | `TableExpandable` | `-` |
| height | Table height; fixes the header and scrolls the body. Numbers are px | `number \| string` | `-` |
| max-height | Maximum table height; shrinks for short content and scrolls the body on overflow. Numbers are px | `number \| string` | `-` |
| fit | Remaining-space allocation; the table always fills at least its parent `width`. `true` assigns it to flexible columns without `width`; `false` expands columns proportionally to their base widths | `boolean` | `true` |
| pagination | Pagination properties configuration | `boolean \| TablePaginationConfig` | `true` |
| page-position | Pagination region inside the table, currently tl/top/tr/bl/bottom/br; not the page-size dropdown placement | `'tl' \| 'top' \| tr' \| 'bl' \| 'bottom' \| 'br'` | `'br'` |
| indent-size | The indentation distance of the tree table | `number` | `16` |
| row-key | Value field of table row `key` | `string` | `'key'` |
| show-header | Whether to show the header | `boolean` | `true` |
| virtual-list-props | Virtual-list props; providing them enables virtual scrolling. See VirtualListProps | `VirtualListProps` | `-` |
| span-method | Cell merge method (The index starts counting from the data item) | `(data: {  record: TableData;  column: TableColumnData \| TableOperationColumn;  rowIndex: number;  columnIndex: number;}) => { rowspan?: number; colspan?: number } \| void` | `-` |
| span-all | Whether to make the index of the span method contain all | `boolean` | `false` |
| load-more | Load children asynchronously; call done(children), or done() to allow retry | `(record: TableData, done: (children?: TableData[]) => void) => void` | `-` |
| filter-icon-align-left | Whether the filter icon is aligned to the left | `boolean` | `false` |
| hide-expand-button-on-empty | Whether to hide expand button when subtree is empty | `boolean` | `false` |
| row-class | Class for table-row elements | `string\| any[]\| Record<string, any>\| ((record: TableData, rowIndex: number) => any)` | `-` |
| draggable | Table drag and drop sorting configuration | `TableDraggable` | `-` |
| column-resizable | Whether columns can be resized; drag handles render only under `table-layout: fixed` | `boolean` | `false` |
| summary | Show footer summary row | `boolean\| ((params: {    columns: TableColumnData[];    data: TableData[];  }) => TableData[])` | `-` |
| summary-text | The first column of text in the summary line | `string` | `'Summary'` |
| summary-span-method | Cell Merge Method for Summarizing Rows | `(data: {  record: TableData;  column: TableColumnData \| TableOperationColumn;  rowIndex: number;  columnIndex: number;}) => { rowspan?: number; colspan?: number } \| void` | `-` |
| selected-keys | Selected row (controlled mode) takes precedence over `rowSelection` | `(string \| number)[]` | `-` |
| default-selected-keys | The selected row by default (uncontrolled mode) takes precedence over `rowSelection` | `(string \| number)[]` | `-` |
| expanded-keys | Displayed Expanded Row, Subtree (Controlled Mode) takes precedence over `expandable` | `(string \| number)[]` | `-` |
| default-expanded-keys | Expand row, Subtree displayed by default (Uncontrolled mode) takes precedence over `expandable` | `(string \| number)[]` | `-` |
| default-expand-all-rows | Whether to expand all rows by default | `boolean` | `false` |
| sticky-header | Sticky header relative to the page/outer scroller; numeric values are top offsets in px | `boolean \| number` | `false` |
| sticky-pagination | Sticky pagination relative to the page/outer scroller; numeric values are bottom offsets in px | `boolean \| number` | `false` |
| scrollbar | Whether to enable virtual scroll bar | `boolean \| ScrollbarProps` | `true` |
| show-empty-tree | Whether to display empty subtrees | `boolean` | `false` |
| extra-column | Append an extra final column, e.g. settings; slots supply its content | `boolean \| TableExtraColumnConfig` | `false` |
| empty-type | Empty-state type | <br/>`default`\|`network`\|`unknown`\|`success` <br/> <br/> | `default` |
| empty-text | Empty-state text | <br/>`string` <br/> <br/> | `-` |

### `<Table>` Events

| Event | Description | Arguments |
| ---------------- | ------------------------------ | ---------------------------------------------------------------------------------- |
| expand | Emitted when an expandable row is clicked | rowKey: `string \| number`<br>record: `TableData` |
| expanded-change | Emitted when expanded rows change | rowKeys: `(string \| number)[]` |
| select | Emitted when a row selector is clicked | rowKeys: `string \| number[]`<br>rowKey: `string \| number`<br>record: `TableData` |
| select-all | Emitted when the select-all control is clicked | checked: `boolean` |
| selection-change | Emitted when selected rows change | rowKeys: `(string \| number)[]` |
| sorter-change | Emitted when sorting changes | dataIndex: `string`<br>direction: `string` |
| filter-change | Emitted when filtering changes | dataIndex: `string`<br>filteredValues: `string[]` |
| page-change | Emitted when table page changes | page: `number` |
| page-size-change | Emitted when table page size changes | pageSize: `number` |
| change | Emitted when table data changes | data: `TableData[]`<br>extra: `TableChangeExtra`<br>currentData: `TableData[]` |
| update:columns | Emitted when column configuration changes; supports v-model:columns | columns: `TableColumnData[]` |
| cell-mouse-enter | Emitted on cell hover enter | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event` |
| cell-mouse-leave | Emitted on cell hover leave | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event` |
| cell-click | Emitted when a cell is clicked | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event` |
| row-click | Emitted when a row is clicked | record: `TableData`<br>ev: `Event` |
| header-click | Emitted when a header is clicked | column: `TableColumnData`<br>ev: `Event` |
| column-resize | Emitted when a column is resized | dataIndex: `string`<br>width: `number` |
| row-dblclick | Emitted when a row is double-clicked | record: `TableData`<br>ev: `Event` |
| cell-dblclick | Emitted when a cell is double-clicked | record: `TableData`<br>column: `TableColumnData`<br>ev: `Event` |
| row-contextmenu | Emitted when a row is right-clicked | record: `TableData`<br>ev: `Event` |
| cell-contextmenu | Emitted when a cell is right-clicked | record: `TableData`column: `TableColumnData`<br>ev: `Event` |

### `<Table>` Methods

| Method | Description | Arguments | Returns |
| ------------ | ---------------- | ------------------------------------------------------------------------ | ------ |
| selectAll | Set select-all state | checked: `boolean` | - |
| select | Set row-selection state | rowKey: `string \| number \| (string \| number)[]`<br>checked: `boolean` | - |
| expandAll | Set all rows’ expansion state | checked: `boolean` | - |
| expand | Set expansion state | rowKey: `string \| number \| (string \| number)[]`<br>checked: `boolean` | - |
| resetFilters | Reset column filters | dataIndex: `string \| string[]` | - |
| clearFilters | Clear column filters | dataIndex: `string \| string[]` | - |
| resetSorters | Reset column sorting | - | - |
| clearSorters | Clear column sorting | - | - |

### `<Table>` Slots

| Slot | Description | Arguments |
| ---------------- | :-----------------------------------: | ---------------------------------------------------------------------- |
| th | Custom th element | column: `TableColumnData` |
| thead | Custom thead element | - |
| empty | Empty content | - |
| summary-cell | Summary row | column: `TableColumnData`<br>record: `TableData`<br>rowIndex: `number` |
| pagination-right | Content to the right of pagination | - |
| pagination-left | Content to the left of pagination | - |
| td | Custom td element | column: `TableColumnData`<br>record: `TableData`<br>rowIndex: `number` |
| tr | Custom tr element | record: `TableData`<br>rowIndex: `number` |
| tbody | Custom tbody element | - |
| drag-handle-icon | Drag-anchor icon | - |
| footer | Table footer | - |
| expand-row | Expanded-row content | record: `TableData` |
| expand-icon | Expanded-row icon | expanded: `boolean`<br>record: `TableData` |
| columns | Declarative columns; when used, override columns | - |
| extra-column-header | Extra final-column header content | - |
| extra-column-cell | Extra final-column cell content | record / rowIndex, etc. |
| header-cell-actions | Header-side actions for leaf columns; entirely controlled by the caller | column / dataIndex |

### `<TableColumn>` Props

| Parameter | Description | Type | Default |
| ------------------ | ----------------------------------- | --------------------------------------------------------- | :-----: |
| data-index | Column identifier matching a TableData field | `string` | `-` |
| title | Column title | `string` | `-` |
| width | Column width | `number` | `-` |
| min-width | Minimum column width | `number` | `80` |
| align | Alignment | `TableColumnData['align']` | `-` |
| fixed | Fixed position | `TableColumnData['fixed']` | `-` |
| ellipsis | Whether to truncate with an ellipsis | `boolean` | `false` |
| sortable | Sorting options | `TableSortable` | `-` |
| filterable | Filtering options | `TableFilterable` | `-` |
| cell-class | Custom cell class | `ClassName` | `-` |
| header-cell-class | Custom header-cell class | `ClassName` | `-` |
| body-cell-class | Custom body-cell class | `ClassName \| ((record: TableData) => ClassName)` | `-` |
| summary-cell-class | Custom summary-cell class | `ClassName \| ((record: TableData) => ClassName)` | `-` |
| cell-style | Custom cell style | `CSSProperties` | `-` |
| header-cell-style | Custom header-cell style | `CSSProperties` | `-` |
| body-cell-style | Custom body-cell style | `CSSProperties \| ((record: TableData) => CSSProperties)` | `-` |
| summary-cell-style | Custom summary-cell style | `CSSProperties \| ((record: TableData) => CSSProperties)` | `-` |
| index | Manually specify the option index | `number` | `-` |
| tooltip | Whether to show a text tooltip when truncated | `boolean\|object` | `false` |

### `<TableColumn>` Slots

| Slot | Description | Arguments |
| -------------- | :------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| filter-icon | Filter-button icon | - |
| filter-content | Custom filter-popup content | filterValue: `string[]`<br>setFilterValue: `(filterValue: string[]) => void`<br>handleFilterConfirm: `(event: Event) => void`<br>handleFilterReset: `(event: Event) => void` |
| title | Title | - |
| cell | Cell | record: `TableData`<br>column: `TableColumnData`<br>rowIndex: `number` |

### TableData

| Parameter | Description | Type | Default |
| -------- | ---------------- | -------------------------- | :-----: |
| key | Row key | `string` | `-` |
| expand | Expanded-row content | `string \| RenderFunction` | `-` |
| children | Child data | `TableData[]` | `-` |
| disabled | Whether row selection is disabled | `boolean` | `false` |
| isLeaf | Whether this is a leaf node | `boolean` | `false` |

### TableSortable

| Parameter | Description | Type | Default |
| ---------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | :----: |
| sortDirections | Supported sort directions | `('ascend' \| 'descend')[]` | `-` |
| sorter | Sort comparator; `true` disables internal sorting | `((        a: TableData,        b: TableData,        extra: { dataIndex: string; direction: 'ascend' \| 'descend' }      ) => number)    \| boolean` | `-` |
| sortOrder | Sort direction | `'ascend' \| 'descend' \| ''` | `-` |
| defaultSortOrder | Default sort direction in uncontrolled mode | `'ascend' \| 'descend' \| ''` | `-` |

### TableFilterData

| Parameter | Description | Type | Default |
| ------ | ------------------ | -------------------------- | :----: |
| text | Filter-option content | `string \| RenderFunction` | `-` |
| value | Filter-option value | `string` | `-` |

### TableFilterable

| Parameter | Description | Type | Default |
| -------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: |
| filters | Filter data | `TableFilterData[]` | `-` |
| filter | Filter callback, similar to Array.prototype.filter | `(filteredValue: string[], <br/>record:TableData)=> boolean` | `-` |
| multiple | Whether to support multiple selection | `boolean` | `false` |
| filteredValue | Selected filters | `string[]` | `-` |
| defaultFilteredValue | Default selected filters | `string[]` | `-` |
| renderContent | Filter-popup content | `(data: {    filterValue: string[];    setFilterValue: (filterValue: string[]) => void;    handleFilterConfirm: (event: Event) => void;    handleFilterReset: (event: Event) => void;  }) => VNodeChild` | `-` |
| icon | Filter-button icon | `RenderFunction` | `-` |
| triggerProps | Filter-popup configuration | `TriggerProps` | `-` |
| alignLeft | Whether the filter icon is aligned to the left | `boolean` | `false` |

### TableColumnData

| Parameter | Description | Type | Default |
| ---------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | :-----: |
| dataIndex | Column identifier matching data in `TableData` | `string` | `-` |
| title | Column title | `string \| RenderFunction` | `-` |
| width | Base column width. Fixed when flexible columns exist and fit=true; if all columns are fixed and narrower than the container, expanded proportionally | `number` | `-` |
| minWidth | Minimum `width`. Columns without `width` share remaining space proportionally. Default 80 | `number` | `80` |
| align | Alignment | `'left' \| 'center' \| 'right'` | `-` |
| fixed | Fixed position | `'left' \| 'right'` | `-` |
| ellipsis | Whether to show an ellipsis | `boolean` | `false` |
| tooltip | Whether truncation shows a tooltip; accepts Tooltip props | `boolean \| Record<string, any>` | `-` |
| sortable | Sorting options | `TableSortable` | `-` |
| filterable | Filtering options | `TableFilterable` | `-` |
| children | Child header data for grouped headers | `TableColumnData[]` | `-` |
| cellClass | Custom cell class | `ClassName` | `-` |
| headerCellClass | Custom header-cell class | `ClassName` | `-` |
| bodyCellClass | Custom body-cell class | `ClassName \| ((record: TableData) => ClassName)` | `-` |
| summaryCellClass | Custom summary-cell class | `ClassName \| ((record: TableData) => ClassName)` | `-` |
| cellStyle | Custom cell style | `CSSProperties` | `-` |
| headerCellStyle | Custom header-cell style | `CSSProperties` | `-` |
| bodyCellStyle | Custom body-cell style | `CSSProperties \| ((record: TableData) => CSSProperties)` | `-` |
| summaryCellStyle | Custom summary-cell style | `CSSProperties \| ((record: TableData) => CSSProperties)` | `-` |
| render | Custom column-cell renderer | `(data: {    record: TableData;    column: TableColumnData;    rowIndex: number;  }) => VNodeChild` | `-` |
| slotName | Named render slot for this column; same arguments as #cell | `string` | `-` |
| titleSlotName | Named title-rendering slot for this column | `string` | `-` |

### TableBorder

| Parameter | Description | Type | Default |
| ---------- | ------------------------------- | --------- | :-----: |
| wrapper | Whether to show the outer border | `boolean` | `false` |
| cell | Whether to show header/body cell borders | `boolean` | `false` |
| headerCell | Whether to show header-cell borders | `boolean` | `false` |
| bodyCell | Whether to show body-cell borders | `boolean` | `false` |

### TableRowSelection

| Parameter | Description | Type | Default |
| ---------------------- | ---------------------------------------------- | ----------------------- | :-----: |
| type | Row-selection type | `'checkbox' \| 'radio'` | `-` |
| selectedRowKeys | Selected rows in controlled mode | `BaseType[]` | `-` |
| defaultSelectedRowKeys | Default selected rows in uncontrolled mode | `BaseType[]` | `-` |
| showCheckedAll | Whether to show select all | `boolean` | `false` |
| title | Column title | `string` | `-` |
| width | Column width | `number` | `-` |
| fixed | Whether fixed | `boolean` | `false` |
| checkStrictly | Allow parent selection; unlink parent/child checks | `boolean` | `true` |
| onlyCurrent | Keep only current-page keys; clear them when changing pages | `boolean` | `false` |

### TableExpandable

| Parameter | Description | Type | Default |
| ---------------------- | ------------------------------ | ------------------------------------------------------ | :-----: |
| expandedRowKeys | Expanded rows in controlled mode | `BaseType[]` | `-` |
| defaultExpandedRowKeys | Default expanded rows in uncontrolled mode | `BaseType[]` | `-` |
| defaultExpandAllRows | Whether to expand all rows by default | `boolean` | `false` |
| expandedRowRender | Custom expanded-row content | `(record: TableData) => VNodeChild` | `-` |
| icon | Expand icon | `(expanded: boolean, record: TableData) => VNodeChild` | `-` |
| title | Column title | `string` | `-` |
| width | Column width | `number` | `-` |
| fixed | Whether fixed | `boolean` | `false` |

### TableDraggable

| Parameter | Description | Type | Default |
| ------ | -------- | ------------------- | :-----: |
| type | Drag type | `'row' \| 'handle'` | `-` |
| title | Column title | `string` | `-` |
| width | Column width | `number` | `-` |
| fixed | Whether fixed | `boolean` | `false` |

### TableChangeExtra

| Parameter | Description | Type | Default |
| ---------- | ---------- | ------------------------------------------------ | :----: |
| type | Trigger type | `'pagination' \| 'sorter' \| 'filter' \| 'drag'` | `-` |
| page | Page number | `number` | `-` |
| pageSize | Items per page | `number` | `-` |
| sorter | Sorting information | `Sorter` | `-` |
| filters | Filtering information | `Filters` | `-` |
| dragTarget | Drag information | `TableData` | `-` |

### VirtualListProps

| Parameter | Description | Type | Default |
| :----------------- | ------------------------------------------------------------------ | ------------------ | :-----: |
| height | Viewport height | `number \| string` | `-` |
| threshold | Item-count threshold for virtual scrolling; counts below it do not enable virtualization | `number` | `-` |
| isStaticItemHeight | Removed: use `fixedSize` instead of the old fixed-height flag | `boolean` | `false` |
| fixedSize | Whether item heights are fixed | `boolean` | `false` |
| estimatedSize | Estimated item height when heights vary | `number` | `-` |
| buffer | Number of items premounted beyond viewport boundaries | `number` | `10` |

### TableExtraColumnConfig

| Parameter | Description | Type | Default |
| :----- | ---- | ---- | :----: |
| width | Column width; follows table size when omitted | `number` | xs 28 / sm 32 / md·lg·xl 36 |
| fixed | Fixed position | `'left' \| 'right'` | `'right'` |
| align | Alignment | `'left' \| 'center' \| 'right'` | `'center'` |
| dataIndex | Column identifier | `string` | `__cedar_table_extra__` |

### Pagination configuration type

`TablePaginationConfig = Omit<PaginationProps, 'total'> & { total?: number }`. When `pagination.total` is omitted, Table derives it from the effective data count. Remote pagination can still provide `total` explicitly. Existing `PaginationProps` objects remain accepted by Table; standalone `Pagination` still requires `total`. `TablePaginationConfig` is exported from root/table entries.


### Existing precedence of forwarded configuration (F07)

Column filterable.triggerProps is spread after internal Trigger settings, so nested fields such as open can currently override filter-popup state. F07 preserves this order/type for compatibility without automatically forbidding existing capabilities. Future restrictions require separate migration assessment of filter/popup states.


## Optional business-row type configuration (F08-A)

```ts
import { defineTableConfig } from '@cedar-design/ui'
import type { TypedTableConfig, TypedTableColumn, TableDataPath } from '@cedar-design/ui/table'

interface User { id: string; name: string; age: number }
const users: User[] = [{ id: 'a', name: 'Alice', age: 20 }]
const config = defineTableConfig<User>({
  rowKey: 'id', data: users,
  columns: [{ dataIndex: 'age', render: ({ record }) => record.age.toFixed(0) }],
})
```

Use the config with `<c-table v-bind="config" />` or TSX `<Table {...config} />`. Business-side as any is unnecessary. Existing TableData, TableColumnData, TableProps and component props remain. The new entry validates inputs and returns existing TableProps for old components. Runtime returns the same object without copying rows/columns, changing sorting/filtering or wrapping components.

| Associated scope | New type rules |
| --- | --- |
| data / columns | The same Row type recursively applies to tree children |
| dataIndex | Validates fields/nested paths such as profile.city, tags[0].label and tags.0.label, up to five business-structure levels. Dynamic strings/deeper paths retain the old entry |
| render / sortable / filterable | record, comparators and filters receive Row, including grouped child columns |
| Row callbacks | Cell styles/classes, rowClass, expandable, loadMore, spanMethod and custom summaries associate with Row |
| rowKey | Explicitly provide a Row field whose value is string/number; this is a field name, not a nested path |
| summary | May be omitted, false or a custom function returning complete Row. Automatic summary=true is not guaranteed to be a business row, so the new entry rejects it; existing Table configuration still supports it |

Business interfaces normally need not extend TableData explicitly; its any index broadens keyof and weakens spelling checks. Use ordinary business interfaces and generic constraints to validate reserved Table metadata compatibility. Business code still validates backend contents; types do not ensure unique IDs.

Type association covers only this configuration. Component template slots/events and custom components extensions do not automatically become Row-generic. Returned TableProps remains the old broad type; arbitrary later mutations are not Row-validated. If reactive sources replace arrays, use `computed(() => defineTableConfig<Row>(...))`; passing rows.value once is not an ongoing ref subscription.

Automatic summary rows may contain text, totals and missing fields; render(record: User) must not assume a complete User. Keep the old broad configuration for automatic summaries or heterogeneous tree rows. The new custom-summary entry requires a complete business row. Neither entry changes Table runtime behavior.

Platform scope: Maple Table is a native-table display container without data/columns API, so no associated-config entry is added there. Select/Cascader type associations require separate assessment.


## Reading direction and interaction

Table inherits native reading direction. Normal columns follow reading order; explicit fixed left/right sides stay physical through stable visual partitions. Mixed frozen group headers are projected into matching physical sections without mutating source columns or business indexes. Default cell alignment follows reading start; explicit left/right alignment stays physical. Header/body/summary/sticky rail share a normalized nonnegative inline scroll distance, including native negative RTL scrollLeft. Virtual row positioning preserves horizontal distance. Teleported footers retain source direction. Resize handles support directional pointer and keyboard input; sticky rails support arrows and Home/End. Direction switches preserve business state and cancel stale resize gestures.

Lazy children belong to the source node identity and row key, rather than to a reused key alone. Replacing the node, row key or loader invalidates old work/cache. Deactivation or unmount invalidates pending cell callbacks. `done()` releases pending for retry; `done([])` accepts an empty result. Only the first completion is accepted. Synchronous loader exceptions release pending and remain observable through Vue. Keep the callback-based `load-more` protocol; returned notification Promises do not control this work.

If a callback-style loader returns a Promise, its rejection releases pending and reaches the Vue error path; a fulfilled return value is ignored and does not replace `done`. This is error reporting for an explicit loader Prop, not Promise collection from `expand` or other notification events.

---

Document: llms/en-US/components/tabs.md

<!-- Source: src/tabs/README.en-US.md; locale: en-US; page: /en/components/tabs/ -->

# Tabs

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `default-value="overview"`, `name="overview"`, `title="概览"`, `name="details"`.

Example source: src/tabs/__demos__/basic.vue

```vue
<template>
  <c-tabs default-value="overview">
    <c-tab-pane name="overview" title="概览">概览内容</c-tab-pane>
    <c-tab-pane name="details" title="详情">详情内容</c-tab-pane>
    <c-tab-pane name="settings" title="设置">设置内容</c-tab-pane>
  </c-tabs>
</template>
```

## Appearance and states

### Appearance Lab

Preview configuration: `layout="vertical"`, `:clearable="false"`, `options`, `aria-label="variant"`.

Example source: src/tabs/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({ variant: "line", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["line","card","outline","plain","capsule","enclosed"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-select
          v-model="__demoAppearance['variant']"
          :clearable="false"
          :options="[
            { label: 'line', value: 'line' },
            { label: 'card', value: 'card' },
            { label: 'outline', value: 'outline' },
            { label: 'plain', value: 'plain' },
            { label: 'capsule', value: 'capsule' },
            { label: 'enclosed', value: 'enclosed' },
          ]"
          aria-label="variant"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-tabs default-value="overview" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">
      <c-tab-pane name="overview" title="概览">概览内容</c-tab-pane>
      <c-tab-pane name="details" title="详情">详情内容</c-tab-pane>
      <c-tab-pane name="settings" title="设置">设置内容</c-tab-pane>
    </c-tabs>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Appearance and direction

### Type

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `orientation` | Horizontal/vertical axis of tab navigation, default horizontal; affects navigation layout and arrow-key behavior | Type, Position |
| `item-style` | `StyleValue` | No Padding, Custom Style |
| `default-value` | `string / number` | No Padding, Custom Style |
| `variant` | `line / card / outline / plain / capsule / enclosed` | Type |
| `size` | `xs / sm / md / lg / xl` | Type |
| `editable` | `boolean` | Type |
<!-- demo-config-notes:end -->


- `variant`: Selects the visual variant.
- `size`: Controls the component size.

Example source: src/tabs/__demos__/type.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-radio-group v-model="isVertical" type="button">
      <c-radio value="horizontal">Horizontal</c-radio>
      <c-radio value="vertical">Vertical</c-radio>
    </c-radio-group>
    <c-radio-group v-model="variant" type="button">
      <c-radio value="line">Line</c-radio>
      <c-radio value="card">Card</c-radio>
      <c-radio value="outline">Outline</c-radio>
      <c-radio value="plain">Plain</c-radio>
      <c-radio value="capsule">Capsule</c-radio>
      <c-radio value="enclosed">Enclosed</c-radio>
    </c-radio-group>
    <c-radio-group v-model="size" type="button">
      <c-radio value="xs">Xs</c-radio>
      <c-radio value="sm">Sm</c-radio>
      <c-radio value="md">Md</c-radio>
      <c-radio value="lg">Lg</c-radio>
      <c-radio value="xl">Xl</c-radio>
    </c-radio-group>
  </c-space>
  <c-tabs
    :variant="variant"
    :size="size"
    :orientation="isVertical"
    :editable="true"
    @add="handleAdd"
    @delete="handleDelete"
    show-add-button
    auto-switch
    :style="isVertical !== 'vertical' ? { height: '240px' } : undefined"
  >
    <c-tabs-navs>
      <c-tab-nav v-for="(item, index) of data" :key="item.key" :name="item.key" :title="item.title" :closable="index !== 2" />
      <template #prefix><c-button size="xs">Action</c-button></template>
      <template #suffix>suffix</template>
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item v-for="(item, index) of data" :key="item.key" :name="item.key">{{ item?.content }}</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const variant = ref('line')
const size = ref('md')
const isVertical = ref('horizontal')
const data = ref([
  {
    key: '1',
    title: 'Tab 1',
    content: 'Content of Tab Panel 1',
  },
  {
    key: '2',
    title: 'Tab 2',
    content: 'Content of Tab Panel 2',
  },
  {
    key: '3',
    title: 'Tab 3',
    content: 'Content of Tab Panel 3',
  },
  {
    key: '4',
    title: 'Tab 4',
    content: 'Content of Tab Panel 4',
  },
])
let count = 5
const handleAdd = () => {
  const number = count++
  data.value = data.value.concat({
    key: `${number}`,
    title: `New Tab ${number}`,
    content: `Content of New Tab Panel ${number}`,
  })
}
const handleDelete = (key) => {
  data.value = data.value.filter((item) => item.key !== key)
}
</script>
```

### Position

Preview configuration: `type="button"`, `value="normal"`, `value="reverse"`, `value="horizontal"`.

Example source: src/tabs/__demos__/position.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-radio-group v-model="indicatorPosition" type="button">
      <c-radio value="normal">Normal (bottom/right)</c-radio>
      <c-radio value="reverse">Reverse (top/left)</c-radio>
    </c-radio-group>
    <c-radio-group v-model="vertical" type="button">
      <c-radio value="horizontal">Horizontal</c-radio>
      <c-radio value="vertical">Vertical</c-radio>
    </c-radio-group>
    <c-radio-group v-model="componentOrder" type="button">
      <c-radio value="nav-first">TabsNavs → TabsItems</c-radio>
      <c-radio value="items-first">TabsItems → TabsNavs</c-radio>
    </c-radio-group>
    <c-tabs :indicator-position="indicatorPosition" :orientation="vertical">
      <template v-if="componentOrder === 'items-first'">
        <c-tabs-items>
          <c-tab-item name="1">Content of Tab Panel 1</c-tab-item>
          <c-tab-item name="2">Content of Tab Panel 2</c-tab-item>
          <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
        </c-tabs-items>
        <c-tabs-navs>
          <c-tab-nav name="1" title="Tab 1" />
          <c-tab-nav name="2" title="Tab 2" />
          <c-tab-nav name="3" title="Tab 3" />
        </c-tabs-navs>
      </template>
      <template v-else>
        <c-tabs-navs>
          <c-tab-nav name="1" title="Tab 1" />
          <c-tab-nav name="2" title="Tab 2" />
          <c-tab-nav name="3" title="Tab 3" />
        </c-tabs-navs>
        <c-tabs-items>
          <c-tab-item name="1">Content of Tab Panel 1</c-tab-item>
          <c-tab-item name="2">Content of Tab Panel 2</c-tab-item>
          <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
        </c-tabs-items>
      </template>
    </c-tabs>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const indicatorPosition = ref('normal')
const vertical = ref('horizontal')
const componentOrder = ref('nav-first')
</script>
```

### Icon Tabs

Preview configuration: `name="1"`, `name="2"`, `name="3"`, `item-vertical`.

Example source: src/tabs/__demos__/icon-tabs.vue

```vue
<template>
  <c-space direction="column" size="lg">
    <c-tabs>
      <c-tabs-navs>
        <c-tab-nav name="1">
          <template #icon> <c-icon-calendar /> </template>
          <template #title>Tab 1</template>
        </c-tab-nav>
        <c-tab-nav name="2">
          <template #icon> <c-icon-clock-circle /> </template>
          <template #title>Tab 2</template>
        </c-tab-nav>
        <c-tab-nav name="3">
          <template #icon> <c-icon-user /> </template>
          <template #title>Tab 3</template>
        </c-tab-nav>
      </c-tabs-navs>
      <c-tabs-items>
        <c-tab-item name="1"> Content of Tab Panel 1</c-tab-item>
        <c-tab-item name="2"> Content of Tab Panel 2</c-tab-item>
        <c-tab-item name="3"> Content of Tab Panel 3</c-tab-item>
      </c-tabs-items>
    </c-tabs>

    <c-tabs>
      <c-tabs-navs>
        <c-tab-nav name="1" item-vertical>
          <template #icon> <c-icon-calendar /> </template>
          <template #title>日历</template>
        </c-tab-nav>
        <c-tab-nav name="2" item-vertical>
          <template #icon> <c-icon-clock-circle /> </template>
          <template #title>时钟</template>
        </c-tab-nav>
        <c-tab-nav name="3" item-vertical>
          <template #icon> <c-icon-user /> </template>
          <template #title>用户</template>
        </c-tab-nav>
      </c-tabs-navs>
      <c-tabs-items>
        <c-tab-item name="1"> Content of Tab Panel 1</c-tab-item>
        <c-tab-item name="2"> Content of Tab Panel 2</c-tab-item>
        <c-tab-item name="3"> Content of Tab Panel 3</c-tab-item>
      </c-tabs-items>
    </c-tabs>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

### No Padding

Preview configuration: `:item-style="{ padding: 0 }"`, `default-value="2"`, `name="1"`, `title="Tab 1"`.

Example source: src/tabs/__demos__/no-padding.vue

```vue
<template>
  <c-tabs :item-style="{ padding: 0 }" default-value="2">
    <c-tabs-navs :style="{ paddingInline: 0 }">
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3">
        <template #title>Tab 3</template>
      </c-tab-nav>
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1">
        <div class="p-24">通过 item-style 设置内容间距，并通过 TabsNavs 的 style 去掉导航两端内边距</div>
      </c-tab-item>
      <c-tab-item name="2"> Content of Tab Panel 2</c-tab-item>
      <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
</script>
```

### Custom Style

Preview configuration: `default-value="overview"`, `item-class="custom-tab-content"`, `:item-style="{ padding: '16px' }"`, `item-wrapper-class="custom-tab-panel"`.

Example source: src/tabs/__demos__/custom-style.vue

```vue
<template>
  <c-tabs
    default-value="overview"
    item-class="custom-tab-content"
    :item-style="{ padding: '16px' }"
    item-wrapper-class="custom-tab-panel"
    :item-wrapper-style="{ border: '1px solid currentColor', borderRadius: '8px' }"
    tab-class="custom-tab-label"
    :tab-style="{ borderRadius: '8px' }"
  >
    <c-tabs-navs :style="{ paddingInline: 0 }">
      <c-tab-nav name="overview" title="概览" />
      <c-tab-nav name="details" title="详情" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="overview">统一设置导航、内容和内容外层样式。</c-tab-item>
      <c-tab-item name="details">自定义类名保留内置选中状态，样式支持响应式更新。</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>
```

## Navigation and content composition

### Nav Content

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | `string / number` | Nav Content |
| `swipeable` | `boolean` | Same Source |
| `lazy-load` | `boolean` | Same Source |
<!-- demo-config-notes:end -->


Preview configuration: `default-value="overview"`, `aria-label="内容分类"`, `name="overview"`, `title="概览"`.

Example source: src/tabs/__demos__/nav-content.vue

```vue
<template>
  <c-tabs default-value="overview">
    <c-tabs-navs aria-label="内容分类">
      <c-tab-nav name="overview" title="概览" />
      <c-tab-nav name="details" title="详情" />
      <c-tab-nav name="settings" title="设置" />
    </c-tabs-navs>
  </c-tabs>
</template>
```

### Same Source

Preview configuration: `swipeable`, `lazy-load`, `aria-label="内容分类"`, `:name="item.key"`.

Example source: src/tabs/__demos__/same-source.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const active = ref('overview')
const items = [{ key: 'overview', title: '概览' }, { key: 'details', title: '详情' }, { key: 'disabled', title: '不可用', disabled: true }]
</script>
<template>
  <c-tabs v-model="active" swipeable lazy-load>
    <c-tabs-navs aria-label="内容分类">
      <c-tab-nav v-for="item in items" :key="item.key" :name="item.key" :title="item.title" :disabled="item.disabled" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item v-for="item in items" :key="item.key" :name="item.key">{{ item.title }}内容</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>
```

### Suffix

Preview configuration: `name="1"`, `title="Tab 1"`, `name="2"`, `title="Tab 2"`.

Example source: src/tabs/__demos__/suffix.vue

```vue
<template>
  <c-tabs>
    <c-tabs-navs>
      <template #suffix>
        <c-button>Action</c-button>
      </template>
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3" title="Tab 3" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1"> Content of Tab Panel 1 </c-tab-item>
      <c-tab-item name="2"> Content of Tab Panel 2 </c-tab-item>
      <c-tab-item name="3"> Content of Tab Panel 3 </c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
</script>
```

## Interaction and dynamic tabs

### Trigger

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `default-value` | `string / number` | Trigger, Lazy Load |
| `trigger` | `click / hover` | Trigger |
| `lazy-load` | `boolean` | Lazy Load |
| `variant` | `line / card / outline / plain / capsule / enclosed` | Editable |
| `editable` | `boolean` | Editable |
| `show-add-button` | `boolean` | Editable |
<!-- demo-config-notes:end -->


Preview configuration: `value="click"`, `value="hover"`, `default-value="1"`, `:trigger="trigger"`.

Example source: src/tabs/__demos__/trigger.vue

```vue
<template>
  <c-radio-group v-model="trigger">
    <c-radio value="click">click</c-radio>
    <c-radio value="hover">hover</c-radio>
  </c-radio-group>
  <c-tabs default-value="1" :trigger="trigger">
    <c-tabs-navs>
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3">
        <template #title>Tab 3</template>
      </c-tab-nav>
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1">Content of Tab Panel 1</c-tab-item>
      <c-tab-item name="2">Content of Tab Panel 2</c-tab-item>
      <c-tab-item name="3">Content of Tab Panel 3</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const trigger = ref('click')
</script>
```

### Lazy Load

Preview configuration: `default-value="2"`, `lazy-load`, `name="1"`, `title="Tab 1"`.

Example source: src/tabs/__demos__/lazy-load.vue

```vue
<template>
  <c-tabs default-value="2" lazy-load>
    <c-tabs-navs>
      <c-tab-nav name="1" title="Tab 1" />
      <c-tab-nav name="2" title="Tab 2" />
      <c-tab-nav name="3" title="Tab 3" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item name="1"> Content of Tab Panel 1 </c-tab-item>
      <c-tab-item name="2"> Content of Tab Panel 2 </c-tab-item>
      <c-tab-item name="3"> Content of Tab Panel 3 </c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
</script>
```

### Editable

- `variant`: Selects the visual variant.

Example source: src/tabs/__demos__/editable.vue

```vue
<template>
  <c-tabs variant="card" :editable="true" @add="handleAdd" @delete="handleDelete" show-add-button auto-switch>
    <c-tabs-navs>
      <template #suffix>
        <c-button>Action</c-button>
      </template>
      <c-tab-nav v-for="(item, index) of data" :key="item.key" :name="item.key" :title="item.title" :closable="index !== 2" />
    </c-tabs-navs>
    <c-tabs-items>
      <c-tab-item v-for="(item, index) of data" :key="item.key" :name="item.key">{{ item?.content }}</c-tab-item>
    </c-tabs-items>
  </c-tabs>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
let count = 5

const data = ref([
  {
    key: '1',
    title: 'Tab 1',
    content: 'Content of Tab Panel 1',
  },
  {
    key: '2',
    title: 'Tab 2',
    content: 'Content of Tab Panel 2',
  },
  {
    key: '3',
    title: 'Tab 3',
    content: 'Content of Tab Panel 3',
  },
  {
    key: '4',
    title: 'Tab 4',
    content: 'Content of Tab Panel 4',
  },
])

const handleAdd = () => {
  const number = count++
  data.value = data.value.concat({
    key: `${number}`,
    title: `New Tab ${number}`,
    content: `Content of New Tab Panel ${number}`,
  })
}
const handleDelete = (key: string | number) => {
  data.value = data.value.filter((item) => item.key !== key)
}
</script>
```

## API

TabPane, TabNav and TabItem all require unique names. Selection and navigation/panel association use `name`; Vue key controls only node reuse. Provide `:key` separately in loops.

Use ordinary `v-model`. `modelValue` is the selected tab name. `defaultValue` initializes uncontrolled state once without later resets or initialization `update:modelValue`. When provided, the parent value controls selection.

### Tabs Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| model-value | `string / number` | `undefined` | Current selected name; controlled when provided |
| default-value | `string / number` | `undefined` | Initial uncontrolled value; defaults to the first available item |
| variant | `line / card / outline / plain / capsule / enclosed` | `line` | Visual variant |
| size | `xs / sm / md / lg / xl` | Global value or md | Size |
| orientation | Horizontal/vertical axis of tab navigation, default horizontal; affects navigation layout and arrow-key behavior | `horizontal` | Navigation orientation |
| indicator-position | Indicator on the navigation side facing the content (normal) or the opposite side (reverse), default normal; does not use four-side values | `normal` | Indicator on the content side or opposite side |
| editable | `boolean` | `false` | Allow closing tabs |
| show-add-button | `boolean` | `false` | Show the add button in editable mode |
| auto-switch | `boolean` | `false` | Switch to the last available tab after adding |
| lazy-load | `boolean` | `false` | Mount on first activation |
| destroy-on-hide | `boolean` | `false` | Unmount content when hidden |
| justify | `boolean` | `false` | Fill container height in horizontal orientation |
| animation | `boolean` | `false` | Content fade-in animation |
| item-class | `string / object / array` | `undefined` | Inner class for each panel; merged with built-in classes |
| item-style | `StyleValue` | `undefined` | Inner style for each panel; supports string, object or array |
| item-wrapper-class | `string / object / array` | `undefined` | Outer class for each panel; merged with built-in classes |
| item-wrapper-style | `StyleValue` | `undefined` | Outer style for each panel; supports string, object or array |
| tab-class | `string / object / array` | `undefined` | Outer navigation-label class, including title/close button; merged with built-in classes |
| tab-style | `StyleValue` | `undefined` | Outer navigation-label style; supports string, object or array |
| hide-content | `boolean` | `false` | Hide the content area |
| trigger | `click / hover` | `click` | Mouse trigger mode; touch always uses click |
| scroll-position | Target position or numeric offset of the selected tab within the navigation scroll viewport, default auto; not popup placement | `auto` | Selected-tab scroll position; numbers are start offsets |
| scroll-buttons | `boolean / auto` | `auto` | Show arrows on overflow; auto hides them on touch devices |
| activation-mode | `automatic / manual` | `automatic` | Whether arrow keys immediately select |
| swipeable | `boolean` | `false` | Horizontal swipe between content panels; no looping |

### Tabs Events

| Event | Arguments | Description |
| --- | --- | --- |
| update:model-value | name: string / number | Request a selected-value update |
| change | name: string / number | Notify on selecting a different available item; controlled mode still requires parent modelValue updates |
| tab-click | name, event: Event | Click an available item, including repeat clicks; hover/arrows/swipes do not emit click |
| add | event: Event | Request adding a tab; the caller updates data |
| delete | name, event: Event | Request removing a tab; the caller updates data |

### TabPane Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name **(required)** | string / number | — | Unique business identifier matching modelValue |
| title | string | undefined | Navigation title |
| disabled | boolean | false | Prevent selecting and closing |
| closable | boolean | true | Show the close button in editable mode |
| item-vertical | boolean | false | Vertical icon/text layout |
| lazy-load | boolean | undefined | Inherit Tabs; explicit false overrides it |
| destroy-on-hide | boolean | undefined | Inherit Tabs; explicit false overrides it |

### TabNav Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name **(required)** | string / number | — | Unique business identifier matching modelValue |
| title | string | undefined | Title |
| disabled | boolean | false | Prevent selecting and closing |
| closable | boolean | true | Show the close button in editable mode |
| item-vertical | boolean | false | Vertical icon/text layout |

TabNav/TabItem associate through the same `name`. Names are unique within a group; number `1` and string `'1'` differ. Vue `key` controls node reuse only; provide `:key` in loops independently. It does not determine selection.

### TabItem Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| name **(required)** | string / number | — | Unique business identifier matching modelValue |
| lazy-load | boolean | undefined | Inherit Tabs; explicit false overrides it |
| destroy-on-hide | boolean | undefined | Inherit Tabs; explicit false overrides it |

Inactive panels always have hidden. The above props determine whether internal state survives. destroy-on-hide overrides lazy-load; active content remains mounted. TabsNavs/TabsItems have no business props.

### Slots

| Component | Slot | Description |
| --- | --- | --- |
| Tabs | default | TabPane list, or TabsNavs/TabsItems for advanced composition |
| TabPane | default / title | Panel content / custom navigation title |
| TabsNavs | default | TabNav list |
| TabsNavs | prefix / suffix / add-icon | Navigation prefix/suffix areas and add icon |
| TabNav | title / default / icon | title/default slots customize the title; icon supplies an icon |
| TabsItems | default | TabItem list |
| TabItem | default | Panel content |

### Expose

`TabsNavs.resize(): void` remeasures overflow and scrolls the selected tab into view. ResizeObserver watches size changes automatically.

### Keyboard and direction

Arrow keys skip disabled items and wrap; Home/End reach first/last. Delete requests closing editable tabs. Horizontal uses Left/Right, vertical uses Up/Down. Manual mode moves focus only; Enter/Space activates the native button. `dir="rtl"` supports right-to-left layout. Give TabsNavs an `aria-label` to name navigation.

### Types

Exports TabsName, TabsVariant, TabsTrigger, TabsIndicatorPosition, TabsScrollPosition, TabsActivationMode and Props/Instance/runtime props/`_XxxComponent` for all six components. Both platforms use the same prop definitions.

## Style variables

Matching token suffixes have matching meanings on both platforms, with platform-specific defaults. The variables and their defaults are listed below.

| Variable | Default |
| --- | --- |
| `--c-tabs-background` | `var(--c-sys-color-surface-default)` |
| `--c-tabs-title-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tabs-title-text-color-active` | `var(--c-sys-color-content-brand)` |
| `--c-tabs-title-text-color-disabled` | `var(--c-sys-color-content-disabled)` |
| `--c-tabs-muted-background` | `var(--c-sys-color-surface-muted)` |
| `--c-tabs-border-color` | `var(--c-sys-color-border-default)` |
| `--c-tabs-hover-background` | `var(--c-sys-color-state-hover)` |
| `--c-tabs-nav-gap` | `var(--c-sys-space-2)` |
| `--c-tabs-tab-gap` | `var(--c-sys-space-2)` |
| `--c-tabs-header-padding` | `var(--c-sys-space-5)` |
| `--c-tabs-control-height` | `var(--c-sys-control-height-xs)` |
| `--c-tabs-touch-target` | `var(--c-sys-control-touch-target)` |
| `--c-tabs-border-width` | `1px` |
| `--c-tabs-focus-width` | `2px` |
| `--c-tabs-focus-offset` | `-3px` |
| `--c-tabs-radius` | `var(--c-sys-radius-md)` |
| `--c-tabs-icon-gap` | `var(--c-sys-space-3)` |
| `--c-tabs-content-padding` | `var(--c-sys-space-6)` |
| `--c-tabs-indicator-size` | `2px` |
| `--c-tabs-indicator-radius` | `1px` |
| `--c-tabs-animation-duration` | `var(--c-sys-motion-duration-standard)` |
| `--c-tabs-active-font-weight` | `var(--c-sys-font-weight-semibold)` |
| `--c-tabs-group-padding` | `var(--c-sys-space-2)` |
| `--c-tabs-capsule-radius` | `var(--c-sys-radius-pill)` |
| `--c-tabs-active-shadow` | `0 1px 3px rgba(0, 0, 0, 0.12)` |
| `--c-tabs-size-xs-tab-height` | `var(--c-sys-control-height-xs)` |
| `--c-tabs-size-xs-tab-padding` | `var(--c-sys-space-2) var(--c-sys-space-4)` |
| `--c-tabs-size-xs-tab-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tabs-size-sm-tab-height` | `var(--c-sys-control-height-sm)` |
| `--c-tabs-size-sm-tab-padding` | `var(--c-sys-space-3) var(--c-sys-space-5)` |
| `--c-tabs-size-sm-tab-font-size` | `var(--c-sys-font-size-sm)` |
| `--c-tabs-size-md-tab-height` | `var(--c-sys-control-height-md)` |
| `--c-tabs-size-md-tab-padding` | `var(--c-sys-space-4) var(--c-sys-space-6)` |
| `--c-tabs-size-md-tab-font-size` | `var(--c-sys-font-size-md)` |
| `--c-tabs-size-lg-tab-height` | `var(--c-sys-control-height-lg)` |
| `--c-tabs-size-lg-tab-padding` | `10px var(--c-sys-space-7)` |
| `--c-tabs-size-lg-tab-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-tabs-size-xl-tab-height` | `var(--c-sys-control-height-xl)` |
| `--c-tabs-size-xl-tab-padding` | `var(--c-sys-space-5) var(--c-sys-space-8)` |
| `--c-tabs-size-xl-tab-font-size` | `var(--c-sys-font-size-xl)` |

Both platforms keep the same API, state, lifecycle and keyboard behavior. Desktop and mobile differences use style tokens and pointer media queries; the packages remain independent at runtime.

## Independent source copies and public types

Both platforms independently maintain Tabs, TabPane, TabsNavs, TabNav, TabsItems and TabItem without cross-library runtimes or generic platform configuration. All xs/sm/md/lg/xl sizes are implemented. Cedar inherits ConfigProvider size/rtl. Maple defaults to md and supports setPropsDefaults, explicit size and DOM dir. Panels use native hidden; InfiniteScroll observes visibility directly rather than old panel registration.

Public types include TabsEmits, TabsSlots, TabPaneSlots, TabsNavsSlots, TabNavSlots, TabsItemsSlots, TabItemSlots and TabsNavsExpose. Only TabsNavs has its own method, resize(). Other members have no own imperative methods/notification events; selection/editing events belong to Tabs.

---

Document: llms/en-US/components/tag.md

<!-- Source: src/tag/README.en-US.md; locale: en-US; page: /en/components/tag/ -->

# Tag

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `color`: Overrides the color.

Example source: src/tag/__demos__/basic.vue

```vue
<template>
  <c-space wrap fill>
    <c-tag>Default</c-tag>
    <c-tag>Tag 1</c-tag>
    <c-tag>Tag 2</c-tag>
    <c-tag>
      <template #icon>
        <c-icon-check-circle-fill />
      </template>
      Complete
    </c-tag>
  </c-space>
  <br />
  <c-space wrap fill>
    <c-tag>gray</c-tag>
    <c-tag color="brand">brand</c-tag>
    <c-tag color="green">green</c-tag>
    <c-tag color="orange">orange</c-tag>
    <c-tag color="red">red</c-tag>
    <c-tag color="blue">blue</c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## Appearance and states

### Color

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `color` | Custom background (border color when outline) | Color |
| `closable` | Whether the tag can be closed | Color |
<!-- demo-config-notes:end -->


- `color`: Overrides the color.

Example source: src/tag/__demos__/color.vue

```vue
<template>
  <c-space wrap>
    <c-tag v-for="(color, index) of colors" :key="index" :color="color" closable>{{ color }}</c-tag>
  </c-space>
  <h3>Custom Color:</h3>
  <c-space wrap>
    <c-tag v-for="(color, index) of custom" :key="index" :color="color" closable>{{ color }}</c-tag>
  </c-space>
</template>

<script lang="ts" setup>
const colors = [
  'red',
  'orangered',
  'orange',
  'gold',
  'lime',
  'green',
  'cyan',
  'blue',
  'brand',
  'purple',
  'pinkpurple',
  'magenta',
  'gray',
]
const custom = [
  '#f53f3f',
  '#7816ff',
  '#00b42a',
  '#00BEBE',
  '#ff7d00',
  '#eb0aa4',
  '#7bc616',
  '#86909c',
  '#b71de8',
  '#0fc6c2',
  '#ffb400',
  '#168cff',
  '#ff5722',
]
</script>
```

### Appearance configuration comparison

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/tag/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({
  variant: "default",
  status: "default",
  size: "md",
});

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["default","outline"]},{"name":"status","values":["default","primary","secondary","tertiary","info","success","warning","danger"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'outline', value: 'outline' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'secondary', value: 'secondary' },
            { label: 'tertiary', value: 'tertiary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-tag v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }">gray</c-tag>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Content and presentation

### Checkable

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `color` | Custom background (border color when outline) | Checkable, Icon |
| `checkable` | Whether the tag is selectable | Checkable |
| `status` | Tag status `color`; mutually exclusive with `color`, which takes precedence | Checkable |
| `default-value` | Default checked state of a selectable tag | Checkable |
| `variant` | Tag variant, aligned with Button | Checkable |
| `loading` | Whether the tag is loading | Checkable |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.
- `variant`: Selects the visual variant.
- `color`: Overrides the color.

Example source: src/tag/__demos__/checkable.vue

```vue
<template>
  <c-space wrap>
    <c-tag checkable>Awesome</c-tag>
    <c-tag checkable status="primary" :default-value="false">点击选中</c-tag>
    <c-tag checkable status="warning" variant="outline">描边状态</c-tag>
    <c-tag checkable status="success" loading>加载中</c-tag>
    <c-tag checkable color="red" :default-value="true">Toutiao</c-tag>
    <c-tag checkable color="brand" :default-value="true">Lark</c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

### Icon

- `color`: Overrides the color.

Example source: src/tag/__demos__/icon.vue

```vue
<template>
  <c-space wrap>
    <c-tag color="gray">
      <template #icon>
        <c-icon-github />
      </template>
      Github
    </c-tag>
    <c-tag color="orangered">
      <template #icon>
        <c-icon-gitlab />
      </template>
      Gitlab
    </c-tag>
    <c-tag color="blue">
      <template #icon>
        <c-icon-twitter />
      </template>
      Twitter
    </c-tag>
    <c-tag color="brand">
      <template #icon>
        <c-icon-facebook />
      </template>
      Facebook
    </c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

## Interaction and control

### Closable

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `closable` | Whether the tag can be closed | Closable, Dynamic Tag |
| `loading` | Whether the tag is loading | Loading |
<!-- demo-config-notes:end -->


Preview configuration: `closable`.

Example source: src/tag/__demos__/closable.vue

```vue
<template>
  <c-space wrap>
    <c-tag closable>Tag</c-tag>
    <c-tag closable>
      <template #icon>
        <c-icon-star />
      </template>
      Tag
    </c-tag>
  </c-space>
</template>

<script lang="ts" setup>
</script>
```

### Dynamic Tag

Preview configuration: `:closable="index !== 0"`, `size="xs"`.

Example source: src/tag/__demos__/dynamic-tag.vue

```vue
<template>
  <c-space wrap>
    <c-tag v-for="(tag, index) of tags" :key="tag" :closable="index !== 0" @close="handleRemove(tag)">
      {{ tag }}
    </c-tag>

    <c-input
      v-if="showInput"
      ref="inputRef"
      :style="{ width: '90px' }"
      size="xs"
      v-model.trim="inputVal"
      @keyup.enter="handleAdd"
      @blur="handleAdd" />
    <c-tag
      v-else
      :style="{
        width: '90px',
        backgroundColor: 'var(--color-fill-2)',
        border: '1px dashed var(--color-fill-3)',
        cursor: 'pointer',
      }"
      @click="handleEdit"
    >
      <template #icon>
        <c-icon-plus />
      </template>
      Add Tag
    </c-tag>
  </c-space>
</template>

<script lang="ts" setup>
import { ref, nextTick } from 'vue'
const tags = ref(['Tag 1', 'Tag 2', 'Tag 3'])
const inputRef = ref(null)
const showInput = ref(false)
const inputVal = ref('')

const handleEdit = () => {
  showInput.value = true

  nextTick(() => {
    if (inputRef.value) {
      inputRef.value.focus()
    }
  })
}

const handleAdd = () => {
  if (inputVal.value) {
    tags.value.push(inputVal.value)
    inputVal.value = ''
  }
  showInput.value = false
}

const handleRemove = (key) => {
  tags.value = tags.value.filter((tag) => tag !== key)
}
</script>
```

### Loading

Preview configuration: `loading`.

Example source: src/tag/__demos__/loading.vue

```vue
<template>
  <c-tag loading>Loading</c-tag>
</template>

<script lang="ts" setup>
</script>
```

## API

### Value and default value

Use ordinary `v-model`. `modelValue` is a selectable tag's boolean checked state. `defaultValue` initializes uncontrolled state once; later changes do not reset it. Explicit binding takes precedence, without initialization `update:modelValue`.

### `<Tag>` Props

| Prop | Description | Type | Default |
| --------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| color | Custom background (border color when outline) | `string` | - |
| text-color | Custom text color | `string` | - |
| status | Tag status `color`; mutually exclusive with `color`, which takes precedence | `'default' \| 'primary' \| 'secondary' \| 'tertiary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'default'` |
| variant | Tag variant, aligned with Button | `'default' \| 'outline'` | `'default'` |
| size | Tag size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| show **(v-model)** | Whether the tag is visible | `boolean` | - |
| default-show | Default tag visibility | `boolean` | `true` |
| loading | Whether the tag is loading | `boolean` | `false` |
| closable | Whether the tag can be closed | `boolean` | `false` |
| checkable | Whether the tag is selectable | `boolean` | `false` |
| model-value **(v-model)** | Whether a selectable tag is checked | `boolean` | - |
| default-value | Default checked state of a selectable tag | `boolean` | `true` |
| nowrap | Whether content is nowrap with ellipsis | `boolean` | `false` |
| round | Whether to use a pill shape | `boolean` | `false` |

### `<Tag>` Events

| Event | Description | Arguments |
| ------ | -------------------------------------- | --------------------------------------------- |
| close | Triggered when the Close button is clicked and can only be used when the Close button is displayed | `(event: MouseEvent) => void` |
| check | Emitted on user selection, only in selectable mode | `(check: boolean, event: MouseEvent) => void` |
| update:show | Visibility changed | `(show: boolean) => void` |
| update:model-value | Checked-state change | `(checked: boolean) => void` |

### `<Tag>` Slots

| Slot | Description | Arguments |
| ---------- | -------------- | ---- |
| default | Tag content | - |
| icon | Icon | - |
| close-icon | Close-button icon | - |

### Type definitions

The component exports the following types

```ts
import type { TagProps } from '@cedar-design/ui'
```

## Shared implementation and platform boundaries

Each platform maintains a complete local implementation. They do not import a common core or share component instances or reactive state. Changes must update both implementations. Component bodies, props, key styles and paired tests have read-only source consistency checks; theme tokens and installation entries remain local to each library.

Both retain independent show/checked state, with controlled values updated by callers. Fade-out remains; class/style fall through explicitly to the actual tag. Size configuration, RTL context and icons are locally adapted. Mobile touch dimensions remain in tokens.

### Complete variable defaults and boundaries

Status text and outline borders use readable system content colors; colored fills use palette level 1. Unchecked stays neutral; checked status colors override generic hover. Neutral fills use fill-2 → fill-3. color overrides status; preset colors are outside this contrast guarantee. Callers must check custom backgrounds and set text-color if needed. Platform dimensions remain distinct. All public declarations are listed; 15 unused preset-icon hover-background/size variables, custom-icon-bg-hover and old InputTag references are removed without aliases.

| Variable | Default |
| --- | --- |
| `--c-tag-status-primary-bg-color` | `rgb(var(--c-primary-1))` |
| `--c-tag-status-primary-text-color` | `var(--c-sys-color-content-brand)` |
| `--c-tag-status-secondary-bg-color` | `rgb(var(--c-gray-2))` |
| `--c-tag-status-secondary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-status-tertiary-bg-color` | `rgb(var(--c-gray-1))` |
| `--c-tag-status-tertiary-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-status-info-bg-color` | `rgb(var(--c-blue-1))` |
| `--c-tag-status-info-text-color` | `var(--c-sys-color-content-info)` |
| `--c-tag-status-success-bg-color` | `rgb(var(--c-success-1))` |
| `--c-tag-status-success-text-color` | `var(--c-sys-color-content-success)` |
| `--c-tag-status-warning-bg-color` | `rgb(var(--c-warning-1))` |
| `--c-tag-status-warning-text-color` | `var(--c-sys-color-content-warning)` |
| `--c-tag-status-danger-bg-color` | `rgb(var(--c-danger-1))` |
| `--c-tag-status-danger-text-color` | `var(--c-sys-color-content-danger)` |
| `--c-tag-variant-outline-status-primary-color` | `var(--c-sys-color-content-brand)` |
| `--c-tag-variant-outline-status-secondary-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-variant-outline-status-tertiary-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-variant-outline-status-info-color` | `var(--c-sys-color-content-info)` |
| `--c-tag-variant-outline-status-success-color` | `var(--c-sys-color-content-success)` |
| `--c-tag-variant-outline-status-warning-color` | `var(--c-sys-color-content-warning)` |
| `--c-tag-variant-outline-status-danger-color` | `var(--c-sys-color-content-danger)` |
| `--c-tag-variant-outline-default-color` | `var(--c-sys-color-content-primary)` |
| `--c-tag-variant-outline-default-border-color` | `var(--c-sys-color-border-default)` |
| `--c-tag-border-width` | `1px` |
| `--c-tag-border-type` | `solid` |
| `--c-tag-padding-horizontal` | `var(--c-spacing-4)` |
| `--c-tag-padding-vertical` | `0` |
| `--c-tag-icon-margin-right` | `var(--c-spacing-2)` |
| `--c-tag-text-font-weight` | `var(--c-font-weight-500)` |
| `--c-tag-border-radius` | `var(--c-sys-radius-sm)` |
| `--c-tag-round-radius` | `100px` |
| `--c-tag-size-xs` | `var(--c-size-4)` |
| `--c-tag-size-sm` | `var(--c-size-5)` |
| `--c-tag-size-md` | `var(--c-size-6)` |
| `--c-tag-size-lg` | `var(--c-size-7)` |
| `--c-tag-size-xl` | `var(--c-size-8)` |
| `--c-tag-size-xs-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tag-size-sm-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tag-size-md-font-size` | `var(--c-sys-font-size-xs)` |
| `--c-tag-size-lg-font-size` | `var(--c-sys-font-size-md)` |
| `--c-tag-size-xl-font-size` | `var(--c-sys-font-size-md)` |
| `--c-tag-bg-not-checked-hover` | `var(--c-sys-color-state-hover)` |
| `--c-tag-custom-text-color` | `var(--c-sys-color-content-on-dark)` |
| `--c-tag-default-bg` | `var(--c-sys-color-state-hover)` |
| `--c-tag-default-bg-hover` | `var(--c-color-fill-3)` |
| `--c-tag-default-icon-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-default-text-color` | `var(--c-sys-color-content-primary)` |
| `--c-tag-default-border-color` | `transparent` |
| `--c-tag-default-border-color-hover` | `transparent` |
| `--c-tag-red-bg` | `rgb(var(--c-red-1))` |
| `--c-tag-red-bg-hover` | `rgb(var(--c-red-2))` |
| `--c-tag-red-border-color` | `transparent` |
| `--c-tag-red-border-color-hover` | `transparent` |
| `--c-tag-red-icon-color` | `rgb(var(--c-red-9))` |
| `--c-tag-red-text-color` | `rgb(var(--c-red-9))` |
| `--c-tag-orangered-bg` | `rgb(var(--c-orangered-1))` |
| `--c-tag-orangered-bg-hover` | `rgb(var(--c-orangered-2))` |
| `--c-tag-orangered-border-color` | `transparent` |
| `--c-tag-orangered-border-color-hover` | `transparent` |
| `--c-tag-orangered-icon-color` | `rgb(var(--c-orangered-9))` |
| `--c-tag-orangered-text-color` | `rgb(var(--c-orangered-9))` |
| `--c-tag-orange-bg` | `rgb(var(--c-orange-1))` |
| `--c-tag-orange-bg-hover` | `rgb(var(--c-orange-2))` |
| `--c-tag-orange-border-color` | `transparent` |
| `--c-tag-orange-border-color-hover` | `transparent` |
| `--c-tag-orange-icon-color` | `rgb(var(--c-orange-9))` |
| `--c-tag-orange-text-color` | `rgb(var(--c-orange-9))` |
| `--c-tag-gold-bg` | `rgb(var(--c-gold-1))` |
| `--c-tag-gold-bg-hover` | `rgb(var(--c-gold-2))` |
| `--c-tag-gold-border-color` | `transparent` |
| `--c-tag-gold-border-color-hover` | `transparent` |
| `--c-tag-gold-icon-color` | `rgb(var(--c-gold-9))` |
| `--c-tag-gold-text-color` | `rgb(var(--c-gold-9))` |
| `--c-tag-lime-bg` | `rgb(var(--c-lime-1))` |
| `--c-tag-lime-bg-hover` | `rgb(var(--c-lime-2))` |
| `--c-tag-lime-border-color` | `transparent` |
| `--c-tag-lime-border-color-hover` | `transparent` |
| `--c-tag-lime-icon-color` | `rgb(var(--c-lime-9))` |
| `--c-tag-lime-text-color` | `rgb(var(--c-lime-9))` |
| `--c-tag-green-bg` | `rgb(var(--c-green-1))` |
| `--c-tag-green-bg-hover` | `rgb(var(--c-green-2))` |
| `--c-tag-green-border-color` | `transparent` |
| `--c-tag-green-border-color-hover` | `transparent` |
| `--c-tag-green-icon-color` | `rgb(var(--c-green-9))` |
| `--c-tag-green-text-color` | `rgb(var(--c-green-9))` |
| `--c-tag-cyan-bg` | `rgb(var(--c-cyan-1))` |
| `--c-tag-cyan-bg-hover` | `rgb(var(--c-cyan-2))` |
| `--c-tag-cyan-border-color` | `transparent` |
| `--c-tag-cyan-border-color-hover` | `transparent` |
| `--c-tag-cyan-icon-color` | `rgb(var(--c-cyan-9))` |
| `--c-tag-cyan-text-color` | `rgb(var(--c-cyan-9))` |
| `--c-tag-blue-bg` | `rgb(var(--c-blue-1))` |
| `--c-tag-blue-bg-hover` | `rgb(var(--c-blue-2))` |
| `--c-tag-blue-border-color` | `transparent` |
| `--c-tag-blue-border-color-hover` | `transparent` |
| `--c-tag-blue-icon-color` | `rgb(var(--c-blue-9))` |
| `--c-tag-blue-text-color` | `rgb(var(--c-blue-9))` |
| `--c-tag-brand-bg` | `rgb(var(--c-brand-1))` |
| `--c-tag-brand-bg-hover` | `rgb(var(--c-brand-2))` |
| `--c-tag-brand-border-color` | `transparent` |
| `--c-tag-brand-border-color-hover` | `transparent` |
| `--c-tag-brand-icon-color` | `rgb(var(--c-brand-9))` |
| `--c-tag-brand-text-color` | `rgb(var(--c-brand-9))` |
| `--c-tag-purple-bg` | `rgb(var(--c-purple-1))` |
| `--c-tag-purple-bg-hover` | `rgb(var(--c-purple-2))` |
| `--c-tag-purple-border-color` | `transparent` |
| `--c-tag-purple-border-color-hover` | `transparent` |
| `--c-tag-purple-icon-color` | `rgb(var(--c-purple-9))` |
| `--c-tag-purple-text-color` | `rgb(var(--c-purple-9))` |
| `--c-tag-pinkpurple-bg` | `rgb(var(--c-pinkpurple-1))` |
| `--c-tag-pinkpurple-bg-hover` | `rgb(var(--c-pinkpurple-2))` |
| `--c-tag-pinkpurple-border-color` | `transparent` |
| `--c-tag-pinkpurple-border-color-hover` | `transparent` |
| `--c-tag-pinkpurple-icon-color` | `rgb(var(--c-pinkpurple-9))` |
| `--c-tag-pinkpurple-text-color` | `rgb(var(--c-pinkpurple-9))` |
| `--c-tag-magenta-bg` | `rgb(var(--c-magenta-1))` |
| `--c-tag-magenta-bg-hover` | `rgb(var(--c-magenta-2))` |
| `--c-tag-magenta-border-color` | `transparent` |
| `--c-tag-magenta-border-color-hover` | `transparent` |
| `--c-tag-magenta-icon-color` | `rgb(var(--c-magenta-9))` |
| `--c-tag-magenta-text-color` | `rgb(var(--c-magenta-9))` |
| `--c-tag-gray-bg` | `rgb(var(--c-gray-2))` |
| `--c-tag-gray-bg-hover` | `rgb(var(--c-gray-3))` |
| `--c-tag-gray-border-color` | `transparent` |
| `--c-tag-gray-border-color-hover` | `transparent` |
| `--c-tag-gray-icon-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-gray-text-color` | `var(--c-sys-color-content-secondary)` |
| `--c-tag-close-margin-left` | `var(--c-spacing-2)` |
| `--c-tag-close-font-size` | `var(--c-sys-font-size-xs)` |

### Color override boundaries

Preset outline stays transparent; loading does not trigger preset fill hover. Dark backgrounds consume bg/bg-hover with instance overrides. Preset icon-color is separate from text-color. Unchecked presets remain neutral, while an explicit color still applies. Preset/custom colors do not guarantee contrast on arbitrary backgrounds.

### Motion variables

Built-in motion follows `prefers-reduced-motion: reduce`. Reduced motion does not prevent loading-state or close-event updates.

| Token | Default |
| --- | --- |
| `--c-tag-fade-duration` | `var(--c-sys-motion-duration-fast)` |

---

Document: llms/en-US/components/textarea.md

<!-- Source: src/textarea/README.en-US.md; locale: en-US; page: /en/components/textarea/ -->

# Textarea

Multiline text input.

## Reading direction

The textarea inherits source `dir`, aligns text to inline start and its counter to inline end. Runtime direction changes retain the native editor, focus and selection; native caret and newline keys keep their meanings.

## Basic examples

### Basic usage

Example source: src/textarea/__demos__/basic.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('')
const trimmed = ref('')
</script>
<template>
  <c-space direction="column">
    <c-textarea v-model="value" clearable placeholder="请输入多行文本" aria-label="受控文本" />
    <p role="status">当前值：{{ value || '（空）' }}</p>
    <c-textarea default-value="这是一段非受控初始文本" aria-label="非受控文本" />
    <c-textarea v-model.trim="trimmed" placeholder="输入首尾空白，失焦后去除" aria-label="去除首尾空白" />
    <p role="status">去除空白后的值：{{ JSON.stringify(trimmed) }}</p>
  </c-space>
</template>
```

## Appearance and states

### Status

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                           | Related examples |
| --------------- | --------------------------------- | ---------------- |
| `placeholder`   | Placeholder text                  | Status           |
| `variant`       | `filled` / `outline` / `standard` | Status           |
| `default-value` | Uncontrolled initial value        | Status           |
| `readonly`      | Whether readonly                  | Status           |
| `disabled`      | Whether disabled                  | Status           |
| `error`         | Show the error state              | Status           |

<!-- demo-config-notes:end -->

- `variant`: Selects the visual variant.
- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/textarea/__demos__/status.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-textarea placeholder="默认描边外观" />
    <c-textarea variant="filled" placeholder="填充外观" />
    <c-textarea variant="standard" placeholder="标准外观" />
    <c-textarea default-value="Readonly value" readonly />
    <c-textarea placeholder="Disabled status" disabled />
    <c-textarea placeholder="Error status" error />
  </c-space>
</template>
```

### Appearance Lab

Example source: src/textarea/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("这是一段可以编辑的多行内容。");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-textarea v-model="value" v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"></c-textarea>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Content and presentation

### Max Length

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                      | Related examples |
| ----------------- | -------------------------------------------- | ---------------- |
| `placeholder`     | Placeholder text                             | Max Length       |
| `max-length`      | Truncating or error-only length limit        | Max Length       |
| `clearable`       | Enables the clear action                     | Max Length       |
| `show-word-limit` | Show the character counter                   | Max Length       |
| `aria-label`      | Accessible name when no visible label exists | Native Attrs     |
| `rows`            | Native visible row count                     | Native Attrs     |

<!-- demo-config-notes:end -->

Example source: src/textarea/__demos__/max-length.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <p>长度按 UTF-16 码元计算；试着输入 123456789😀Z，默认截断保留 123456789，不拆开 emoji。</p>
    <c-textarea
      v-model="limited"
      placeholder="超过 10 个字符会截断"
      :max-length="10"
      clearable
      show-word-limit
    />
    <c-textarea
      v-model="errorOnly"
      placeholder="超过 10 个字符后保留内容并显示错误"
      :max-length="{ length: 10, errorOnly: true }"
      clearable
      show-word-limit
    />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const limited = ref("");
const errorOnly = ref("超过长度的内容会保留");
</script>
```

### Native Attrs

Example source: src/textarea/__demos__/native-attrs.vue

```vue
<template>
  <label for="feedback">反馈内容</label>
  <c-textarea
    v-model="value"
    aria-label="反馈内容"
    :rows="4"
    :textarea-attrs="{
      id: 'feedback',
      name: 'feedback',
      autocomplete: 'off',
      'aria-describedby': 'feedback-help',
    }"
  />
  <p id="feedback-help">请勿填写密码或其他敏感信息。</p>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref("");
</script>
```

## Customization and slots

### Slots

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                  | Related examples |
| ------------- | ------------------------ | ---------------- |
| `clearable`   | Enables the clear action | Slots            |
| `placeholder` | Placeholder text         | Slots            |

<!-- demo-config-notes:end -->

Example source: src/textarea/__demos__/slots.vue

```vue
<template>
  <c-textarea v-model="value" clearable placeholder="带前后缀和自定义清除按钮">
    <template #prefix>说明</template>
    <template #suffix>Markdown</template>
    <template #clear-icon="{ clear }">
      <c-button html-type="button" aria-label="清空文本" @click="clear"
        >×</c-button
      >
    </template>
  </c-textarea>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref("可清空内容");
</script>
```

## Interaction and control

### State Lab

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose                                                | Related examples                      |
| ------------- | ------------------------------------------------------ | ------------------------------------- |
| `placeholder` | Placeholder text                                       | Auto Size, Interaction, Body Contract |
| `rows`        | Native visible row count                               | Auto Size, Body Contract              |
| `auto-size`   | Automatic height, optionally with minimum/maximum rows | Auto Size, Body Contract              |
| `clearable`   | Enables the clear action                               | Interaction, Body Contract            |
| `disabled`    | Whether disabled                                       | State Lab                             |
| `readonly`    | Whether readonly                                       | State Lab                             |

<!-- demo-config-notes:end -->

Example source: src/textarea/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("这是一段可以编辑的多行内容。");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-textarea v-model="value" v-bind="__demoState"></c-textarea>
  </c-space>
</template>
```

### Auto Size

Example source: src/textarea/__demos__/auto-size.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-textarea default-value="原生三行，可纵向拖动" :rows="3" />
    <c-textarea v-model="content" auto-size placeholder="随内容自动增高" />
    <c-textarea
      v-model="boundedContent"
      :auto-size="{ minRows: 2, maxRows: 5 }"
      placeholder="自动高度限制在 2 到 5 行"
    />
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const content = ref("第一行");
const boundedContent = ref("第一行\n第二行");
</script>
```

### Interaction

Example source: src/textarea/__demos__/interaction.vue

```vue
<template>
  <c-space direction="column" size="lg" fill>
    <c-textarea
      v-model="value"
      clearable
      placeholder="输入、换行并失焦以观察事件"
      @input="record('input', $event)"
      @change="record('change', $event)"
      @keydown="record('keydown')"
      @clear="record('clear')"
      @blur="record('blur')"
    />
    <span>最近事件：{{ latest || "-" }}</span>
  </c-space>
</template>

<script lang="ts" setup>
import { ref } from "vue";

const value = ref("Cedar");
const latest = ref("");

const record = (name: string, value?: string) => {
  latest.value = value === undefined ? name : `${name}: ${value}`;
};
</script>
```

### Body Contract

Example source: src/textarea/__demos__/body-contract.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const value = ref('可编辑内容')
const events = ref<string[]>([])
const record = (name: string) => { events.value = [...events.value.slice(-7), name] }
</script>
<template>
  <div class="textarea-body-demo">
    <c-textarea v-model="value" hint clearable placeholder="工作备注" :auto-size="{ minRows: 2, maxRows: 5 }" :max-length="100" show-word-limit @clear="record('clear')" @input="record('input')" @update:model-value="record('update:modelValue')" @change="record('change')" />
    <c-textarea :line="false" hint placeholder="无边框提示" focus-color="#137547" :rows="2" />
    <p>Enter 保持换行；失焦提交 change；清空完整通知一次。</p>
    <output>{{ events.join(' → ') || '等待操作' }}</output>
  </div>
</template>
<style scoped>
.textarea-body-demo { display: flex; flex-direction: column; gap: 16px; }
.textarea-body-demo p { margin: 0; }
</style>
```

## Design notes

- Defaults to `outline` with `clearable` disabled.
- `input` means live editing; `change` commits on changed blur or clear. Enter remains a newline.
- `auto-size` lets content determine height, overriding visual effects of `rows`/manual `resize`.
- Form/FormItem own business validation/messages; Textarea supplies event signals/error appearance only.

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Textarea Props

Supports Input-compatible hint, line, text-color, focus-color and blur-color. Omitted hint inherits InputGroup/library defaults. An outer FormItem label hides the internal floating hint.

| Prop                    | Description                                                      | Type                                                | Default   |
| ----------------------- | ---------------------------------------------------------------- | --------------------------------------------------- | --------- |
| model-value (`v-model`) | Controlled value                                                 | `string`                                            | `-`       |
| default-value           | Uncontrolled initial value                                       | `string`                                            | `''`      |
| model-modifiers         | Supports the `trim` model modifier                               | `{ trim?: boolean }`                                | `{}`      |
| placeholder             | Placeholder text                                                 | `string`                                            | `-`       |
| variant                 | `filled` / `outline` / `standard`                                | `FormControlVariant`                                | `outline` |
| size                    | `xs` / `sm` / `md` / `lg` / `xl`                                 | `ComponentSize`                                     | `md`      |
| clearable               | Enables the clear action                                         | `boolean`                                           | `false`   |
| disabled                | Whether disabled                                                 | `boolean`                                           | `false`   |
| readonly                | Whether readonly                                                 | `boolean`                                           | `false`   |
| error                   | Show the error state                                             | `boolean`                                           | `false`   |
| rows                    | Native visible row count                                         | `string \| number`                                  | `-`       |
| resize                  | Allows vertical manual resizing                                  | `boolean`                                           | `true`    |
| auto-size               | Automatic height, optionally with minimum/maximum rows           | `boolean \| { minRows?: number; maxRows?: number }` | `false`   |
| max-length              | Truncating or error-only length limit                            | `number \| { length: number; errorOnly?: boolean }` | `0`       |
| show-word-limit         | Show the character counter                                       | `boolean`                                           | `false`   |
| word-length             | Custom length function                                           | `(value: string) => number`                         | `-`       |
| word-slice              | Custom slice function                                            | `(value: string, maxLength: number) => string`      | `-`       |
| aria-label              | Accessible name when no visible label exists                     | `string`                                            | `-`       |
| autofocus               | Focus automatically after mount                                  | `boolean`                                           | `false`   |
| enterkeyhint            | Virtual keyboard Enter hint                                      | `string`                                            | `-`       |
| textarea-attrs          | Supplemental native textarea attributes                          | `Record<string, unknown>`                           | `-`       |
| hint                    | Floating hint; inherits InputGroup/library defaults when omitted | boolean                                             | undefined |
| line                    | Show border/underline                                            | boolean                                             | true      |
| text-color              | Instance text color                                              | string                                              | undefined |
| focus-color             | Instance focus color                                             | string                                              | undefined |
| blur-color              | Instance unfocused hint color                                    | string                                              | undefined |

### Textarea Events

| Event   | Description                                    | Arguments                  |
| ------- | ---------------------------------------------- | -------------------------- |
| input   | User input after IME composition               | `value: string, ev: Event` |
| change  | Changed value committed on blur                | `value: string, ev: Event` |
| keydown | Native keydown signal; Enter remains a newline | `ev: KeyboardEvent`        |
| clear   | Clear → input → update:model-value → change    | `ev: Event`                |
| focus   | Emitted on focus                               | `ev: FocusEvent`           |
| blur    | Emitted on blur                                | `ev: FocusEvent`           |

### Textarea Slots

| Slot       | Description          | Arguments                     |
| ---------- | -------------------- | ----------------------------- |
| prefix     | Prefix content       | `-`                           |
| suffix     | Suffix content       | `-`                           |
| clear-icon | Clear icon or button | `clear: (ev?: Event) => void` |

### Textarea Methods

| Method | Description                 |
| ------ | --------------------------- |
| focus  | Focus the internal textarea |
| blur   | Blur the internal textarea  |

## Type definitions

```ts
import type {
  TextareaAutoSize,
  TextareaMaxLength,
  TextareaProps,
  WordLength,
  WordSlice,
} from "@cedar-design/ui";
```

## Style variables

| Variable                          | Default                           |
| --------------------------------- | --------------------------------- |
| `--c-textarea-height`             | `auto`                            |
| `--c-textarea-min-height`         | `--c-sys-control-height-xl`       |
| `--c-textarea-font-size`          | `--c-sys-font-size-md`            |
| `--c-textarea-line-height`        | `--c-line-height`                 |
| `--c-textarea-padding-horizontal` | `--c-sys-space-3`                 |
| `--c-textarea-padding-vertical`   | `--c-sys-space-1`                 |
| `--c-textarea-placeholder-color`  | `--c-sys-color-content-secondary` |
| `--c-textarea-counter-color`      | `--c-sys-color-content-secondary` |
| `--c-textarea-counter-font-size`  | `--c-sys-font-size-xs`            |
| `--c-textarea-counter-margin-top` | `var(--c-sys-space-2)`            |

Both counters sit outside the textarea. counter-margin-top controls their gap and avoids covering text.

### Native layout and public types

size supports five FieldDecorator densities: xs/sm/md/lg/xl. rows, auto-size and Textarea tokens still control textarea height/text metrics. Cedar allows manual resize by default; Maple does not. InputGroup/Form state is inherited, with explicit child values taking precedence. Exposes focus(options?), blur(), select() and textareaRef.

`TextareaProps`、`TextareaVariant`、`TextareaMaxLength`、`TextareaAutoSize`、`TextareaEmits`、`TextareaSlots`、`TextareaExpose`、`TextareaInstance`。

Native methods: `focus(options?: FocusOptions)`, `blur()`, `select()`; `textareaRef` is the native element.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`--c-field-caret-color` sets the shared caret color, defaulting to `currentColor`. `--c-textarea-caret-color` overrides this component and defaults to `var(--c-field-caret-color)`.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.
Text and person-ID models remain strings; use an empty string or a business-defined string sentinel.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/time-picker.md

<!-- Source: src/time/picker/README.en-US.md; locale: en-US; page: /en/components/time-picker/ -->

# Time Picker

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `default-value="09:09:06"`.

Example source: src/time/picker/__demos__/basic.vue

```vue
<template>
  <c-time-picker default-value="09:09:06" />
</template>
```

## Format and presentation

### Format

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `format` | Display format | Format, Use12Hours |
| `use12-hours` | 12-hour clock | Use12Hours |
<!-- demo-config-notes:end -->


- `format`: Controls the displayed format.

Example source: src/time/picker/__demos__/format.vue

```vue
<template>
  <c-time-picker format="HH:mm" default-value="09:24" />
</template>
```

### Use12Hours

- `format`: Controls the displayed format.

Example source: src/time/picker/__demos__/use12Hours.vue

```vue
<template>
  <c-space>
    <c-time-picker use12-hours default-value="12:20:20 AM" format="hh:mm:ss A" />
    <c-time-picker use12-hours default-value="09:20:20 pm" format="hh:mm:ss a" />
    <c-time-picker use12-hours default-value="2:20 AM" format="h:mm A" />
  </c-space>
</template>
```

## Selection rules and interaction

### Disabled Parts

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `format` | Display format | Disabled Parts, Bounds, Panel Behavior |
| `disable-confirm` | Skip confirmation | No Confirm, Panel Behavior |
| `use12-hours` | 12-hour clock | Disabled Parts |
| `step` | Hour/minute/second steps | Step |
| `hide-disabled-options` | Hide disabled time options | Panel Behavior |
<!-- demo-config-notes:end -->


- `format`: Controls the displayed format.

Example source: src/time/picker/__demos__/disabled-parts.vue

```vue
<template>
  <p>12 小时显示；禁用回调始终使用 0–23 小时。下午 1 点禁用，下午 2 点的第 30 分钟禁用。</p>
  <c-time-picker
    default-value="02:20:00 pm"
    format="hh:mm:ss a"
    use12-hours
    :disabled-hours="() => [0, 13]"
    :disabled-minutes="(hour) => hour === 14 ? [30] : []"
    :disabled-seconds="(hour, minute) => hour === 14 && minute === 20 ? [15, 30, 45] : []"
  />
</template>
```

### Step

- `step`: Controls the allowed increment.

Example source: src/time/picker/__demos__/step.vue

```vue
<template>
  <c-time-picker
    default-value="10:25:30"
    :step="{
      hour: 2,
      minute: 5,
      second: 10,
    }"
  />
</template>
```

### Bounds

- `format`: Controls the displayed format.
- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/time/__demos__/bounds.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("10:30:38");
const narrow = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>
      包含边界：10:30:38–10:31:02。收紧边界不会改写已有模型，但越界值无法确认。
    </p>
    <c-checkbox v-model="narrow"> 将下限调整为 10:30:40</c-checkbox>
    <c-time
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <c-time-picker
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### No Confirm

Preview configuration: `disable-confirm`.

Example source: src/time/picker/__demos__/no-confirm.vue

```vue
<template>
  <c-time-picker disable-confirm />
</template>
```

### Panel Behavior

- `format`: Controls the displayed format.
- `readonly`: Displays the current value without allowing edits.

Example source: src/time/picker/__demos__/panel-behavior.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:30");
const immediate = ref(false);
const confirmations = ref(0);
const hideDisabled = ref(false);
const readonly = ref(false);
const disabledHours = () => [0, 1, 2, 3, 4, 5, 6, 7];
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <c-checkbox v-model="immediate"> 跳过确认，选择即提交</c-checkbox>
    <c-checkbox v-model="hideDisabled"> 隐藏禁用小时（00–07）</c-checkbox>
    <c-checkbox v-model="readonly"> 只读（包括确认）</c-checkbox>
    <c-button variant="outline" @click="value = '13:45'"
      >外部更新为 13:45，覆盖未提交草稿</c-button
    >
    <c-time-picker
      v-model="value"
      @confirm="confirmations++"
      format="HH:mm"
      :disable-confirm="immediate"
      :hide-disabled-options="hideDisabled"
      :readonly="readonly"
      :disabled-hours="disabledHours"
    >
      <template #extra
        ><p>附加说明使用 extra 插槽；选择草稿后点击确认提交。</p></template
      >
    </c-time-picker>
    <span>有效确认次数: {{ confirmations }}</span>
    <span>已提交值: {{ value }}</span>
    <p>默认选择只修改草稿，点击确认后上方的已提交值才会更新。</p>
  </c-space>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"`. Direction changes neither change the time nor commit drafts. Time columns follow reading order; Left/Right moves focus visually between columns. Cedar Up/Down and Home/End move focus within a column, skipping disabled options; Enter/Space selects. Maple wheels retain their existing Up/Down and Home/End selection behavior. Existing confirmation settings control submission. Popovers inherit their source direction.

## API

The panel owns one draft/confirmation state, reused by its presentation. Examples show the extra slot and valid-confirm count. Confirming the same value again emits confirm without a duplicate change.

### Pure-panel event and slot boundaries

`TimePicker`/`TimeRangePicker` do not manage fields/popups. Pass `open`, `size`, `variant`, clearing and popup configuration to `Time`/`TimeRange`.

- `select(value, date)`: edit the draft.
- `change(value, date)`: valid confirmation with a changed value; updates the model.
- `confirm(value, date)`: every valid confirmation, including unchanged values. `disableConfirm` also emits it on valid selection commits. Disabled, readonly or invalid drafts do not emit it.
- `extra`: additional explanatory content.
- `actions({ confirm, canConfirm, value })`: replace default tools. `value` is the draft; call `confirm()` to commit and disable buttons according to `canConfirm`.

Single-time events carry formatted strings and Date objects; range events carry corresponding arrays. Pure panels no longer emit `open-change`, `update:open` or `clear`.

### Props

| Arguments | Description | Type | Default |
| --- | --- | --- | --- |
| `model-value` | Bound value | `string \| number \| Date` | `-` |
| `format` | Display format | `string` | `-` |
| `use12-hours` | 12-hour clock | `boolean` | `false` |
| `hide-disabled-options` | Hide disabled time options | `boolean` | `false` |
| `disable-confirm` | Skip confirmation | `boolean` | `false` |
| `disabled` | Disable interaction | `boolean` | `false` |
| `step` | Hour/minute/second steps | `object` | `-` |

---

Document: llms/en-US/components/time-range.md

<!-- Source: src/time-range/README.en-US.md; locale: en-US; page: /en/components/time-range/ -->

# TimeRange

A pair of time endpoints with explicit confirmation.

```ts
import type { TimeRangeProps, TimeRangeInstance } from "@cedar-design/ui";
```

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes null unchanged; omitted values preserve the existing default. Editors render null as blank without converting ordinary empty-string input to null. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

## Basic examples

### Basic usage

Example source: src/time-range/__demos__/basic.vue

```vue
<template>
  <c-time-range v-model="range" style="width: 252px" clearable />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

## Appearance and presentation

### Size

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                                                                        | Related examples                                                  |
| --------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `format`        | Display format                                                                                                 | Field Appearance, Range formats and 12-hour clocks, Show Next Day |
| `clearable`     | Show the clear action                                                                                          | Range formats and 12-hour clocks, Placeholder, Show Next Day      |
| `placeholder`   | Placeholder                                                                                                    | Field Appearance, Placeholder                                     |
| `show-next-day` | Allow end before start and show next day. Otherwise reversed ranges cannot commit. Endpoints are never swapped | Range formats and 12-hour clocks, Show Next Day                   |
| `size`          | Size                                                                                                           | Size                                                              |
| `variant`       | Field appearance                                                                                               | Field Appearance                                                  |

<!-- demo-config-notes:end -->

- `size`: Controls the component size.

Example source: src/time-range/__demos__/size.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-time-range style="width: 252px" size="xs" />
    <c-time-range style="width: 252px" size="sm" />
    <c-time-range style="width: 252px" size="md" />
    <c-time-range style="width: 252px" size="lg" />
    <c-time-range style="width: 252px" size="xl" />
  </c-space>
</template>
```

### Field Appearance

- `format`: Controls the displayed format.
- `variant`: Input variant

Example source: src/time-range/__demos__/field-appearance.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["09:00", "18:00"]);
const hint = ref(true);
const error = ref(false);
const line = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="hint"> 浮动提示</c-checkbox>
    <c-checkbox v-model="error"> 显式错误状态</c-checkbox>
    <c-checkbox v-model="line"> 边框 / 底线</c-checkbox>
    <c-time-range
      v-model="value"
      format="HH:mm"
      variant="outline"
      :placeholder="['开始时间', '结束时间']"
      :hint="hint"
      :error="error"
      :line="line"
      focus-color="#6750a4"
      separator=" → "
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### Range formats and 12-hour clocks

Compare minute, second and 12-hour range displays and edit both endpoints. Next-day rules and model formats remain separate.

Example source: src/time-range/__demos__/format-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const range = ref(['09:30', '18:00'])

const literalRange = ref(['Time 09:30', 'Time 18:00'])

const rangeSeconds = ref(['09:30:20', '18:00:00'])
return { range, literalRange, rangeSeconds }
})())

const scene2 = demoProxyRefs((() => {

const value = ref(['11:30:00 pm', '12:30:00 am'])
return { value }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="format">
    <h4><span lang="zh-CN">显示格式</span><span lang="en-US">format</span></h4>
    <c-space direction="column" fill>
        <c-time-range v-model="scene1.range" format="HH:mm" style="width: 100%; max-width: 360px" clearable />
        <c-time-range v-model="scene1.literalRange" format="[Time] HH:mm" style="width: 100%; max-width: 360px" clearable />
        <c-time-range
          v-model="scene1.rangeSeconds"
          format="HH:mm:ss"
          style="width: 100%; max-width: 360px"
          clearable
        />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="ampm">
    <h4><span lang="zh-CN">十二小时制</span><span lang="en-US">ampm</span></h4>
    <c-space direction="column" :size="12" style="width: 100%">
        <p>分别切换起止端的 AM/PM；12 AM 是午夜，12 PM 是中午。</p>
        <c-time-range v-model="scene2.value" use12-hours show-next-day style="width: 100%; max-width: 360px" />
        
        <span>当前值: {{ scene2.value }}</span>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

### Placeholder

Example source: src/time-range/__demos__/placeholder.vue

```vue
<template>
  <c-time-range
    v-model="range"
    style="width: 280px"
    :placeholder="['开始时间', '结束时间']"
    clearable
  />
</template>

<script setup>
import { ref } from 'vue'

const range = ref()
</script>
```

### Show Next Day

- `format`: Controls the displayed format.

Example source: src/time-range/__demos__/show-next-day.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const range = ref<string[] | undefined>(["22:00", "06:00"]);
const reset = () => {
  range.value = ["22:00", "06:00"];
};
</script>

<template>
  <section class="time-overnight-demo">
    <c-time-range
      v-model="range"
      format="HH:mm"
      input-editable
      show-next-day
      clearable
    />
    <output aria-label="Overnight model">{{
      range === undefined ? "undefined" : JSON.stringify(range)
    }}</output>
    <c-button @click="reset">重置</c-button>
  </section>
</template>

<style scoped>
.time-overnight-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 360px;
}
</style>
```

## Value model and selection rules

### Format Model

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose        | Related examples           |
| ------------- | -------------- | -------------------------- |
| `format`      | Display format | Format Model, Step, Bounds |
| `use12-hours` | 12-hour clock  | Step                       |

<!-- demo-config-notes:end -->

- `format`: Controls the displayed format.

Example source: src/time-range/__demos__/format-model.vue

```vue
<script setup>
import { ref } from 'vue'

const date = new Date(2026, 8, 23, 13, 5, 9)
const later = new Date(2026, 8, 23, 18, 30, 0)
const value = ref([date, later.getTime()])
const literal = ref(['Time 09:30', 'Time 18:00'])
</script>

<template>
  <c-space direction="column" fill style="width: 100%">
    <p>Date 和时间戳按本地时间反显；选择后返回格式化字符串。</p>
    <c-time-range v-model="value" format="hh:mm A" style="width: 100%; max-width: 360px" />
    <span>当前模型: {{ value }}</span>
    <c-time-range v-model="literal" format="[Time] HH:mm" style="width: 100%; max-width: 360px" />
    <span>固定文字格式: {{ literal }}</span>
  </c-space>
</template>
```

### Step

- `format`: Controls the displayed format.
- `step`: Controls the allowed increment.

Example source: src/time-range/__demos__/step.vue

```vue
<script setup>
import { ref } from "vue";
const value = ref(["09:30:00", "17:00:00"]);
const step = { hour: 1, minute: 15, second: 10 };
const use12Hours = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>小时步长 1，分钟步长 15，秒步长 10。</p>
    <c-checkbox v-model="use12Hours">
      12 小时面板，模型仍为 HH:mm:ss</c-checkbox
    >
    <c-time-range
      v-model="value"
      format="HH:mm:ss"
      :use12-hours="use12Hours"
      :step="step"
      style="width: 100%; max-width: 360px"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### Bounds

- `format`: Controls the displayed format.
- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/time-range/__demos__/bounds.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["10:30:38", "10:31:02"]);
const narrow = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>
      包含边界：10:30:38–10:31:02。收紧边界不会改写已有模型，但越界值无法确认。
    </p>
    <c-checkbox v-model="narrow"> 将下限调整为 10:30:40</c-checkbox>
    <c-time-range
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <c-time-range-picker
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

## Input and state control

### Interaction state comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                  | Related examples                                        |
| ---------------- | ------------------------ | ------------------------------------------------------- |
| `format`         | Display format           | Interaction state comparison, Text Entry, Default State |
| `clearable`      | Show the clear action    | Text Entry, Default State, Selection Events             |
| `disabled`       | Disable interaction      | Interaction state comparison, Selection Events          |
| `readonly`       | Read-only interaction    | Interaction state comparison, Selection Events          |
| `input-editable` | Allow desktop text input | Text Entry, Copying and editing                         |
| `model-value`    | Bound value              | Default State                                           |

<!-- demo-config-notes:end -->

Toggle the state, interact with the component, and restore editing using the controls outside the specimen. Error appearance alone does not run validation.

Example source: src/time-range/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref(["09:30", "18:00"]);
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-time-range
      v-model="value"
      format="HH:mm"
      v-bind="__demoState"
    ></c-time-range>
  </c-space>
</template>
```

### Text Entry

- `format`: Controls the displayed format.
- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/time-range/__demos__/text-entry.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["09:00", "10:00"]);
const editable = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="editable"> 允许手输</c-checkbox>
    <p>回车或失焦提交，Esc 撤销。合法范围为 08:00–18:00。</p>
    <c-time-range
      v-model="value"
      :input-editable="editable"
      format="HH:mm"
      min="08:00"
      max="18:00"
      clearable
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### Default State

- `format`: Controls the displayed format.

Example source: src/time-range/__demos__/default-state.vue

```vue
<script setup>
import { ref } from "vue";
const value = ref(["09:00", "10:00"]);
const open = ref(false);
const acceptValue = ref(true);
const acceptOpen = ref(true);
const acceptClose = ref(true);
const commits = ref(0);
const proposal = ref();
const openProposal = ref();
const updateValue = (next) => {
  proposal.value = next;
  if (acceptValue.value) {
    value.value = next;
  }
};
const updateOpen = (next) => {
  openProposal.value = next;
  if (acceptOpen.value && (next || acceptClose.value)) {
    open.value = next;
  }
};
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <p>非受控初始值，无需绑定 v-model</p>
    <c-time-range
      :default-value="['09:00', '10:00']"
      format="HH:mm"
      clearable
    />
    <p>受控值与展开状态</p>
    <c-checkbox v-model="acceptValue"> 接受值更新</c-checkbox>
    <c-checkbox v-model="acceptOpen"> 接受展开更新</c-checkbox>
    <c-time-range
      :model-value="value"
      :open="open"
      format="HH:mm"
      clearable
      @update:model-value="updateValue"
      @update:open="updateOpen"
      @change="commits++"
    />
    <span>{{ value }} / {{ open }}</span>
    <c-checkbox v-model="acceptClose"> 接受关闭请求</c-checkbox>
    <output aria-label="Commit count">{{ commits }}</output>
    <output aria-label="Controlled proposals">{{
      JSON.stringify({ value: proposal, open: openProposal })
    }}</output>
  </c-space>
</template>
```

### Selection Events

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.
- `format`: Controls the displayed format.

Example source: src/time-range/__demos__/selection-events.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref(["09:00", "18:00"]);
const immediate = ref(false);
const readonly = ref(false);
const disabled = ref(false);
const events = ref([]);
function record(name, value, dates) {
  const times = Array.isArray(dates)
    ? dates.map((date) => date?.toLocaleTimeString())
    : dates?.toLocaleTimeString();
  events.value = [
    JSON.stringify({ event: name, value: value ?? null, time: times ?? null }),
    ...events.value,
  ].slice(0, 5);
}
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <c-checkbox v-model="readonly"> 只读：可聚焦，不可修改</c-checkbox>
    <c-checkbox v-model="disabled"> 禁用：释放焦点，不可修改</c-checkbox>
    <c-checkbox v-model="immediate"> 选择后立即提交</c-checkbox>
    <p>select 记录草稿，change 记录提交；取消不改模型，清除返回 undefined。</p>
    <c-time-range
      v-model="value"
      :disable-confirm="immediate"
      :readonly="readonly"
      :disabled="disabled"
      format="HH:mm"
      clearable
      @select="(value, dates) => record('select', value, dates)"
      @change="(value, dates) => record('change', value, dates)"
      @clear="record('clear')"
      @click="record('click')"
      @open-change="(open) => record('open-change', open)"
      @focus="record('focus')"
      @blur="record('blur')"
    />
    <span>模型: {{ value === undefined ? "undefined" : value }}</span>
    <c-button variant="outline" @click="value = ['15:30', '18:00']"
      >从外部替换模型</c-button
    >
    <small>外部替换会更新反显，不触发 select 或 change。</small>
    <div
      v-for="(event, index) in events"
      :key="index"
      style="overflow-wrap: anywhere"
    >
      {{ event }}
    </div>
  </c-space>
</template>
```

### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/time-range/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-time-range
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref(["09:30:00", "10:30:00"]);
</script>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## Reading direction

Range values remain `[start, end]`; direction changes preserve endpoint order, drafts and overnight semantics. Panels and time columns follow reading order, with visual Left/Right focus movement across endpoint columns. Cedar Up/Down moves focus and Enter/Space selects; Maple retains wheel selection with Up/Down. Existing confirmation settings control submission. Popovers inherit their source direction.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Popup configuration and field notifications

`popup-props` configures local Trigger positioning/appearance, e.g. `{ placement: 'top-start' }`, without overriding field open, disabled, trigger or other state/interaction. Top-level `popup-container`, including false, takes precedence. `input-editable` defaults to true and can disable desktop typing. `time-range-picker-props`, including class/style, controls panel appearance. Undeclared attrs no longer supply panel/popup configuration; id/aria-* fall through to the field.

`click(event)` notifies only clicks on non-disabled fields. Readonly may notify without expanding. Closing consistently listens to `open-change(false)`, a close request that controlled open still requires the parent to accept. Neither platform has a field close event; a close request is not a value commit.

`suffix-icon` receives `focus: boolean` and `popupOpen: boolean`. `focus(index = 0)` focuses start (0) or end (1) without committing; `blur()` removes focus and requests closing.

A `placeholder` string applies to both endpoints; arrays provide start/end text, with missing entries empty. Explicit empty strings do not fall back to default text.

### Props

| Arguments                 | Description                                                                                                                      | Type                                                | Default   |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | --------- |
| `open-trigger-target`     | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                                 | `'field'` |
| `model-value`             | Bound value                                                                                                                      | `(string \| number \| Date)[]`                      | `-`       |
| `open`                    | Controlled popup visibility                                                                                                      | `boolean`                                           | `-`       |
| `popup-props`             | Local Trigger presentation options; do not control field state                                                                   | `TimePopupPresentationProps<Partial<TriggerProps>>` | `{}`      |
| `input-editable`          | Allow desktop text input                                                                                                         | `boolean`                                           | `true`    |
| `clearable`               | Show the clear action                                                                                                            | `boolean`                                           | `true`    |
| `disabled`                | Disable interaction                                                                                                              | `boolean`                                           | `false`   |
| `readonly`                | Read-only interaction                                                                                                            | `boolean`                                           | `false`   |
| `size`                    | Size                                                                                                                             | `xs \| sm \| md \| lg \| xl`                        | `-`       |
| `variant`                 | Field appearance                                                                                                                 | `filled \| outline \| standard`                     | `filled`  |
| `placeholder`             | Placeholder                                                                                                                      | `string \| string[]`                                | `-`       |
| `format`                  | Display format                                                                                                                   | `string`                                            | `-`       |
| `use12-hours`             | 12-hour clock                                                                                                                    | `boolean`                                           | `false`   |
| `hide-disabled-options`   | Hide disabled time options                                                                                                       | `boolean`                                           | `false`   |
| `disable-confirm`         | Skip confirmation; valid selections commit immediately and request closing                                                       | `boolean`                                           | `false`   |
| `show-next-day`           | Allow end before start and show next day. Otherwise reversed ranges cannot commit. Endpoints are never swapped                   | `boolean`                                           | `false`   |
| `time-range-picker-props` | Forwarded to TimeRangePicker                                                                                                     | `object`                                            | `{}`      |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

Inline date/time fields retain their existing confirmation policy. In click/dblclick editors, internal panels hide confirmation tools, and the edit layer supplies one confirm/cancel pair. Standalone DatePicker, DateRangePicker, TimePicker and TimeRangePicker retain panel APIs/confirmation and do not inherit Form field presentation.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

### Forwarded configuration boundaries (F07)

Existing TimePopupPresentationProps and runtime filtering remain. Fields own open/defaultOpen, disabled, trigger, closeOnClickReference, preventFocus and expansion updates. Explicit top-level popup-container takes precedence, otherwise nested configuration is used. popupClass merges internal classes. Inline popupOffset stays 4; Maple also fixes unmountOnClose=true. Such fields in old types are not guaranteed to control final values. Existing Time types/runtime behavior are not narrowed here.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/time.md

<!-- Source: src/time/README.en-US.md; locale: en-US; page: /en/components/time/ -->

# Time

A time field with a separate draft and confirmation step.

```ts
import type { TimeProps, TimeInstance } from "@cedar-design/ui";
```

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes null unchanged; omitted values preserve the existing default. Editors render null as blank without converting ordinary empty-string input to null. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

## Basic examples

### Basic usage

Example source: src/time/__demos__/basic.vue

```vue
<template>
  <c-time v-model="value" style="width: 200px" />
</template>

<script setup>
import { ref } from 'vue'

const value = ref()
</script>
```

## Appearance and presentation

### Size

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration | Purpose          | Related examples                                  |
| ------------- | ---------------- | ------------------------------------------------- |
| `size`        | Size             | Size, Control Sizes                               |
| `variant`     | Field appearance | Control Sizes, Field Appearance                   |
| `placeholder` | Placeholder      | Control Sizes, Field Appearance                   |
| `format`      | Display format   | Field Appearance, Time formats and 12-hour clocks |
| `use12-hours` | 12-hour clock    | Time formats and 12-hour clocks                   |

<!-- demo-config-notes:end -->

- `size`: Controls the component size.

Example source: src/time/__demos__/size.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-time style="width: 200px" size="xs" />
    <c-time style="width: 200px" size="sm" />
    <c-time style="width: 200px" size="md" />
    <c-time style="width: 200px" size="lg" />
    <c-time style="width: 200px" size="xl" />
  </c-space>
</template>
```

### Control Sizes

- `size`: Controls the component size.
- `variant`: Input variant

Example source: src/field-decorator/__demos__/control-sizes.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
const sizes = ["xs", "sm", "md", "lg", "xl"] as const;
const variants = ["outline", "filled", "standard"] as const;
const size = ref<(typeof sizes)[number]>("md");
const variant = ref<(typeof variants)[number]>("outline");
const options = [
  { value: "beijing", label: "Beijing" },
  { value: "shanghai", label: "Shanghai" },
];
const cascaderOptions = [{ value: "china", label: "China", children: options }];

const inputValue = ref("Beijing");
const selectValue = ref("beijing");
const cascaderValue = ref("beijing");
const selectMultiple = ref(["beijing", "shanghai"]);
const cascaderMultiple = ref(["beijing", "shanghai"]);
const selectOverflow = ref(["long", "beijing", "shanghai"]);
const cascaderOverflow = ref(["long", "beijing", "shanghai"]);
const selectedOptions = [
  ...options,
  {
    value: "long",
    label:
      "A very long selected option label for overflow comparison — full text preview keeps the selected value unchanged.",
  },
];
const selectedCascaderOptions = [
  { value: "china", label: "China", children: selectedOptions },
];
function resetSelections() {
  inputValue.value = "Beijing";
  selectValue.value = "beijing";
  cascaderValue.value = "beijing";
  selectMultiple.value = ["beijing", "shanghai"];
  cascaderMultiple.value = ["beijing", "shanghai"];
  selectOverflow.value = ["long", "beijing", "shanghai"];
  cascaderOverflow.value = ["long", "beijing", "shanghai"];
}
</script>
<template>
  <section
    aria-label="Form control size comparison"
    class="control-size-comparison"
  >
    <c-space wrap :size="12">
      <c-radio-group v-model="size" aria-label="Comparison size">
        <c-radio v-for="item in sizes" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
      <c-radio-group v-model="variant" aria-label="Comparison variant">
        <c-radio v-for="item in variants" :key="item" :value="item">{{
          item
        }}</c-radio>
      </c-radio-group>
    </c-space>
    <div class="control-size-comparison__grid">
      <div data-control="Input">
        <p>Input</p>
        <c-input :size="size" :variant="variant" placeholder="Input" />
      </div>
      <div data-control="Button">
        <p>Button</p>
        <c-button :size="size" variant="outline">Button</c-button>
      </div>
      <div data-control="Select">
        <p>Select</p>
        <c-select
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="Select"
        />
      </div>
      <div data-control="Date">
        <p>Date</p>
        <c-date :size="size" :variant="variant" placeholder="Date" />
      </div>
      <div data-control="Time">
        <p>Time</p>
        <c-time :size="size" :variant="variant" placeholder="Time" />
      </div>
      <div data-control="InputNumber">
        <p>InputNumber</p>
        <c-input-number :size="size" :variant="variant" placeholder="Number" />
      </div>
      <div data-control="AutoComplete">
        <p>AutoComplete</p>
        <c-auto-complete
          :size="size"
          :variant="variant"
          :options="options"
          placeholder="AutoComplete"
        />
      </div>
      <div data-control="Cascader">
        <p>Cascader</p>
        <c-cascader
          :size="size"
          :variant="variant"
          :options="cascaderOptions"
          placeholder="Cascader"
        />
      </div>
      <div data-control="DateRange">
        <p>DateRange</p>
        <c-date-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
      <div data-control="TimeRange">
        <p>TimeRange</p>
        <c-time-range
          :size="size"
          :variant="variant"
          :placeholder="['Start', 'End']"
        />
      </div>
    </div>

    <section
      aria-label="Selected control size comparison"
      class="control-size-comparison__states"
    >
      <c-space wrap align="center" :size="12">
        <span>Selected / Clearable / Multiple — 有值、可清空与多选不换行</span>
        <span
          >Hover or focus truncated text; tap on touch screens /
          悬停或聚焦省略正文查看全文；触屏点按查看，点外部关闭</span
        >
        <c-button size="sm" variant="outline" @click="resetSelections"
          >Reset / 恢复选中值</c-button
        >
      </c-space>
      <div class="control-size-comparison__grid">
        <div data-control="InputValue">
          <p>Input · clearable</p>
          <c-input
            v-model="inputValue"
            :size="size"
            :variant="variant"
            clearable
            placeholder="Input value"
          />
        </div>
        <div data-control="ButtonReference">
          <p>Button · reference</p>
          <c-button :size="size" variant="outline">Button</c-button>
        </div>
        <div data-control="SelectValue">
          <p>Select · clearable</p>
          <c-select
            v-model="selectValue"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            clearable
            placeholder="Select value"
          />
        </div>
        <div data-control="CascaderValue">
          <p>Cascader · clearable</p>
          <c-cascader
            v-model="cascaderValue"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            clearable
            placeholder="Cascader value"
          />
        </div>
        <div data-control="SelectMultiple">
          <p>Select · multiple / nowrap</p>
          <c-select
            v-model="selectMultiple"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select multiple"
          />
        </div>
        <div data-control="CascaderMultiple">
          <p>Cascader · multiple / nowrap</p>
          <c-cascader
            v-model="cascaderMultiple"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader multiple"
          />
        </div>
        <div data-control="SelectOverflow">
          <p>Select · long values / nowrap</p>
          <c-select
            v-model="selectOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Select long values"
          />
        </div>
        <div data-control="CascaderOverflow">
          <p>Cascader · long values / nowrap</p>
          <c-cascader
            v-model="cascaderOverflow"
            edit-mode="direct"
            :size="size"
            :variant="variant"
            :options="selectedCascaderOptions"
            multiple
            tag-nowrap
            clearable
            placeholder="Cascader long values"
          />
        </div>
      </div>
    </section>
  </section>
</template>
<style scoped>
.control-size-comparison,
.control-size-comparison__states {
  display: grid;
  gap: 24px;
}
.control-size-comparison__grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  align-items: start;
  gap: 24px 16px;
}
.control-size-comparison__grid > div {
  min-width: 0;
}
.control-size-comparison__grid p {
  margin: 0 0 12px;
  font-size: 14px;
  line-height: 20px;
}
.control-size-comparison__grid :deep(.c-input-number),
.control-size-comparison__grid :deep(.c-auto-complete) {
  width: 100%;
}
</style>
```

### Field Appearance

- `format`: Controls the displayed format.
- `variant`: Input variant

Example source: src/time/__demos__/field-appearance.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:00");
const hint = ref(true);
const error = ref(false);
const line = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="hint"> 浮动提示</c-checkbox>
    <c-checkbox v-model="error"> 显式错误状态</c-checkbox>
    <c-checkbox v-model="line"> 边框 / 底线</c-checkbox>
    <c-time
      v-model="value"
      format="HH:mm"
      variant="outline"
      placeholder="请选择时间"
      :hint="hint"
      :error="error"
      :line="line"
      focus-color="#6750a4"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### Time formats and 12-hour clocks

Compare minute, second and 12-hour displays. Distinguish midnight (12 AM) from noon (12 PM); model formats and step constraints remain separate.

Example source: src/time/__demos__/format-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const value = ref('09:30')

const valueSeconds = ref('09:30:20')

const literalValue = ref('Time 09:30')
return { value, valueSeconds, literalValue }
})())

const scene2 = demoProxyRefs((() => {

const value = ref('12:00:00 am')

const noon = ref('12:00:00 pm')
return { value, noon }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="format">
    <h4><span lang="zh-CN">显示格式</span><span lang="en-US">format</span></h4>
    <c-space direction="column" fill>
        <c-time v-model="scene1.value" format="HH:mm" style="width: 100%; max-width: 320px" />
        <c-time v-model="scene1.valueSeconds" format="HH:mm:ss" style="width: 100%; max-width: 320px" />
        <c-time v-model="scene1.literalValue" format="[Time] HH:mm" style="width: 100%; max-width: 320px" />
      </c-space>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="ampm">
    <h4><span lang="zh-CN">十二小时制</span><span lang="en-US">ampm</span></h4>
    <c-space direction="column" :size="12" style="width: 100%">
        <p>12 AM 是午夜，12 PM 是中午。字段与面板联动展示。</p>
        <c-time v-model="scene2.value" use12-hours  style="width: 100%; max-width: 360px" />
        <c-time v-model="scene2.noon" use12-hours style="width: 100%; max-width: 360px" />
        <c-time-picker v-model="scene2.noon" use12-hours />
        <span>当前值: {{ scene2.value }}</span>
      </c-space>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Value model and selection rules

### Format Model

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                  | Related examples           |
| ----------------- | ------------------------ | -------------------------- |
| `format`          | Display format           | Format Model, Step, Bounds |
| `model-value`     | Bound value              | Step                       |
| `use12-hours`     | 12-hour clock            | Step                       |
| `step`            | Hour/minute/second steps | Step                       |
| `disable-confirm` | No Confirm               | No Confirm                 |

<!-- demo-config-notes:end -->

- `format`: Controls the displayed format.

Example source: src/time/__demos__/format-model.vue

```vue
<script setup>
import { ref } from 'vue'

const date = new Date(2026, 8, 23, 13, 5, 9)
const timestamp = ref(date.getTime())
const value = ref(date)
const literal = ref('Time 09:30')
</script>

<template>
  <c-space direction="column" fill style="width: 100%">
    <p>Date 和时间戳按本地时间反显；选择后返回格式化字符串。</p>
    <c-time v-model="value" format="hh:mm A" style="width: 100%; max-width: 360px" />
    <span>当前模型: {{ value }}</span>
    <c-time v-model="timestamp" format="HH:mm:ss" style="width: 100%; max-width: 360px" />
    <span>时间戳模型: {{ timestamp }}</span>
    <c-time v-model="literal" format="[Time] HH:mm" style="width: 100%; max-width: 360px" />
    <span>固定文字格式: {{ literal }}</span>
  </c-space>
</template>
```

### Step

- `format`: Controls the displayed format.
- `step`: Controls the allowed increment.

Example source: src/time/__demos__/step.vue

```vue
<script setup>
import { computed, ref } from "vue";
const value = ref("09:30:00");
const coarse = ref(false);
const fiveHours = ref(false);
const blockAfternoon = ref(false);
const accept = ref(true);
const proposals = ref(0);
const disabledHours = () => (blockAfternoon.value ? [15] : []);
function update(next) {
  proposals.value++;
  if (accept.value) value.value = next;
}
const step = computed(() => ({
  hour: fiveHours.value ? 5 : 1,
  minute: coarse.value ? 30 : 15,
  second: 10,
}));
</script>

<template>
  <c-space
    class="time-step-demo"
    direction="column"
    :size="12"
    style="width: 100%"
  >
    <c-checkbox v-model="fiveHours"> 十二小时显示 + 5 小时步长</c-checkbox>
    <c-checkbox v-model="coarse"> 切换为 30 分钟步长</c-checkbox>
    <c-checkbox v-model="blockAfternoon"> 禁用 15 点（03 PM）</c-checkbox>
    <c-checkbox v-model="accept"> 父级接受更新</c-checkbox>
    <p>确认时按当前步长重新校验；切换规则不会自动修改已提交值。</p>
    <c-time
      :model-value="value"
      format="HH:mm:ss"
      :use12-hours="fiveHours"
      :step="step"
      :disabled-hours="disabledHours"
      style="width: 100%; max-width: 360px"
      @update:model-value="update"
    />
    <span>{{ value }}</span>
    <span role="status">提议次数：{{ proposals }}</span>
  </c-space>
</template>
```

### Bounds

- `format`: Controls the displayed format.
- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/time/__demos__/bounds.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("10:30:38");
const narrow = ref(false);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <p>
      包含边界：10:30:38–10:31:02。收紧边界不会改写已有模型，但越界值无法确认。
    </p>
    <c-checkbox v-model="narrow"> 将下限调整为 10:30:40</c-checkbox>
    <c-time
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <c-time-picker
      v-model="value"
      format="HH:mm:ss"
      :min="narrow ? '10:30:40' : '10:30:38'"
      max="10:31:02"
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### No Confirm

Example source: src/time/__demos__/no-confirm.vue

```vue
<template>
  <c-time v-model="value" style="width: 200px" disable-confirm />
</template>

<script setup>
import { ref } from 'vue'

const value = ref()
</script>
```

## Input and state control

### Interaction state comparison

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration    | Purpose                     | Related examples                                                |
| ---------------- | --------------------------- | --------------------------------------------------------------- |
| `format`         | Display format              | Interaction state comparison, Text Entry, Default State         |
| `readonly`       | Read-only interaction       | Interaction state comparison, Selection Events, Multiple Fields |
| `clearable`      | Show the clear action       | Text Entry, Default State, Selection Events                     |
| `disabled`       | Disable interaction         | Interaction state comparison, Selection Events                  |
| `input-editable` | Allow desktop text input    | Text Entry, Copying and editing                                 |
| `open`           | Controlled popup visibility | Default State                                                   |

<!-- demo-config-notes:end -->

Toggle the state, interact with the component, and restore editing using the controls outside the specimen. Error appearance alone does not run validation.

Example source: src/time/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("09:30");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-time v-model="value" format="HH:mm" v-bind="__demoState"></c-time>
  </c-space>
</template>
```

### Text Entry

- `format`: Controls the displayed format.
- `min`: Sets the lower bound.
- `max`: Sets the upper bound.

Example source: src/time/__demos__/text-entry.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:00");
const editable = ref(true);
</script>

<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="editable"> 允许手输</c-checkbox>
    <p>回车或失焦提交，Esc 撤销。合法范围为 08:00–18:00。</p>
    <c-time
      v-model="value"
      :input-editable="editable"
      format="HH:mm"
      min="08:00"
      max="18:00"
      clearable
    />
    <span>{{ value }}</span>
  </c-space>
</template>
```

### Default State

- `format`: Controls the displayed format.

Example source: src/time/__demos__/default-state.vue

```vue
<script setup>
import { ref } from "vue";
const value = ref("09:00");
const open = ref(false);
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <p>非受控初始值，无需绑定 v-model</p>
    <c-time :default-value="'09:00'" format="HH:mm" clearable />
    <p>受控值与展开状态</p>
    <c-time v-model="value" v-model:open="open" format="HH:mm" clearable />
    <span>{{ value }} / {{ open }}</span>
  </c-space>
</template>
```

### Selection Events

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.
- `format`: Controls the displayed format.

Example source: src/time/__demos__/selection-events.vue

```vue
<script setup>
import { ref } from "vue";

const value = ref("09:00");
const immediate = ref(false);
const readonly = ref(false);
const disabled = ref(false);
const events = ref([]);
function record(name, value, dates) {
  const times = Array.isArray(dates)
    ? dates.map((date) => date?.toLocaleTimeString())
    : dates?.toLocaleTimeString();
  events.value = [
    JSON.stringify({ event: name, value: value ?? null, time: times ?? null }),
    ...events.value,
  ].slice(0, 5);
}
</script>

<template>
  <c-space direction="column" size="12px" style="width: 100%">
    <c-checkbox v-model="readonly"> 只读：可聚焦，不可修改</c-checkbox>
    <c-checkbox v-model="disabled"> 禁用：释放焦点，不可修改</c-checkbox>
    <c-checkbox v-model="immediate"> 选择后立即提交</c-checkbox>
    <p>select 记录草稿，change 记录提交；取消不改模型，清除返回 undefined。</p>
    <c-time
      v-model="value"
      :disable-confirm="immediate"
      :readonly="readonly"
      :disabled="disabled"
      format="HH:mm"
      clearable
      @select="(value, dates) => record('select', value, dates)"
      @change="(value, dates) => record('change', value, dates)"
      @clear="record('clear')"
      @click="record('click')"
      @open-change="(open) => record('open-change', open)"
      @focus="record('focus')"
      @blur="record('blur')"
    />
    <span>模型: {{ value === undefined ? "undefined" : value }}</span>
    <c-button variant="outline" @click="value = '15:30'"
      >从外部替换模型</c-button
    >
    <small>外部替换会更新反显，不触发 select 或 change。</small>
    <div
      v-for="(event, index) in events"
      :key="index"
      style="overflow-wrap: anywhere"
    >
      {{ event }}
    </div>
  </c-space>
</template>
```

### Multiple Fields

- `readonly`: Displays the current value without allowing edits.
- `format`: Controls the displayed format.

Example source: src/time/__demos__/multiple-fields.vue

```vue
<script setup>
import { ref } from "vue";
const lastEvent = ref("—");
const readonly = ref(false);
const start = ref("09:00:00");
const end = ref("18:00:00");
const range = ref(["09:00:00", "18:00:00"]);
</script>
<template>
  <c-space direction="column" :size="12" style="width: 100%">
    <c-checkbox v-model="readonly">
      只读字段仍可聚焦，但不能展开修改</c-checkbox
    >
    <c-input placeholder="在这里按 Enter，不会打开时间面板" />
    <small aria-live="polite">{{ lastEvent }}</small>
    <div aria-live="polite">
      <div>开始模型: {{ start ?? "undefined" }}</div>
      <div>结束模型: {{ end ?? "undefined" }}</div>
      <div>范围模型: {{ range ?? "undefined" }}</div>
    </div>
    <p>依次点击各个字段，之前的面板会关闭，不提交未确认草稿。</p>
    <c-time
      v-model="start"
      :readonly="readonly"
      @focus="lastEvent = 'start: focus'"
      @blur="lastEvent = 'start: blur'"
      format="HH:mm:ss"
      placeholder="开始时间"
      style="width: 100%; max-width: 360px"
    />
    <c-time
      v-model="end"
      :readonly="readonly"
      @focus="lastEvent = 'end: focus'"
      @blur="lastEvent = 'end: blur'"
      format="HH:mm:ss"
      placeholder="结束时间"
      style="width: 100%; max-width: 360px"
    />
    <c-time-range
      v-model="range"
      :readonly="readonly"
      @focus="lastEvent = 'range: focus'"
      @blur="lastEvent = 'range: blur'"
      format="HH:mm:ss"
      style="width: 100%; max-width: 360px"
    />
  </c-space>
</template>
```

### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/time/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-time
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :input-editable="editable"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("09:30:00");
</script>
```

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## Reading direction

Inherits the nearest `dir="ltr|rtl"`. Direction changes neither change the time nor commit drafts. Time columns follow reading order; Left/Right moves focus visually between columns. Cedar Up/Down and Home/End move focus within a column, skipping disabled options; Enter/Space selects. Maple wheels retain their existing Up/Down and Home/End selection behavior. Existing confirmation settings control submission. Popovers inherit their source direction.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Popup configuration and field notifications

`popup-props` configures local Trigger positioning/appearance, e.g. `{ placement: 'top-start' }`, without overriding field state/interaction such as open, disabled or trigger. Top-level `popup-container`, including false, takes precedence. `input-editable` defaults to true and can disable desktop typing. `time-picker-props`, including class/style, controls panel appearance. Undeclared attrs no longer supply panel/popup configuration; id/aria-* fall through to the field.

`click(event)` notifies only clicks on non-disabled fields. Readonly may notify without expanding. Closing consistently listens to `open-change(false)`, a close request that controlled open still requires the parent to accept. Neither platform has a field close event; a close request is not a value commit.

The field icon slot is `suffix-icon` with `focus: boolean` and `popupOpen: boolean`. `focus(index = 0)` focuses an endpoint without committing; `blur()` removes focus and requests closing.

### Props

| Arguments               | Description                                                                                                                      | Type                                                | Default   |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | --------- |
| `open-trigger-target`   | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                                 | `'field'` |
| `model-value`           | Bound value                                                                                                                      | `string \| number \| Date`                          | `-`       |
| `open`                  | Controlled popup visibility                                                                                                      | `boolean`                                           | `-`       |
| `popup-props`           | Local Trigger presentation options; do not control field state                                                                   | `TimePopupPresentationProps<Partial<TriggerProps>>` | `{}`      |
| `input-editable`        | Allow desktop text input                                                                                                         | `boolean`                                           | `true`    |
| `clearable`             | Show the clear action                                                                                                            | `boolean`                                           | `true`    |
| `disabled`              | Disable interaction                                                                                                              | `boolean`                                           | `false`   |
| `readonly`              | Read-only interaction                                                                                                            | `boolean`                                           | `false`   |
| `size`                  | Size                                                                                                                             | `xs \| sm \| md \| lg \| xl`                        | `-`       |
| `variant`               | Field appearance                                                                                                                 | `filled \| outline \| standard`                     | `filled`  |
| `placeholder`           | Placeholder                                                                                                                      | `string`                                            | `-`       |
| `format`                | Display format                                                                                                                   | `string`                                            | `-`       |
| `use12-hours`           | 12-hour clock                                                                                                                    | `boolean`                                           | `false`   |
| `hide-disabled-options` | Hide disabled time options                                                                                                       | `boolean`                                           | `false`   |
| `step`                  | Hour/minute/second steps                                                                                                         | `object`                                            | `-`       |
| `disable-confirm`       | Skip confirmation                                                                                                                | `boolean`                                           | `false`   |
| `time-picker-props`     | Forwarded to TimePicker                                                                                                          | `object`                                            | `{}`      |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

Inline date/time fields retain their existing confirmation policy. In click/dblclick editors, internal panels hide confirmation tools, and the edit layer supplies one confirm/cancel pair. Standalone DatePicker, DateRangePicker, TimePicker and TimeRangePicker retain panel APIs/confirmation and do not inherit Form field presentation.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

### Forwarded configuration boundaries (F07)

Existing TimePopupPresentationProps and runtime filtering remain. Fields own open/defaultOpen, disabled, trigger, closeOnClickReference, preventFocus and expansion updates. Explicit top-level popup-container takes precedence, otherwise nested configuration is used. popupClass merges internal classes. Inline popupOffset stays 4; Maple also fixes unmountOnClose=true. Such fields in old types are not guaranteed to control final values. Existing Time types/runtime behavior are not narrowed here.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

`empty-value` accepts explicit `null` (or `() => null`). Clearing publishes `null` unchanged; omitted values preserve the existing default. Editors render `null` as blank without converting ordinary empty-string input to `null`. In popup editing, clearing changes the draft; confirm commits it and cancel preserves the original model.

---

Document: llms/en-US/components/timeline.md

<!-- Source: src/timeline/README.en-US.md; locale: en-US; page: /en/components/timeline/ -->

# Timeline

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `reverse`: Whether reverse order

Example source: src/timeline/__demos__/basic.vue

```vue
<template>
  <div :style="{ marginBottom: '40px' }">
    <c-typography-text :style="{ verticalAlign: 'middle', marginRight: '8px' }"> Reverse </c-typography-text>
    <c-radio-group @change="onChange" :style="{ marginBottom: '30px' }" v-model="isReverse">
      <c-radio :value="false">No Reverse</c-radio>
      <c-radio :value="true">Reverse</c-radio>
    </c-radio-group>
  </div>
  <c-timeline :reverse="isReverse">
    <c-timeline-item label="2017-03-10">The first milestone</c-timeline-item>
    <c-timeline-item label="2018-05-12">The second milestone</c-timeline-item>
    <c-timeline-item label="2020-09-30">The third milestone</c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const isReverse = ref(false)

const onChange = (bool) => {
  isReverse.value = bool
}
</script>
```

## Appearance and states

### Type

Preview configuration: `label="2017-03-10"`, `lineType="dashed"`, `type="secondary"`, `label="2018-05-12"`.

Example source: src/timeline/__demos__/type.vue

```vue
<template>
  <c-timeline>
    <c-timeline-item label="2017-03-10" lineType="dashed">
      The first milestone
      <br />
      <c-typography-text type="secondary" :style="{ fontSize: '12px', marginTop: '4px' }">
        This is a descriptive message
      </c-typography-text>
    </c-timeline-item>
    <c-timeline-item label="2018-05-12" lineType="dashed">
      The second milestone
      <br />
      <c-typography-text type="secondary" :style="{ fontSize: '12px', marginTop: '4px' }">
        This is a descriptive message
      </c-typography-text>
    </c-timeline-item>
    <c-timeline-item label="2020-09-30" lineType="dashed">
      The third milestone
      <br />
      <c-typography-text type="secondary" :style="{ fontSize: '12px', marginTop: '4px' }">
        This is a descriptive message
      </c-typography-text>
    </c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
</script>
```

## Layout and arrangement

### Timeline direction and labels

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `mode` | The display mode of Timeline | Timeline direction and labels |
| `label-position` | Position of label text | Timeline direction and labels |
| `orientation` | Horizontal/vertical axis of the timeline line, default vertical; constrains valid item sides | Timeline direction and labels |
| `pending` | Whether to display ghost nodes. When set to true, only ghost nodes are displayed. When passed to ReactNode, it will be displayed as node content | Timeline direction and labels |
<!-- demo-config-notes:end -->


Compare orientation, sequence and label placement independently of pending states and custom nodes.

Example source: src/timeline/__demos__/layout-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const mode = ref('left')


const onChange = (_mode) => {
  mode.value = _mode
}
return { mode, onChange }
})())

const scene2 = demoProxyRefs((() => {


const mode = ref('top')


const onChange = (_mode) => {
  mode.value = _mode
}
return { mode, onChange }
})())

const scene3 = demoProxyRefs((() => {


const mode = ref('left')

const pos = ref('same')


const onLabelPositionChange = (_pos) => {
  pos.value = _pos
}


const onModeChange = (_mode) => {
  mode.value = _mode
}
return { mode, pos, onLabelPositionChange, onModeChange }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="vertical">
    <h4><span lang="zh-CN">纵向时间轴</span><span lang="en-US">vertical</span></h4>
    <div>
        <c-row align="center" :style="{
      marginBottom: '24px'
    }">
          <c-typography-text>mode: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene1.onChange" :modelValue="scene1.mode">
            <c-radio value="left">left</c-radio>
            <c-radio value="right">right</c-radio>
            <c-radio value="alternate">alternate</c-radio>
          </c-radio-group>
        </c-row>
        <c-timeline :mode="scene1.mode" labelPosition="relative">
          <c-timeline-item label="2012-08">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/b5d834b83708a269b4562924436eac48.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Toutiao
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2012</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2017-05">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Xigua Video
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2017</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2018-07">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Pipidance
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2018</div>
              </div>
            </c-row>
          </c-timeline-item>
        </c-timeline>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="direction">
    <h4><span lang="zh-CN">横向时间轴</span><span lang="en-US">direction</span></h4>
    <div>
        <c-row align="center" :style="{
      marginBottom: '24px'
    }">
          <c-typography-text>mode: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene2.onChange" :modelValue="scene2.mode">
            <c-radio value="top">top</c-radio>
            <c-radio value="bottom">bottom</c-radio>
            <c-radio value="alternate">alternate</c-radio>
          </c-radio-group>
        </c-row>
        <c-timeline orientation="horizontal" pending :mode="scene2.mode">
          <c-timeline-item label="2012-08">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/b5d834b83708a269b4562924436eac48.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Toutiao
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2012</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2017-05">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Xigua Video
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2017</div>
              </div>
            </c-row>
          </c-timeline-item>
          <c-timeline-item label="2018-07">
            <c-row :style="{
      display: 'inline-flex',
      alignItems: 'center'
    }">
              <img
                width="40"
                :style="{
      marginRight: '16px',
      marginBottom: '12px'
    }"
                src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/385ed540c359ec8a9b9ce2b5fe89b098.png~tplv-uwbnlip3yd-png.png"
              />
              <div :style="{
      marginBottom: '12px'
    }">
                Pipidance
                <div :style="{
      fontSize: '12px',
      color: '#4E5969'
    }">Founded in 2018</div>
              </div>
            </c-row>
          </c-timeline-item>
        </c-timeline>
      </div>
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="label">
    <h4><span lang="zh-CN">标签文本位置</span><span lang="en-US">label</span></h4>
    <div>
        <c-row align="center">
          <c-typography-text>labelPosition: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene3.onLabelPositionChange" :modelValue="scene3.pos">
            <c-radio value="same">same</c-radio>
            <c-radio value="relative">relative</c-radio>
          </c-radio-group>
        </c-row>
        <c-row align="center" :style="{
      margin: '20px 0px 24px'
    }">
          <c-typography-text>mode: &nbsp; &nbsp;</c-typography-text>
          <c-radio-group @change="scene3.onModeChange" :modelValue="scene3.mode">
            <c-radio value="left">left</c-radio>
            <c-radio value="right">right</c-radio>
            <c-radio value="alternate">alternate</c-radio>
          </c-radio-group>
        </c-row>
        <c-timeline :mode="scene3.mode" :labelPosition="scene3.pos">
          <c-timeline-item label="2017-03-10" dotColor="#52C419"> The first milestone </c-timeline-item>
          <c-timeline-item label="2018-05-12" dotColor="#F5222D" labelPosition="same"> The second milestone </c-timeline-item>
          <c-timeline-item label="2020-09-30" content-placement="bottom"> The third milestone </c-timeline-item>
        </c-timeline>
      </div>
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Content and presentation

### Pending

Preview configuration: `align="center"`, `:checked="!!pendingProps.orientation"`, `:checked="!!pendingProps.reverse"`, `:checked="!!pendingProps.pending"`.

Example source: src/timeline/__demos__/pending.vue

```vue
<template>
  <c-row align="center" :style="{ marginBottom: '24px' }">
    <c-checkbox :checked="!!pendingProps.orientation" @change="(v) => onChange({ orientation: v ? 'horizontal' : '' })">
      horizontal &nbsp; &nbsp;
    </c-checkbox>
    <c-checkbox :checked="!!pendingProps.reverse" @change="(v) => onChange({ reverse: v })">
      reverse &nbsp; &nbsp;
    </c-checkbox>
    <c-checkbox
      :checked="!!pendingProps.pending"
      @change="(v) => onChange({ pending: v ? 'This is a pending dot' : false })"
    >
      pending &nbsp; &nbsp;
    </c-checkbox>
    <c-checkbox :checked="!!pendingProps.hasPendingDot" @change="(v) => onChange({ hasPendingDot: v })">
      custom pendingDot
    </c-checkbox>
  </c-row>
  <c-timeline v-bind="pendingProps">
    <template v-if="pendingProps.hasPendingDot" #dot>
      <c-icon-fire :style="{ color: '#e70a0a' }" />
    </template>
    <c-timeline-item label="2017-03-10" dotColor="#52C419"> The first milestone </c-timeline-item>
    <c-timeline-item label="2018-05-12" dotColor="#F5222D"> The second milestone </c-timeline-item>
    <c-timeline-item label="2020-09-30">The third milestone</c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const pendingProps = ref({})

const onChange = (newProps) => {
  pendingProps.value = {
    ...pendingProps.value,
    ...newProps,
  }
}
</script>
```

### Mode

- `mode`: The display mode of Timeline

Example source: src/timeline/__demos__/mode.vue

```vue
<template>
  <c-row justify="space-between">
    <c-timeline mode="alternate" :style="{ flex: 1 }">
      <c-timeline-item label="2017-03-10">The first milestone</c-timeline-item>
      <c-timeline-item label="2018-05-12">The second milestone</c-timeline-item>
      <c-timeline-item label="2020-09-30" content-placement="bottom"> The third milestone </c-timeline-item>
    </c-timeline>
    <c-timeline mode="right" :style="{ flex: 1 }">
      <c-timeline-item label="2017-03-10">The first milestone</c-timeline-item>
      <c-timeline-item label="2018-05-12">The second milestone</c-timeline-item>
      <c-timeline-item label="2020-09-30" content-placement="bottom"> The third milestone </c-timeline-item>
    </c-timeline>
  </c-row>
</template>

<script lang="ts" setup>
</script>
```

## Customization and slots

### Icon

Preview configuration: `label="2017-03-10"`, `dotColor="#00B42A"`, `label="2018-05-22"`, `label="2020-06-22"`.

Example source: src/timeline/__demos__/icon.vue

```vue
<template>
  <c-timeline>
    <c-timeline-item label="2017-03-10" dotColor="#00B42A"> The first milestone </c-timeline-item>
    <c-timeline-item label="2018-05-22">The second milestone</c-timeline-item>
    <c-timeline-item label="2020-06-22" dotColor="#F53F3F">
      The third milestone
      <c-icon-exclamation-circle-fill :style="{ color: '#F53F3F', fontSize: '12px', marginLeft: '4px' }" />
    </c-timeline-item>
    <c-timeline-item label="2020-09-30" dotColor="#C9CDD4"> The fourth milestone </c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
</script>
```

### Dot

Preview configuration: `label="2020-04-12"`, `dotColor="#00B42A"`, `label="2020-05-17"`, `label="2020-06-22"`.

Example source: src/timeline/__demos__/dot.vue

```vue
<template>
  <div :style="{ display: 'flex' }">
    <c-timeline :style="{ marginRight: '40px' }">
      <c-timeline-item label="2020-04-12" dotColor="#00B42A"> The first milestone </c-timeline-item>
      <c-timeline-item label="2020-05-17"> The second milestone </c-timeline-item>
      <c-timeline-item label="2020-06-22">
        <template #dot>
          <c-icon-clock-circle :style="{ fontSize: '12px', color: '#F53F3F' }" />
        </template>
        The third milestone
      </c-timeline-item>
      <c-timeline-item label="2020-06-22" dotColor="var(--color-fill-4)"> The third milestone </c-timeline-item>
    </c-timeline>

    <c-timeline :style="{ marginRight: '40px' }">
      <c-timeline-item label="2020-04-12">
        <template #dot>
          <c-icon-check
            :style="{
              fontSize: '12px',
              padding: '2px',
              boxSizing: 'border-box',
              borderRadius: '50%',
              backgroundColor: 'var(--color-primary-light-1)',
            }"
          />
        </template>
        The first milestone
      </c-timeline-item>
      <c-timeline-item label="2020-05-17">
        <template #dot>
          <c-icon-check
            :style="{
              fontSize: '12px',
              padding: '2px',
              boxSizing: 'border-box',
              borderRadius: '50%',
              backgroundColor: 'var(--color-primary-light-1)',
            }"
          />
        </template>
      </c-timeline-item>
      <c-timeline-item label="2020-06-22">The third milestone</c-timeline-item>
      <c-timeline-item label="2020-06-22" dotColor="var(--color-fill-4)"> The third milestone </c-timeline-item>
    </c-timeline>

    <c-timeline>
      <c-timeline-item label="2020-04-12">The first milestone</c-timeline-item>
      <c-timeline-item label="2020-05-17" dotColor="var(--color-fill-4)"> The second milestone </c-timeline-item>
      <c-timeline-item label="2020-06-22" dotColor="var(--color-fill-4)"> The third milestone </c-timeline-item>
    </c-timeline>
  </div>
</template>

<script lang="ts" setup>
</script>
```

### Custom

Example source: src/timeline/__demos__/custom.vue

```vue
<template>
  <c-timeline>
    <c-timeline-item>
      Code Review
      <template #label>
        <c-tag>
          <template #icon>
            <c-icon-check-circle-fill />
          </template>
          Passed
        </c-tag>
      </template>
    </c-timeline-item>
  </c-timeline>
</template>

<script lang="ts" setup>
</script>
```

## API

### `<timeline>` Props

| Parameter | Description | Type | Default |
| -------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------- | :----------: |
| reverse | Whether reverse order | `boolean` | `false` |
| orientation | Horizontal/vertical axis of the timeline line, default vertical; constrains valid item sides | `'horizontal' \| 'vertical'` | `'vertical'` |
| mode | The display mode of Timeline | `'left' \| 'right' \| 'top' \| 'bottom' \| 'alternate'` | `'left'` |
| pending | Whether to display ghost nodes. When set to true, only ghost nodes are displayed. When passed to ReactNode, it will be displayed as node content | `boolean\|string` | `-` |
| label-position | Position of label text | `'relative' \| 'same'` | `'same'` |

### `<timeline>` Slots

| Slot | Description | Arguments |
| ------ | :------: | ---- |
| dot | Ghost node | - |

### `<timeline-item>` Props

| Parameter | Description | Type | Default |
| ---------- | ---------------------------- | --------------------------------- | :-------: |
| dot-color | Node color | `string` | `-` |
| dot-type | Node type: outlined/filled circle | `'hollow' \| 'solid'` | `'solid'` |
| line-type | Timeline line style: solid/dashed/dotted | `'solid' \| 'dashed' \| 'dotted'` | `'solid'` |
| line-color | Timeline color | `string` | `-` |
| label | Label text | `string` | `-` |
| content-placement | Current per-item side relative to the timeline in alternate mode: left/right for vertical and top/bottom for horizontal. Constrained by mode and orientation | `TimelineItemContentPlacement` | `-` |

### `<timeline-item>` Slots

| Slot | Description | Arguments | Version |
| ------ | :--------: | ---- | :----- |
| dot | Custom node | - |  |
| label | Custom label | - | 2.50.0 |

### Type definitions

The component exports the following types

```ts
import type { MentionInstance } from '@cedar-design/ui'
```


## Reading direction and keyboard interaction

Horizontal timelines follow the inherited reading direction, including connecting lines. `reverse` independently controls visual reversal; switching direction does not reorder the data. Explicit vertical `left`/`right` sides retain their physical meaning.

---

Document: llms/en-US/components/tooltip.md

<!-- Source: src/tooltip/README.en-US.md; locale: en-US; page: /en/components/tooltip/ -->

# Tooltip

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `content="This is tooltip content"`, `content="This is a two-line tooltip content.This is a two-line tooltip content."`.

Example source: src/tooltip/__demos__/basic.vue

```vue
<template>
  <c-space wrap>
    <c-tooltip content="This is tooltip content">
      <c-button>Mouse over to display tooltip</c-button>
    </c-tooltip>
    <c-tooltip content="This is a two-line tooltip content.This is a two-line tooltip content.">
      <c-button>Mouse over to display tooltip</c-button>
    </c-tooltip>
  </c-space>
</template>
<script lang="ts" setup>
</script>
```

## Appearance and states

### Status

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Hint content | Status, Appearance configuration comparison |
| `color` | Background color | Status, Appearance configuration comparison |
| `status` | Panel intent | Status |
<!-- demo-config-notes:end -->


- `status`: Selects the semantic state.
- `color`: Overrides the color.

Example source: src/tooltip/__demos__/status.vue

```vue
<template>
  <c-space wrap>
    <c-tooltip v-for="status in statuses" :key="status" :status="status" :content="status">
      <c-button :status="status === 'default' ? undefined : status">{{ status }}</c-button>
    </c-tooltip>
  </c-space>
</template>

<script setup lang="ts">
import type { TooltipStatus } from '../props'

const statuses: TooltipStatus[] = ['default', 'primary', 'info', 'success', 'warning', 'danger']
</script>
```

Example source: src/tooltip/__demos__/color.vue

```vue
<template>
  <c-space wrap>
    <c-tooltip content="This is tooltip content" color="#3491FA">
      <c-button>#3491FA</c-button>
    </c-tooltip>
    <c-tooltip content="This is tooltip content" color="#165DFF">
      <c-button>#165DFF</c-button>
    </c-tooltip>
    <c-tooltip content="This is tooltip content" color="#722ED1">
      <c-button>#722ED1</c-button>
    </c-tooltip>
  </c-space>
</template>
<script lang="ts" setup>
</script>
```

### Appearance configuration comparison

Choose an axis to compare its available values with the same content and model. Other settings remain unchanged while comparing.

Example source: src/tooltip/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";

const __demoAppearance = __demoReactive({ status: "default", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"status","values":["default","primary","info","success","warning","danger"]},{"name":"size","values":["xs","md"]}]
const demoCompareAxis = demoRef("status")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="status">
        <c-select
          v-model="__demoAppearance['status']"
          :clearable="false"
          :options="[
            { label: 'default', value: 'default' },
            { label: 'primary', value: 'primary' },
            { label: 'info', value: 'info' },
            { label: 'success', value: 'success' },
            { label: 'warning', value: 'warning' },
            { label: 'danger', value: 'danger' },
          ]"
          aria-label="status"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'md', value: 'md' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-tooltip
      content="This is tooltip content"
      color="#3491FA"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    >
      <c-button>#3491FA</c-button>
    </c-tooltip>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

## Layout and arrangement

### Placement

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | Hint content | Placement |
| `placement` | Preferred popup side relative to the trigger, default top. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Placement |
<!-- demo-config-notes:end -->


- `placement`: Chooses the position relative to the trigger.

Example source: src/tooltip/__demos__/placement.vue

```vue
<template>
  <div :style="{ position: 'relative', width: '440px', height: '280px' }">
    <c-tooltip content="This is a Tooltip" placement="top-start">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '70px' }">TL</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="top">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '180px' }">TOP</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="top-end">
      <c-button class="button" :style="{ position: 'absolute', top: '0', left: '290px' }">TR</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="bottom-start">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '70px' }">BL</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="bottom">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '180px' }">BOTTOM</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="bottom-end">
      <c-button class="button" :style="{ position: 'absolute', top: '240px', left: '290px' }">BR</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="left-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '10px' }">LT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="left">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '10px' }">LEFT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="left-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '10px' }">LB</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="right-start">
      <c-button class="button" :style="{ position: 'absolute', top: '60px', left: '350px' }">RT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="right">
      <c-button class="button" :style="{ position: 'absolute', top: '120px', left: '350px' }">RIGHT</c-button>
    </c-tooltip>
    <c-tooltip content="This is a Tooltip" placement="right-end">
      <c-button class="button" :style="{ position: 'absolute', top: '180px', left: '350px' }">RB</c-button>
    </c-tooltip>
  </div>
</template>
<script lang="ts" setup>
</script>
<style scoped>
.button {
  width: 100px;
}
</style>
```

## Content and presentation

### Directive

Example source: src/tooltip/__demos__/directive.vue

```vue
<template>
  <div :style="{ position: 'relative', width: '440px', height: '280px' }">
    <c-button v-tooltip:top-start="'This is a Tooltip'" :style="{ position: 'absolute', top: '0', left: '70px' }" class="button"
      >TL
    </c-button>
    <c-button
      v-tooltip:top="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '0', left: '180px' }"
      class="button"
      >TOP
    </c-button>
    <c-button v-tooltip:top-end="'This is a Tooltip'" :style="{ position: 'absolute', top: '0', left: '290px' }" class="button"
      >TR
    </c-button>
    <c-button
      v-tooltip:bottom-start="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '240px', left: '70px' }"
      class="button"
      >BL
    </c-button>
    <c-button
      v-tooltip:bottom="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '240px', left: '180px' }"
      class="button"
      >BOTTOM
    </c-button>
    <c-button
      v-tooltip:bottom-end="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '240px', left: '290px' }"
      class="button"
      >BR
    </c-button>
    <c-button
      v-tooltip:left-start="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '60px', left: '10px' }"
      class="button"
      >LT
    </c-button>
    <c-button
      v-tooltip:left="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '120px', left: '10px' }"
      class="button"
      >LEFT
    </c-button>
    <c-button
      v-tooltip:left-end="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '180px', left: '10px' }"
      class="button"
      >LB
    </c-button>
    <c-button
      v-tooltip:right-start="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '60px', left: '350px' }"
      class="button"
      >RT
    </c-button>
    <c-button
      v-tooltip:right="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '120px', left: '350px' }"
      class="button"
      >RIGHT
    </c-button>
    <c-button
      v-tooltip:right-end="'This is a Tooltip'"
      :style="{ position: 'absolute', top: '180px', left: '350px' }"
      class="button"
      >RB
    </c-button>
  </div>
</template>
<script lang="ts" setup>
</script>

<style scoped>
.button {
  width: 100px;
}
</style>
```

Example source: src/tooltip/__demos__/text-ellipsis.vue

```vue
<template>
  <c-space wrap class="Home">
    <div v-tooltip:ellipsis class="text-container">
      相见时难别亦难，东风无力百花残。 春蚕到死丝方尽，蜡炬成灰泪始干。 晓镜但愁云鬓改，夜吟应觉月光寒。
      蓬山此去无多路，青鸟殷勤为探看。
    </div>
    <div v-tooltip:ellipsis class="text-container">没溢出</div>
  </c-space>
</template>
<style scoped>
.text-container {
  width: 100px;
}
</style>
```

## API

Tooltip inherits Trigger positioning, containers, controlled state, closing policies and public methods.

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| content | Hint content | `string` | — |
| status | Panel intent | `default \| primary \| info \| success \| warning \| danger` | `default` |
| size | Implemented sizes | `xs \| md` | `md` |
| color | Background color | `string` | — |
| text-color | Custom text color | `string` | — |
| trigger | Interaction | `TriggerEvent \| TriggerEvent[]` | `['hover', 'focus']` |
| placement | Preferred popup side relative to the trigger, default top. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `TriggerPlacement` | `top` |
| show-arrow | Show the arrow | `boolean` | `true` |
| popup-offset | Main-axis distance | `number` | `10` |
| unmount-on-close | Unmount after close | `boolean` | `true` |

Events: `update:open`, `open-change`, `open`, `opened`, `close`, `closed`, `click-outside`. Slots: `default`, `content`. Exposes `open`, `close`, `resize`, `allowClose`, `getReference`, `setReference` and `focusReference`.

Content has `role="tooltip"`. Opening adds its ID to the actual trigger's `aria-describedby`; closing, changing external reference or unmounting removes it.

## Shared-source contract

Cedar/Maple independently maintain matching bodies, props, appearance mappings and structural styles. Only prefixes, local imports and theme-token values differ. No `backgroundColor` or boolean `xs` compatibility entry exists.

## Public CSS variables

These are actual :root defaults. Prefer component variables for business customization; internal positioning variables are not public API.

| Variable | Default | Meaning and use case |
| --- | --- | --- |
| `--c-tooltip-background` | `var(--c-sys-color-surface-tooltip)` | Content and arrow background |
| `--c-tooltip-text-color` | `var(--c-sys-color-content-on-dark)` | Body foreground |
| `--c-tooltip-status-primary-background` | `var(--c-sys-color-action-primary)` | Primary content/arrow background |
| `--c-tooltip-status-info-background` | `var(--c-sys-color-status-info)` | Info content/arrow background |
| `--c-tooltip-status-success-background` | `var(--c-sys-color-status-success)` | Success content/arrow background |
| `--c-tooltip-status-warning-background` | `var(--c-sys-color-status-warning)` | Warning content/arrow background |
| `--c-tooltip-status-danger-background` | `var(--c-sys-color-status-danger)` | Danger content/arrow background |
| `--c-tooltip-status-primary-text-color` | `var(--c-sys-color-content-on-dark)` | Primary text; set together with its background |
| `--c-tooltip-status-info-text-color` | `var(--c-sys-color-content-on-dark)` | Info text; set together with its background |
| `--c-tooltip-status-success-text-color` | `var(--c-sys-color-content-on-dark)` | Success text; set together with its background |
| `--c-tooltip-status-warning-text-color` | `var(--c-sys-color-content-on-dark)` | Warning text; set together with its background |
| `--c-tooltip-status-danger-text-color` | `var(--c-sys-color-content-on-dark)` | Danger text; set together with its background |
| `--c-tooltip-padding-horizontal` | `var(--c-sys-space-6)` | Horizontal content padding |
| `--c-tooltip-padding-vertical` | `var(--c-sys-space-4)` | Vertical content padding |
| `--c-tooltip-font-size` | `var(--c-sys-font-size-md)` | Content font size |
| `--c-tooltip-line-height` | `var(--c-line-height)` | Content line height |
| `--c-tooltip-border-radius` | `var(--c-sys-radius-md)` | Content border radius |
| `--c-tooltip-max-width` | `350px` | Maximum tooltip-content width |
| `--c-tooltip-opacity` | `1` | Content/arrow opacity; changes require contrast checks |
| `--c-tooltip-size-xs-padding-horizontal` | `var(--c-sys-space-4)` | xs horizontal content padding |
| `--c-tooltip-size-xs-padding-vertical` | `var(--c-sys-space-2)` | xs vertical content padding |
| `--c-tooltip-size-xs-font-size` | `var(--c-sys-font-size-xs)` | xs content font size |
| `--c-tooltip-animation-duration` | `var(--c-sys-motion-duration-standard)` | Enter/leave duration; reduced motion may override it |

All built-in themes use opacity 1. Colored solid text follows Button on-dark in both light/dark modes. Maple dark mode retains 4px radius, 14px font and 8px/16px vertical/horizontal padding. Neutral surfaces remain dark in both modes. `color` sets content/arrow backgrounds; `text-color` sets text. Explicit content-style/arrow-style override their respective nodes. Recheck custom colors/opacity.

With Teleport, variables must be in the actual popup scope, for example through `popup-style`. Trigger-button variables do not automatically inherit into popups.

---

Document: llms/en-US/components/transfer.md

<!-- Source: src/transfer/README.en-US.md; locale: en-US; page: /en/components/transfer/ -->

# Transfer

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `data`: Data of the transfer
- `default-value`: The default value in the target selection box (uncontrolled state)

Example source: src/transfer/__demos__/basic.vue

```vue
<template>
  <c-transfer :data="data" :default-value="value" />
</template>

<script lang="ts" setup>
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: `Option ${index + 1}`,
  }))
const value = [{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }]
</script>
```

## Search and data structures

### Search

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration               | Purpose                                 | Related examples      |
| --------------------------- | --------------------------------------- | --------------------- |
| `data`                      | Data of the transfer                    | Search, Grouped, Tree |
| `source-filterable`         | Show the source search input            | Search, Grouped       |
| `default-value`             | Complete uncontrolled target-side state | Search, Tree          |
| `source-filter-placeholder` | Source search placeholder               | Search, Grouped       |
| `target-filterable`         | Show the target search input            | Search                |
| `target-filter-placeholder` | Target search placeholder               | Search                |

<!-- demo-config-notes:end -->

- `data`: Data of the transfer
- `default-value`: The default value in the target selection box (uncontrolled state)

Dragging a filtered target list reorders only visible positions in the complete target sequence. Hidden required items, selections absent from the current candidate page, and their metadata are retained.

Example source: src/transfer/__demos__/search.vue

```vue
<template>
  <c-transfer
    source-filterable
    target-filterable
    :data="data"
    v-model="value"
    target-draggable
    source-filter-placeholder="搜索待选项"
    target-filter-placeholder="搜索已选项"
  />
  <p role="status">当前顺序：{{ value.map(item => item.value).join(' → ') }}</p>
  <p>在已选项搜索 Option 后拖拽，隐藏的必选字段仍保留在完整列表中。</p>
</template>

<script lang="ts" setup>
import { ref } from 'vue'
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: index === 2 ? '必选字段' : `Option ${index + 1}`,
    required: index === 2,
  }))
const value = ref([{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }])
</script>
```

### Grouped

- `data`: Data of the transfer

Example source: src/transfer/__demos__/grouped.vue

```vue
<template>
  <div style="height: 520px">
    <c-transfer
      v-model="value"
      :data="data"
      :target-actions="targetActions"
      source-filterable
      target-draggable
      target-operation="menu"
      source-filter-placeholder="请输入关键词搜索"
      @target-action="handleTargetAction"
    />
  </div>
  <c-dialog v-model:open="customVisible" title="自定义操作" :width="420"> 当前操作项：{{ activeLabel }} </c-dialog>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const data = [
  { value: 'gunId', label: '枪ID', group: '基本信息', disabled: true, tip: '系统必选字段' },
  { value: 'gunName', label: '枪名称', group: '基本信息' },
  { value: 'company', label: '区域公司区域公司区域公司', group: '基本信息', tip: '所属区域公司' },
  { value: 'deviceId', label: '设备ID', group: '设备信息' },
  { value: 'deviceName', label: '设备名称', group: '设备信息' },
  { value: 'lock', label: '地锁', group: '设备信息' },
  { value: 'workStatus', label: '工作状态', group: '设备信息' },
  { value: 'connectStatus', label: '连接状态', group: '设备信息' },
]

const value = ref([{ value: 'gunId' }, { value: 'gunName' }, { value: 'deviceName' }])
const customVisible = ref(false)
const activeLabel = ref('')
const targetActions = [{ key: 'custom', label: '自定义弹窗' }]

const handleTargetAction = (_key: string, item: (typeof data)[number]) => {
  activeLabel.value = item.label
  customVisible.value = true
}
</script>
```

### Tree

- `data`: Data of the transfer
- `default-value`: The default value in the target selection box (uncontrolled state)

Example source: src/transfer/__demos__/tree.vue

```vue
<template>
  <c-transfer :data="transferData" :default-value="value">
    <template #source="{ data, selectedKeys, onSelect }">
      <c-tree
        :checkable="true"
        checked-strategy="child"
        :checked-values="selectedKeys"
        :data="getTreeData(data)"
        @check="onSelect"
      />
    </template>
  </c-transfer>
</template>

<script lang="ts" setup>
const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf 0-0-1',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf 0-0-2-1',
            value: '0-0-2-1',
          },
          {
            label: 'Leaf 0-0-2-2',
            value: '0-0-2-2',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf 0-1-1-1',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf 0-1-1-2',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf 0-1-2',
        value: '0-1-2',
      },
    ],
  },
]

const getTransferData = (treeData = [], transferDataSource = []) => {
  treeData.forEach((item) => {
    if (item.children) getTransferData(item.children, transferDataSource)
    else transferDataSource.push({ label: item.label, value: item.value })
  })
  return transferDataSource
}

const getTreeData = (data = []) => {
  const values = data.map((item) => item.value)

  const travel = (_treeData = []) => {
    const treeDataSource = []
    _treeData.forEach((item) => {
      if (item.children || values.includes(item.value)) {
        treeDataSource.push({ label: item.label, value: item.value, children: travel(item.children) })
      }
    })
    return treeDataSource
  }

  return travel(treeData)
}

const transferData = getTransferData(treeData)

const value = [{ value: '0-0-2-1' }]
</script>
```

## Content customization

### Custom

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                 | Related examples      |
| --------------- | --------------------------------------- | --------------------- |
| `data`          | Data of the transfer                    | Custom, Custom Header |
| `default-value` | Complete uncontrolled target-side state | Custom, Custom Header |

<!-- demo-config-notes:end -->

- `data`: Data of the transfer
- `default-value`: The default value in the target selection box (uncontrolled state)

Example source: src/transfer/__demos__/custom.vue

```vue
<template>
  <c-transfer :data="data" :default-value="value">
    <template #item="{ label }">
      <c-icon-up />
      {{ label }}
    </template>
  </c-transfer>
</template>

<script lang="ts" setup>
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: `Option ${index + 1}`,
  }))
const value = [{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }]
</script>
```

### Custom Header

- `data`: Data of the transfer
- `default-value`: The default value in the target selection box (uncontrolled state)

Example source: src/transfer/__demos__/custom-header.vue

```vue
<template>
  <c-transfer :data="data" :default-value="value">
    <template #source-title="{ countTotal, countSelected, checked, indeterminate, onSelectAllChange }">
      <div :style="styleHeader">
        Source Title {{ countSelected }}-{{ countTotal }}
        <c-checkbox :model-value="checked" :indeterminate="indeterminate" @change="onSelectAllChange" />
      </div>
    </template>

    <template #target-title="{ countTotal, countSelected, onClear }">
      <div :style="styleHeader">
        Target Title {{ countSelected }}-{{ countTotal }}
        <c-icon-delete @click="onClear" />
      </div>
    </template>
  </c-transfer>
</template>

<script lang="ts" setup>
const data = Array(8)
  .fill(undefined)
  .map((_, index) => ({
    value: `option${index + 1}`,
    label: `Option ${index + 1}`,
  }))
const value = [{ value: 'option1' }, { value: 'option3' }, { value: 'option5' }]

const styleHeader = {
  display: 'flex',
  alignItems: 'center',
  justifyContent: 'space-between',
  paddingRight: '8px',
}
</script>
```

## Large datasets

### Large Data

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration               | Purpose                              | Related examples |
| --------------------------- | ------------------------------------ | ---------------- |
| `data`                      | Data of the transfer                 | Large Data       |
| `virtual-scroll`            | Whether virtual scrolling is enabled | Large Data       |
| `source-filterable`         | Show the source search input         | Large Data       |
| `source-filter-placeholder` | Source search placeholder            | Large Data       |

<!-- demo-config-notes:end -->

- `data`: Data of the transfer

Example source: src/transfer/__demos__/large-data.vue

```vue
<template>
  <c-transfer
    v-model="value"
    :data="data"
    virtual-scroll
    source-filterable
    source-filter-placeholder="搜索 42,000 项"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const data = Array.from({ length: 42000 }, (_, index) => ({
  value: index,
  label: `Option ${index}`,
  disabled: index % 5 === 0,
}))
const value = ref(Array.from({ length: 50 }, (_, index) => ({ value: index })))
</script>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### `<transfer>` Props

| Parameter                 | Description                                          | Type                                                        |             Default             |
| ------------------------- | ---------------------------------------------------- | ----------------------------------------------------------- | :-----------------------------: |
| data                      | Data of the transfer                                 | `TransferItem[]` / `(query, { signal }) => Array / Promise` |           `undefined`           |
| model-value **(v-model)** | Complete ordered target-side state                   | `TransferTargetItem[]`                                      |               `-`               |
| default-value             | Complete uncontrolled target-side state              | `TransferTargetItem[]`                                      |              `[]`               |
| disabled                  | Whether disabled                                     | `boolean`                                                   |             `false`             |
| virtual-scroll            | Whether virtual scrolling is enabled                 | `boolean`                                                   |             `false`             |
| target-draggable          | Whether the target list can be reordered by dragging | `boolean`                                                   |             `false`             |
| target-operation          | Target actions shown as a remove icon or action menu | `'remove' \| 'menu'`                                        |           `'remove'`            |
| clear-text                | Target clear-button text                             | `string`                                                    |             `清空`              |
| target-actions            | Custom actions appended to the target menu           | `TransferTargetAction[]`                                    |              `[]`               |
| source-filterable         | Show the source search input                         | `boolean`                                                   |             `false`             |
| target-filterable         | Show the target search input                         | `boolean`                                                   |             `false`             |
| show-search               | Show both search inputs                              | `boolean`                                                   |             `false`             |
| filter                    | Custom filter callback                               | `TransferFilter`                                            | Case-insensitive label matching |
| source-filter-placeholder | Source search placeholder                            | `string`                                                    |               `-`               |
| target-filter-placeholder | Target search placeholder                            | `string`                                                    |               `-`               |
| show-selected             | Keep selected items in the source list               | `boolean`                                                   |             `true`              |
| source-title              | Source list title                                    | `string`                                                    |               `-`               |
| target-title              | Target list title                                    | `string`                                                    |               `-`               |
| show-select-all           | Whether show select all checkbox on the header       | `boolean`                                                   |             `true`              |
| title                     | Source/target list titles                            | `string[]`                                                  |     `['Source', 'Target']`      |
| source-search-props       | Source Search configuration in Cedar                 | `object`                                                    |               `-`               |
| target-search-props       | Target Search configuration in Cedar                 | `object`                                                    |               `-`               |

### `<transfer>` Events

| Event         | Description                             | Arguments                                     |
| ------------- | --------------------------------------- | --------------------------------------------- |
| change        | Emitted when target state changes       | value: `TransferTargetItem[]`                 |
| search        | Emitted on user search                  | value: `string`<br>type: `'target'\|'source'` |
| rename        | Emitted when renaming is confirmed      | value: `TransferValue`, label: `string`       |
| target-action | Emitted when a custom action is clicked | key: `string`, item: `TransferItem`           |

### `<transfer>` Slots

| Slot           |       Description        | Arguments                                                                                                                                                                                             | Version |
| -------------- | :----------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| source         |       Source panel       | data: `TransferItem[]`<br>selectedKeys: `string[]`<br>onSelect: `(value: string[]) => void`                                                                                                           | 2.39.0  |
| source-title   |    Source-title slot     | countTotal: `number`<br>countSelected: `number`<br>searchValue: `string`<br>checked: `boolean`<br>indeterminate: `boolean`<br>onSelectAllChange: `(checked:boolean) => void`<br>onClear: `() => void` | 2.45.0  |
| to-target-icon | Move-to-target icon slot | -                                                                                                                                                                                                     | 2.52.0  |
| to-source-icon | Move-to-source icon slot | -                                                                                                                                                                                                     | 2.52.0  |
| target         |       Target panel       | data: `TransferItem[]`<br>selectedKeys: `string[]`<br>onSelect: `(value: string[]) => void`                                                                                                           | 2.39.0  |
| target-title   |    Target-title slot     | countTotal: `number`<br>countSelected: `number`<br>searchValue: `string`<br>checked: `boolean`<br>indeterminate: `boolean`<br>onSelectAllChange: `(checked:boolean) => void`<br>onClear: `() => void` | 2.45.0  |
| item           |         Options          | value: `TransferValue`<br>label: `string`<br>item: `TransferItem`                                                                                                                                     |         |

### TransferItem

| Parameter | Description                                        | Type                           | Default |
| --------- | -------------------------------------------------- | ------------------------------ | :-----: |
| value     | Option value                                       | `string \| number`             |   `-`   |
| label     | Option label                                       | `string`                       |   `-`   |
| disabled  | Whether disabled                                   | `boolean`                      | `false` |
| group     | Source-group title                                 | `string`                       |   `-`   |
| tip       | Option hint                                        | `string \| (() => VNodeChild)` |   `-`   |
| required  | Whether required; required items cannot be removed | `boolean`                      | `false` |

### Type definitions

The component exports the following types

```ts
import type {
  TransferFilter,
  TransferFixed,
  TransferInstance,
  TransferItem,
  TransferTargetAction,
  TransferTargetItem,
  TransferTargetOperation,
  TransferValue,
} from "@cedar-design/ui";
```

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

`data` accepts an array or (query, { signal }) => array/Promise. The component manages loading, cancellation and stale-result isolation; failures emit load-error. Single/multiple groups initialize with an empty query; searchable fields reload when queries change. Tree root loading is independent of existing load-more child loading.

## Reading direction and keyboard interaction

Transfer places candidates at inline-start and selected items at inline-end. Direction changes preserve selected identity/order, filters and frozen state. Native checkboxes and removal buttons support keyboard interaction. Vertical drag ordering and existing left/right freeze values keep their business meaning.

---

Document: llms/en-US/components/tree-select.md

<!-- Source: src/tree-select/README.en-US.md; locale: en-US; page: /en/components/tree-select/ -->

# TreeSelect

A tree-backed selection field with explicit search fields and controlled selection.

## Reading direction

Inherits source dir. Horizontal keys expand, enter children, return or collapse according to reading direction; vertical keys and Home/End keep logical order. Search uses the actual active match. Values and multiple-value arrays are not reversed. Portaled content retains source direction in custom containers.

## Search migration

filterable replaces allowSearch. The old object retainInputValue option is now the independent retain-input-value boolean. filterable enables search; retain-input-value only retains query text after selecting. Default single selection disables search and multiple selection enables it.

Default local matching now searches label and ignores case. Restore the previous matching with search-fields=['value'] and case-sensitive=true. Multiple configured fields use OR matching. Custom filter-tree-node owns its matching rules. disableFilter bypasses built-in filtering.

## Basic examples

### Basic

Example source: src/tree-select/__demos__/basic.vue

```vue
<template>
  <c-space direction="column">
    <c-tree-select v-model="value" :data="data" selectable placeholder="选择部门" />
    <p role="status">当前部门：{{ value || '未选择' }}</p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from 'vue'
const value = ref<string>()
const data = [
  { value: 'design', label: '设计部' },
  { value: 'engineering', label: '研发部' },
]
</script>
```

### Api Review

## Data and options

### Search Matching

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration        | Purpose                                    | Related examples                                  |
| -------------------- | ------------------------------------------ | ------------------------------------------------- |
| `data`               | Data                                       | Search Matching, Retain the query after selecting |
| `filterable`         | Whether to allow searching                 | Search Matching, Retain the query after selecting |
| `case-sensitive`     | Case-sensitive built-in search             | Search Matching                                   |
| `multiple`           | Whether to support multiple selection      | Retain the query after selecting                  |
| `retain-input-value` | Keep search text after selecting an option | Retain the query after selecting                  |

<!-- demo-config-notes:end -->

Example source: src/tree-select/__demos__/search-matching.vue

```vue
<script setup lang="ts">
import { computed, ref } from "vue";
const value = ref("");
const mode = ref("label");
const caseSensitive = ref(false);
const modes = [
  { value: "label", label: "默认：只匹配 label" },
  { value: "both", label: "配置：value 或 label" },
];
const options = [
  { value: "USER_A", label: "Apple" },
  { value: "USER_B", label: "Banana" },
];
const searchFields = computed<("label" | "value")[]>(() =>
  mode.value === "both" ? ["value", "label"] : ["label"],
);
</script>
<template>
  <c-space direction="column" align="stretch" fill>
    <c-form-item layout="vertical" size="sm" label="匹配字段">
      <c-radio-group
        v-model="mode"
        aria-label="匹配字段"
        :options="modes"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-space
      ><c-switch v-model="caseSensitive" /><span>区分大小写</span></c-space
    >
    <c-tree-select
      v-model="value"
      :data="options"
      :case-sensitive="caseSensitive"
      :search-fields="searchFields"
      filterable
      placeholder="输入 Apple、apple 或 USER_A"
    />
    <p>
      默认搜索 label，不区分大小写；配置两字段后，USER_A 和 Apple
      都能找到同一个选项。
    </p>
  </c-space>
</template>
```

### Retain the query after selecting

Type Al, then select Alice: the selected model contains Alice in both examples. Without retain-input-value the search text becomes empty; with it enabled, Al remains so Alan is still easy to select next. This does not control the selected label or whether the field is searchable. filterable enables searching.

Example source: src/tree-select/__demos__/en-US/retain-input-value.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
const cleared = ref<string[]>([])
const retained = ref<string[]>([])
const clearQuery = ref('')
const retainedQuery = ref('')
const data = [{ key: 'alice', title: 'Alice' }, { key: 'alan', title: 'Alan' }, { key: 'bob', title: 'Bob' }]
</script>
<template>
  <c-space direction="column">
    <p>Type Al and select Alice. Both fields select Alice; only the remaining query text differs.</p>
    <c-tree-select v-model="cleared" v-model:input-value="clearQuery" :data="data" filterable multiple placeholder="Clear query after selecting" />
    <output>Selected: {{ cleared }}; query: {{ JSON.stringify(clearQuery) }}</output>
    <c-tree-select v-model="retained" v-model:input-value="retainedQuery" :data="data" filterable multiple retain-input-value placeholder="Keep query after selecting" />
    <output>Selected: {{ retained }}; query: {{ JSON.stringify(retainedQuery) }}</output>
  </c-space>
</template>
```

The candidate `data` prop accepts an array or `(query, { signal }) => array/Promise`. Components own loading, cancellation and stale results, and emit load-error on failure. Choice groups initialize with an empty query; searchable fields load when queries change. Root tree loaders remain independent of existing load-more child loading.

## Lifecycle and edge cases

### Passthrough Options

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration         | Purpose                                                                                                                          | Related examples    |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `data`                | Data                                                                                                                             | Passthrough Options |
| `tree-props`          | Can accept Props of all [Tree](vue/component/tree) components                                                                   | Passthrough Options |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | Copying and editing |
| `filterable`          | Whether to allow searching                                                                                                       | Copying and editing |

<!-- demo-config-notes:end -->

Example source: src/tree-select/__demos__/passthrough-options.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type {
  TreeSelectTriggerOptions,
  TreeSelectTreeOptions,
} from "@cedar-design/ui";
const open = ref(false);
const triggerOptions: TreeSelectTriggerOptions = {
  placement: "top-start",
  popupOffset: 8,
};
const data = [
  {
    value: "fruit",
    label: "水果",
    children: [{ value: "apple", label: "Apple" }],
  },
];
const treeOptions: TreeSelectTreeOptions = {
  showLine: true,
  defaultExpandAll: false,
};
</script>
<template>
  <c-space direction="column" fill>
    <c-button @click="open = !open">{{
      open ? "关闭面板" : "打开面板"
    }}</c-button>
    <c-tree-select
      edit-mode="direct"
      v-model:open="open"
      :data="data"
      :tree-props="treeOptions"
      :trigger-props="triggerOptions"
      aria-label="透传配置示例"
    />
    <p role="status">顶层 open：{{ open }}；嵌套配置：向上展开并调整偏移。</p>
  </c-space>
</template>
```

### Copying and editing

With open-trigger-target="icon", use the input area to edit or copy and the suffix button to open. Existing text remains copyable when editing or search is disabled.

Example source: src/tree-select/__demos__/open-trigger-target.en-US.vue

```vue
<template>
  <c-space direction="column">
    <c-radio-group
      v-model="target"
      :options="[
        { label: 'Whole field', value: 'field' },
        { label: 'Suffix icon only', value: 'icon' },
      ]"
    />
    <label><c-switch v-model="editable" /> Allow editing / search</label>
    <c-tree-select
      v-model="value"
      edit-mode="direct"
      :open-trigger-target="target"
      :filterable="editable"
      :options="[
        { value: 'a', label: 'Alpha' },
        { value: 'b', label: 'Beta' },
      ]"
    />
    <p>
      Disable editing to copy existing text. In icon mode, editing does not open
      the panel.
    </p>
  </c-space>
</template>
<script setup lang="ts">
import { ref } from "vue";
const target = ref<"field" | "icon">("icon");
const editable = ref(true);
const value = ref("a");
</script>
```

### TreeSelect Props

| Prop                  | Description                                                                                                                      | Type                                                      | Default                       |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------- |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                                       | `'field'`                     |
| model-value           | Value                                                                                                                            | string / number / array                                   | undefined                     |
| data                  | Data                                                                                                                             | TreeNodeData[] / `(query, { signal }) => Array / Promise` | `undefined`                   |
| multiple              | Whether to support multiple selection                                                                                            | boolean                                                   | false                         |
| filterable            | Whether to allow searching                                                                                                       | boolean                                                   | Single: false; multiple: true |
| retain-input-value    | Keep search text after selecting an option                                                                                       | boolean                                                   | false                         |
| case-sensitive        | Case-sensitive built-in search                                                                                                   | boolean                                                   | false                         |
| filter-tree-node      | Custom node filter function                                                                                                      | Function                                                  | undefined                     |
| tree-props            | Can accept Props of all [Tree](vue/component/tree) components                                                                   | TreeProps                                                 | undefined                     |

### TreeSelect Events

| Event                                  | Description                              | Arguments     |
| -------------------------------------- | ---------------------------------------- | ------------- |
| update:modelValue                      | Request a selected business value update | value         |
| change                                 | Committed selected value changes         | value         |
| search                                 | Search text changes                      | text: string  |
| update:inputValue / input-value-change | Request input text update                | text: string  |
| update:open / open-change              | Panel visibility changes                 | open: boolean |
| clear                                  | Clear selection                          | None          |

### TreeSelect Slots

| Slot    | Description            |
| ------- | ---------------------- |
| default | Custom default content |

### Shared field loading

`loading` displays the shared field indicator. `loading-mode` is `default` (indicator) or `line` (an indeterminate bottom line); it defaults to `default`. Rendering belongs to FieldDecorator. Loading does not implicitly disable editing or change readonly. Set those states separately.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### TreeSelect Props

| Prop                  | Description                                                                                                                      | Type                                                      | Default                       |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------------------------- |
| `open-trigger-target` | Pointer opening target: the whole field or only the suffix icon. Explicit keyboard opening and controlled open remain available. | `'field' \| 'icon'`                                       | `'field'`                     |
| model-value           | Value                                                                                                                            | string / number / array                                   | undefined                     |
| data                  | Data                                                                                                                             | TreeNodeData[] / `(query, { signal }) => Array / Promise` | `undefined`                   |
| multiple              | Whether to support multiple selection                                                                                            | boolean                                                   | false                         |
| filterable            | Whether to allow searching                                                                                                       | boolean                                                   | Single: false; multiple: true |
| retain-input-value    | Keep search text after selecting an option                                                                                       | boolean                                                   | false                         |
| case-sensitive        | Case-sensitive built-in search                                                                                                   | boolean                                                   | false                         |
| filter-tree-node      | Custom node filter function                                                                                                      | Function                                                  | undefined                     |
| tree-props            | Can accept Props of all [Tree](vue/component/tree) components                                                                   | TreeProps                                                 | undefined                     |

`disabled`/`readonly` accept explicit field values and Form/FormItem inheritance. Confirmation locks editing. Failed validation preserves drafts; reset closes the popup and discards unfinished commits.

### TreeSelect Events

| Event                                  | Description                              | Arguments     |
| -------------------------------------- | ---------------------------------------- | ------------- |
| update:modelValue                      | Request a selected business value update | value         |
| change                                 | Committed selected value changes         | value         |
| search                                 | Search text changes                      | text: string  |
| update:inputValue / input-value-change | Request input text update                | text: string  |
| update:open / open-change              | Panel visibility changes                 | open: boolean |
| clear                                  | Clear selection                          | None          |

### TreeSelect Slots

| Slot    | Description            |
| ------- | ---------------------- |
| default | Custom default content |

## Type definitions

The component exports the following types

```ts
import type { TreeSelectProps } from "@cedar-design/ui";
```

### Form field presentation and confirmation

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

### In-place editing and keyboard precedence

`click`/`dblclick` use Form's editing inheritance. Hover/focus shows an edit icon that opens editing directly. disabled, readonly and readPretty hide edit entries. Panel clicks change only the draft.

While open, arrows navigate visible enabled nodes; Left/Right collapse/expand or move to parents/children; Home/End reach first/last nodes. Enter selects/checks the current node, or toggles an unselectable branch. Search prioritizes matching nodes; multiple selection uses Tree checking rules. Esc first closes the panel, retaining the draft and restoring input focus. With the panel closed, Enter saves and Esc cancels editing. Compare AutoComplete/PeopleSelect in Form's unified field-presentation examples.

Duplicate expansion requests for the same asynchronously loaded node are merged. Replacing nodes, closing editors or resetting Form invalidates old requests so they cannot expand/check nodes. Arrows can enter loaded children immediately. Query/candidate changes clear old filters before Enter can choose stale options. Field confirmation still validates before asynchronous commit.

### Node fields and business values

Nodes default to `{ value, label, children }`. `value` is a tree-wide unique string/number, including `0`; `label` is display content. Map other backend fields with `fieldNames: { value: 'id', label: 'text', children: 'items' }` without changing backend data. Declarative child `name`, Vue `:key` and Table `rowKey` retain separate meanings.

Independent Tree state uses `selectedValues/defaultSelectedValues`, `checkedValues/defaultCheckedValues`, `halfCheckedValues` and `expandedValues/defaultExpandedValues`, updated through corresponding named v-models. `check` event indeterminate sets use `halfCheckedValues`. Node content uses `label`; TreeSelect forwards `tree-slot-label`. `scrollIntoView({ value })` locates business values; explicit `index` remains a zero-based virtual-list array `index`.

### Search configuration

Use `filterable` to enable search: single defaults false, multiple true. `retain-input-value` separately controls whether selection retains the search query, default false.

Migration: `allow-search` becomes `filterable`; `{ retainInputValue: true }` becomes `filterable` plus `retain-input-value`. Old entries are removed without compatibility aliases and require a major release.

### Built-in search fields

`searchFields` / `search-fields` is a readonly `('label' | 'value')[]`, defaulting to `['label']`. Multiple fields use OR matching, case-insensitive by default. `['value', 'label']` searches codes and names; fieldNames maps semantic fields to business fields. An empty array matches no items for a nonempty query. Values are compared as strings; object traversal, object values and pinyin matching require a custom callback. A custom callback takes precedence and decides case handling itself. Remote results use the existing protocol for disabling local filtering. Cascader retains path semantics and checks the configured fields on each path node.

## Configuring the cleared value

`empty-value` / `emptyValue` sets the model value produced by clearing. It accepts a value in the component model type or a zero-argument factory. Omission preserves the existing default; use `() => undefined` to distinguish omission from returning undefined. Arrays are shallow-copied on every clear; selected items that cannot be cleared remain. It does not redefine emptiness, alter Form reset defaults or treat 0/false as universally empty.

---

Document: llms/en-US/components/tree.md

<!-- Source: src/tree/README.en-US.md; locale: en-US; page: /en/components/tree/ -->

# Tree

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

- `data`: Pass in `data` to generate the corresponding tree structure
- `default-expanded-values`: Nodes expanded by default
- `default-selected-values`: Tree node selected by default

Example source: src/tree/__demos__/basic.vue

```vue
<template>
  <c-tree :data="treeData" :default-expanded-values="['0-0-0']" :default-selected-values="['0-0-0', '0-0-1']" />
</template>

<script lang="ts" setup>
const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-0',
        value: '0-0-0',
        disabled: true,
        children: [
          {
            label: 'Leaf',
            value: '0-0-0-0',
          },
          {
            label: 'Leaf',
            value: '0-0-0-1',
          },
        ],
      },
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf',
            value: '0-0-1-0',
          },
        ],
      },
    ],
  },
]
</script>
```

## Appearance and layout

### Tree density and connecting lines

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `block-node` | Whether the node occupies a row | Tree density and connecting lines |
| `checkable` | Add a checkbox before nodes | Tree density and connecting lines |
| `size` | Size | Tree density and connecting lines |
| `data` | Pass in `data` to generate the corresponding tree structure | Tree density and connecting lines |
| `default-selected-values` | Tree node selected by default | Tree density and connecting lines |
| `show-line` | Whether to display the connection line | Tree density and connecting lines |
<!-- demo-config-notes:end -->


Compare node sizes, full-row blocks and connecting lines separately from selection, dragging and asynchronous nodes.

Example source: src/tree/__demos__/appearance-comparison.vue

```vue
<script setup lang="ts">
import { ref } from "vue"
import { proxyRefs as demoProxyRefs } from 'vue'

const scene1 = demoProxyRefs((() => {


const size = ref('md')

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-0',
        value: '0-0-0',
        children: [
          {
            label: 'Leaf',
            value: '0-0-0-0',
          },
          {
            label: 'Leaf',
            value: '0-0-0-1',
          },
        ],
      },
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf',
            value: '0-0-1-0',
          },
        ],
      },
    ],
  },
]
return { size, treeData }
})())

const scene2 = demoProxyRefs((() => {

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-0',
        value: '0-0-0',
        children: [
          {
            label: 'Leaf',
            value: '0-0-0-0',
          },
          {
            label: 'Leaf',
            value: '0-0-0-1',
          },
        ],
      },
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf',
            value: '0-0-1-0',
          },
        ],
      },
    ],
  },
]
return { treeData }
})())

const scene3 = demoProxyRefs((() => {


const showLine = ref(true)

const treeData = [
  {
    label: 'Trunk 1',
    value: '0-0',
    children: [
      {
        label: 'Trunk 1-0',
        value: '0-0-0',
        children: [
          { label: 'leaf', value: '0-0-0-0' },
          {
            label: 'leaf',
            value: '0-0-0-1',
            children: [{ label: 'leaf', value: '0-0-0-1-0' }],
          },
          { label: 'leaf', value: '0-0-0-2' },
        ],
      },
      {
        label: 'Trunk 1-1',
        value: '0-0-1',
      },
      {
        label: 'Trunk 1-2',
        value: '0-0-2',
        children: [
          { label: 'leaf', value: '0-0-2-0' },
          {
            label: 'leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 2',
    value: '0-1',
  },
  {
    label: 'Trunk 3',
    value: '0-2',
    children: [
      {
        label: 'Trunk 3-0',
        value: '0-2-0',
        children: [
          { label: 'leaf', value: '0-2-0-0' },
          { label: 'leaf', value: '0-2-0-1' },
        ],
      },
    ],
  },
]
return { showLine, treeData }
})())
</script>

<template>
<div class="demo-comparison">
  <section class="demo-comparison-case demo-comparison-case--1" data-comparison-scene="size">
    <h4><span lang="zh-CN">不同尺寸</span><span lang="en-US">size</span></h4>
    <div style="margin-bottom: 20px">
        <c-radio-group v-model="scene1.size" type="button">
          <c-radio value="xs">xs</c-radio>
          <c-radio value="sm">sm</c-radio>
          <c-radio value="md">md</c-radio>
          <c-radio value="lg">lg</c-radio>
          <c-radio value="xl">xl</c-radio>
        </c-radio-group>
      </div>
      <c-tree style="margin-right: 20px" :blockNode="true" :checkable="true" :size="scene1.size" :data="scene1.treeData" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--2" data-comparison-scene="block-node">
    <h4><span lang="zh-CN">节点占一行</span><span lang="en-US">block node</span></h4>
    <c-tree block-node :data="scene2.treeData" />
  </section>

  <section class="demo-comparison-case demo-comparison-case--3" data-comparison-scene="show-line">
    <h4><span lang="zh-CN">显示连接线</span><span lang="en-US">show line</span></h4>
    <div>
        <c-typography-text>showLine</c-typography-text>
        <c-switch v-model="scene3.showLine" style="margin-left: 12px" />
      </div>
      <c-tree :default-selected-values="['0-0-1']" :data="scene3.treeData" :show-line="scene3.showLine" />
  </section>
</div>
</template>

<style scoped lang="less">
.demo-comparison { display: grid; gap: 24px; min-width: 0; max-width: 100%; }
.demo-comparison-case { min-width: 0; max-width: 100%; }
.demo-comparison-case > h4 { margin: 0 0 12px; font-size: 14px; }
html:not([lang='en-US']) .demo-comparison-case > h4 > [lang='en-US'],
html[lang='en-US'] .demo-comparison-case > h4 > [lang='zh-CN'] { display: none; }

</style>
```

## Node selection and state

### Multiple

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Pass in `data` to generate the corresponding tree structure | Multiple, Checkable, Control |
| `checkable` | Add a checkbox before nodes | Checkable, Control, Checked Strategy |
| `multiple` | Whether to support multiple selection | Multiple |
| `check-strictly` | Whether to cancel the parent-child node association | Checkable |
| `checked-strategy` | Customized backfill method <br/> all: return all selected nodes <br/> parent: return only parent node when both parent and child nodes are selected <br/> child: return only child nodes | Checked Strategy |
<!-- demo-config-notes:end -->


- `selected-values`: Selected tree node
- `multiple`: Whether to support multiple selection
- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/multiple.vue

```vue
<template>
  <c-checkbox
    style="margin-bottom: 24px"
    v-model="multiple"
    @change="
      () => {
        selectedValues = []
      }
    "
  >
    multiple
  </c-checkbox>
  <br />
  <c-typography-text> Current: {{ selectedValues?.join(' , ') }} </c-typography-text>
  <br />
  <c-tree v-model:selected-values="selectedValues" :multiple="multiple" :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const selectedValues = ref([])
const multiple = ref(true)
const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
]
</script>
```

### Checkable

- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `checked-values`: Tree node with check box selected
- `check-strictly`: Whether to cancel the parent-child node association
- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/checkable.vue

```vue
<template>
  <c-checkbox
    style="margin-bottom: 24px"
    v-model="checkStrictly"
    @change="
      () => {
        checkedValues = []
      }
    "
  >
    checkStrictly
  </c-checkbox>
  <c-tree :checkable="true" v-model:checked-values="checkedValues" :check-strictly="checkStrictly" :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const checkedValues = ref([])
const checkStrictly = ref(false)

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        disabled: true,
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
          {
            label: 'Leaf',
            value: '0-0-2-2',
            disableCheckbox: true,
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf ',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf ',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
]
</script>
```

### Control

- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `selected-values`: Selected tree node
- `checked-values`: Tree node with check box selected
- `expanded-values`: Expanded node

Example source: src/tree/__demos__/control.vue

```vue
<template>
  <c-button-group style="margin-bottom: 20px">
    <c-button status="primary" @click="toggleChecked">
      {{ checkedValues?.length ? 'deselect all' : 'select all' }}
    </c-button>
    <c-button status="primary" @click="toggleExpanded">
      {{ expandedValues?.length ? 'fold' : 'unfold' }}
    </c-button>
  </c-button-group>
  <c-tree
    :checkable="true"
    v-model:selected-values="selectedValues"
    v-model:checked-values="checkedValues"
    v-model:expanded-values="expandedValues"
    @select="onSelect"
    @check="onCheck"
    @expand="onExpand"
    :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const allCheckedValues = ['0-0', '0-0-1', '0-0-2', '0-0-2-1', '0-1', '0-1-1', '0-1-2']
const allExpandedValues = ['0-0', '0-1', '0-0-2']
const selectedValues = ref([])
const checkedValues = ref([])
const expandedValues = ref([])

function toggleChecked() {
  checkedValues.value = checkedValues?.value.length ? [] : allCheckedValues
}

function toggleExpanded() {
  expandedValues.value = expandedValues?.value.length ? [] : allExpandedValues
}

function onSelect(newSelectedValues, event) {
  console.log('select: ', newSelectedValues, event)
}

function onCheck(newCheckedValues, event) {
  console.log('check: ', newCheckedValues, event)
}

function onExpand(newExpandedValues, event) {
  console.log('expand: ', newExpandedValues, event)
}

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf 0-0-1',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf 0-0-2-1',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Leaf 0-1-1',
        value: '0-1-1',
      },
      {
        label: 'Leaf 0-1-2',
        value: '0-1-2',
      },
    ],
  },
]
</script>
```

### Checked Strategy

- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `checked-values`: Tree node with check box selected
- `checked-strategy`: Customized backfill method <br/> all: return all selected nodes <br/> parent: return only parent node when both parent and child nodes are selected <br/> child: return only child nodes
- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/checked-strategy.vue

```vue
<template>
  <c-radio-group
    type="button"
    v-model="checkedStrategy"
    @change="
      (value) => {
        checkedValues = []
      }
    "
  >
    <c-radio v-for="item in strategyOptions" :key="item?.value" :value="item?.value">
      {{ item?.label }}
    </c-radio>
  </c-radio-group>
  <br />
  <c-typography-text style="margin: 24px 0; display: inline-block">
    Current: {{ checkedValues?.join(' , ') }}
  </c-typography-text>
  <br />
  <c-tree :checkable="true" v-model:checked-values="checkedValues" :checked-strategy="checkedStrategy" :data="treeData" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const checkedValues = ref([])
const checkedStrategy = ref('all')

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
]

const strategyOptions = [
  {
    value: 'all',
    label: 'show all',
  },
  {
    value: 'parent',
    label: 'show parent',
  },
  {
    value: 'child',
    label: 'show child',
  },
]
</script>
```

## Node customization

### Node Icon

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Pass in `data` to generate the corresponding tree structure | Node Icon, Icons, Render Extra |
| `show-line` | Whether to display the connection line | Icons |
| `block-node` | Whether the node occupies a row | Render Extra |
| `checkable` | Add a checkbox before nodes | Render Extra |
| `selectable` | Whether selection is supported | Render Extra |
| `check-strictly` | Whether to cancel the parent-child node association | Render Extra |
<!-- demo-config-notes:end -->


- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/node-icon.vue

```vue
<template>
  <c-tree :data="treeData">
    <template #icon>
      <c-icon-star />
    </template>
  </c-tree>
</template>

<script lang="ts" setup>
import { IconDriveFile } from '@cedar-design/icons-vue'
import { h } from 'vue'

const treeData = [
  {
    label: 'Trunk',
    value: 'node1',
    children: [
      {
        label: 'Leaf',
        value: 'node2',
      },
    ],
  },
  {
    label: 'Trunk',
    value: 'node3',
    children: [
      {
        label: 'Leaf',
        value: 'node4',
        icon: () => h(IconDriveFile),
      },
      {
        label: 'Leaf',
        value: 'node5',
        icon: () => h(IconDriveFile),
      },
    ],
  },
]
</script>
```

### Icons

- `data`: Pass in `data` to generate the corresponding tree structure
- `show-line`: Whether to display the connection line

Example source: src/tree/__demos__/icons.vue

```vue
<template>
  <c-tree :data="treeData" show-line>
    <template #switcher-icon="{ children }">
      <c-icon-down v-if="children?.length" />
      <c-icon-star v-else />
    </template>
  </c-tree>
</template>

<script lang="ts" setup>
import { IconDriveFile } from '@cedar-design/icons-vue'
import { h } from 'vue'

const treeData = [
  {
    label: 'Trunk',
    value: 'node1',
    children: [
      {
        label: 'Leaf',
        value: 'node2',
      },
    ],
  },
  {
    label: 'Trunk',
    value: 'node3',
    children: [
      {
        label: 'Leaf',
        value: 'node4',
        switcherIcon: () => h(IconDriveFile),
      },
      {
        label: 'Leaf',
        value: 'node5',
        switcherIcon: () => h(IconDriveFile),
      },
    ],
  },
]
</script>
```

### Render Extra

- `block-node`: Whether the node occupies a row
- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `selectable`: Whether to support selection, function format is supported since `2.27.0`
- `check-strictly`: Whether to cancel the parent-child node association

Example source: src/tree/__demos__/render-extra.vue

```vue
<template>
  <div style="width: 500px; padding: 2px; overflow: auto">
    <c-space wrap>
      <c-checkbox v-model="leafChecksOnly">Leaf checkboxes only</c-checkbox>
      <c-checkbox v-model="leafSelectionOnly">Leaf selection only</c-checkbox>
      <c-checkbox v-model="strict">Strict checks</c-checkbox>
      <c-tag>Checked: {{ checkedValues.join(', ') || '-' }}</c-tag>
      <c-tag>Selected: {{ selectedValues.join(', ') || '-' }}</c-tag>
    </c-space>
    <c-tree
      :block-node="true"
      :checkable="leafChecksOnly ? isLeafNode : true"
      :selectable="leafSelectionOnly ? isLeafNode : true"
      :check-strictly="strict"
      :data="treeData"
      @check="keys => checkedValues = keys"
      @select="keys => selectedValues = keys"
    >
      <template #extra="nodeData">
        <c-button
          variant="text"
          size="xs"
          :aria-label="'Add child to ' + nodeData.title + ' (' + nodeData.key + ')'"
          style="position: absolute; right: 8px; top: 2px"
          @click.stop="onIconClick(nodeData)"
        >
          <template #icon><c-icon-plus /></template>
        </c-button>
      </template>
    </c-tree>
  </div>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const leafChecksOnly = ref(false)
const leafSelectionOnly = ref(false)
const strict = ref(false)
const checkedValues = ref<(string | number)[]>([])
const selectedValues = ref<(string | number)[]>([])
const isLeafNode = (_node: unknown, info: { isLeaf: boolean }) => info.isLeaf

function onIconClick(nodeData) {
  const children = nodeData.children || []
  children.push({
    label: 'new tree node',
    value: nodeData.key + '-' + (children.length + 1),
  })
  nodeData.children = children

  treeData.value = [...treeData.value]
}

const treeData = ref([
  {
    label: 'Trunk',
    value: '0-0',
    children: [
      {
        label: 'Leaf',
        value: '0-0-1',
      },
      {
        label: 'Branch',
        value: '0-0-2',
        children: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk',
    value: '0-1',
    children: [
      {
        label: 'Branch',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf',
        value: '0-1-2',
      },
    ],
  },
])
</script>
```

### Field Names

- `default-selected-values`: Tree node selected by default
- `field-names`: Specify the field name in the node data
- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/field-names.vue

```vue
<template>
  <c-tree
    :default-selected-values="['0-0-2-1-0-0']"
    :fieldNames="{
      value: 'value',
      label: 'label',
      children: 'items',
      icon: 'customIcon',
    }"
    :data="treeData" />
</template>

<script lang="ts" setup>
import { IconDriveFile, IconStar } from '@cedar-design/icons-vue'
import { h } from 'vue'

const treeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    items: [
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        selectable: false,
        customIcon: () => h(IconDriveFile),
        items: [
          {
            label: 'Leaf',
            value: '0-0-2-1',
            items: [
              {
                label: 'Leaf 0-0-2',
                value: '0-0-2-1-0',
                items: [
                  {
                    label: 'Leaf',
                    customIcon: () => h(IconStar),
                    value: '0-0-2-1-0-0',
                  },
                ],
              },
            ],
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    items: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        items: [
          {
            label: 'Leaf',
            value: '0-1-1-0',
          },
        ],
      },
    ],
  },
]
</script>
```

## Search and drag

### Search

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Pass in `data` to generate the corresponding tree structure | Search, Draggable |
| `draggable` | Whether it can be dragged | Draggable |
| `block-node` | Whether the node occupies a row | Draggable |
| `checkable` | Add a checkbox before nodes | Draggable |
<!-- demo-config-notes:end -->


- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/search.vue

```vue
<template>
  <div>
    <c-search style="margin-bottom: 8px; max-width: 240px" v-model="searchKey" />
    <c-tree :data="treeData">
      <template #label="nodeData">
        <template v-if="(index = getMatchIndex(nodeData?.title)) < 0">
          {{ nodeData?.title }}
        </template>
        <span v-else>
          {{ nodeData?.label?.substr(0, index) }}
          <span style="color: var(--color-primary-light-4)">
            {{ nodeData?.label?.substr(index, searchKey.length) }} </span
          >{{ nodeData?.label?.substr(index + searchKey.length) }}
        </span>
      </template>
    </c-tree>
  </div>
</template>

<script lang="ts" setup>
import { computed, ref } from 'vue'

let index

const originTreeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Branch 0-0-1',
        value: '0-0-1',
        children: [
          {
            label: 'Leaf 0-0-1-1',
            value: '0-0-1-1',
          },
          {
            label: 'Leaf 0-0-1-2',
            value: '0-0-1-2',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        children: [
          {
            label: 'Leaf 0-1-1-0',
            value: '0-1-1-0',
          },
        ],
      },
      {
        label: 'Branch 0-1-2',
        value: '0-1-2',
        children: [
          {
            label: 'Leaf 0-1-2-0',
            value: '0-1-2-0',
          },
        ],
      },
    ],
  },
]
const searchKey = ref('')
const treeData = computed(() => {
  if (!searchKey.value) return originTreeData
  return searchData(searchKey.value)
})

function searchData(keyword) {
  const loop = (data) => {
    const result = []
    data.forEach((item) => {
      if (item.title.toLowerCase().indexOf(keyword.toLowerCase()) > -1) {
        result.push({ ...item })
      } else if (item.children) {
        const filterData = loop(item.children)
        if (filterData.length) {
          result.push({
            ...item,
            children: filterData,
          })
        }
      }
    })
    return result
  }

  return loop(originTreeData)
}

function getMatchIndex(title) {
  if (!searchKey.value) return -1
  return title.toLowerCase().indexOf(searchKey.value.toLowerCase())
}
</script>
```

### Draggable

- `draggable`: Whether it can be dragged
- `block-node`: Whether the node occupies a row
- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `data`: Pass in `data` to generate the corresponding tree structure

Example source: src/tree/__demos__/draggable.vue

```vue
<template>
  <c-checkbox v-model="checked" style="margin-bottom: 20px"> checkable </c-checkbox>
  <c-tree class="tree-demo" draggable blockNode :checkable="checked" :data="treeData" @drop="onDrop" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const defaultTreeData = [
  {
    label: 'Trunk 0-0',
    value: '0-0',
    children: [
      {
        label: 'Leaf 0-0-1',
        value: '0-0-1',
      },
      {
        label: 'Branch 0-0-2',
        value: '0-0-2',
        disableCheckbox: true,
        children: [
          {
            draggable: false,
            label: 'Leaf 0-0-2-1 (Drag disabled)',
            value: '0-0-2-1',
          },
        ],
      },
    ],
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
        checkable: false,
        children: [
          {
            label: 'Leaf 0-1-1-1',
            value: '0-1-1-1',
          },
          {
            label: 'Leaf 0-1-1-2',
            value: '0-1-1-2',
          },
        ],
      },
      {
        label: 'Leaf 0-1-2',
        value: '0-1-2',
      },
    ],
  },
]

const treeData = ref(defaultTreeData)
const checkedValues = ref([])
const checked = ref(false)

function onDrop({ dragNode, dropNode, dropPosition }) {
  const data = treeData.value
  const loop = (data, key, callback) => {
    data.some((item, index, arr) => {
      if (item.key === key) {
        callback(item, index, arr)
        return true
      }
      if (item.children) {
        return loop(item.children, key, callback)
      }
      return false
    })
  }

  loop(data, dragNode.key, (_, index, arr) => {
    arr.splice(index, 1)
  })

  if (dropPosition === 0) {
    loop(data, dropNode.key, (item) => {
      item.children = item.children || []
      item.children.push(dragNode)
    })
  } else {
    loop(data, dropNode.key, (_, index, arr) => {
      arr.splice(dropPosition < 0 ? index : index + 1, 0, dragNode)
    })
  }
}
</script>
```

## Async data and virtualization

### Load More

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `data` | Pass in `data` to generate the corresponding tree structure | Load More, Virtual |
| `load-more` | A callback for loading data asynchronously, returning a `Promise` | Load More |
| `block-node` | Whether the node occupies a row | Virtual |
| `checkable` | Add a checkbox before nodes | Virtual |
| `virtual-list-props` | Pass virtual list properties, pass in this parameter to turn on virtual scrolling, [VirtualListProps](#VirtualListProps) | Virtual |
<!-- demo-config-notes:end -->


- `data`: Pass in `data` to generate the corresponding tree structure
- `load-more`: A callback for loading data asynchronously, returning a `Promise`

Example source: src/tree/__demos__/load-more.vue

```vue
<template>
  <c-tree :data="treeData" :load-more="loadMore" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const treeData = ref([
  {
    label: 'Trunk 0-0',
    value: '0-0',
  },
  {
    label: 'Trunk 0-1',
    value: '0-1',
    children: [
      {
        label: 'Branch 0-1-1',
        value: '0-1-1',
      },
    ],
  },
])

const loadMore = (nodeData) => {
  return new Promise((resolve) => {
    setTimeout(() => {
      nodeData.children = [{ label: `leaf`, value: `${nodeData.key}-1`, isLeaf: true }]
      resolve()
    }, 1000)
  })
}
</script>
```

### Virtual

- `block-node`: Whether the node occupies a row
- `checkable`: Whether to add a checkbox before the node, function format is supported since `2.27.0`
- `data`: Pass in `data` to generate the corresponding tree structure
- `virtual-list-props`: Pass virtual list properties, pass in this parameter to turn on virtual scrolling, [VirtualListProps](#VirtualListProps)

Example source: src/tree/__demos__/virtual.vue

```vue
<template>
  <c-button status="primary" :style="{ marginBottom: '20px' }" @click="scrollIntoView">
    Scroll to 0-0-2-2, i.e. the 26th.
  </c-button>
  <c-tree
    ref="treeRef"
    blockNode
    checkable
    :data="treeData"
    :virtualListProps="{
      height: 200,
    }" />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

function loop(path = '0', level = 2) {
  const list = []
  for (let i = 0; i < 10; i += 1) {
    const key = `${path}-${i}`
    const treeNode: {
      label: string
      value: string
      children?: ReturnType<typeof loop>
    } = {
      label: key,
      key,
    }

    if (level > 0) {
      treeNode.children = loop(key, level - 1)
    }

    list.push(treeNode)
  }
  return list
}

const treeRef = ref()
const treeData = loop()
const scrollIntoView = () => {
  treeRef.value && treeRef.value.scrollIntoView({ value: '0-0-2-2' })
}
</script>
```

## API

### `<tree>` Props

| Parameter | Description | Type | Default |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | :-----: |
| size | Size | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` |
| block-node | Whether the node occupies a row | `boolean` | `false` |
| default-expand-all | Whether to expand the parent node by default | `boolean` | `true` |
| multiple | Whether to support multiple selection | `boolean` | `false` |
| checkable | Add a checkbox before nodes | `boolean\| ((    node: TreeNodeData,    info: {      level: number;      isLeaf: boolean;    }  ) => boolean)` | `false` |
| selectable | Whether selection is supported | `boolean\| ((    node: TreeNodeData,    info: {      level: number;      isLeaf: boolean;    }  ) => boolean)` | `true` |
| check-strictly | Whether to cancel the parent-child node association | `boolean` | `false` |
| checked-strategy | Customized backfill method <br/> all: return all selected nodes <br/> parent: return only parent node when both parent and child nodes are selected <br/> child: return only child nodes | `'all' \| 'parent' \| 'child'` | `'all'` |
| default-selected-values | Tree node selected by default | `Array<string \| number>` | `-` |
| selected-values **(v-model)** | Selected tree node | `Array<string \| number>` | `-` |
| default-checked-values | Tree node with checkbox selected by default | `Array<string \| number>` | `-` |
| checked-values **(v-model)** | Tree node with check box selected | `Array<string \| number>` | `-` |
| default-expanded-values | Nodes expanded by default | `Array<string \| number>` | `-` |
| expanded-values **(v-model)** | Expanded node | `Array<string \| number>` | `-` |
| data | Pass in `data` to generate the corresponding tree structure | `TreeNodeData[]` | `[]` |
| field-names | Specify the field name in the node data | `TreeFieldNames` | `-` |
| show-line | Whether to display the connection line | `boolean` | `false` |
| load-more | A callback for loading data asynchronously, returning a `Promise` | `(node: TreeNodeData) => Promise<void>` | `-` |
| draggable | Whether it can be dragged | `boolean` | `false` |
| allow-drop | Whether to allow release on a node when dragging | `(options: {  dropNode: TreeNodeData;  dropPosition: -1 \| 0 \| 1;}) => boolean` | `-` |
| virtual-list-props | Pass virtual list properties, pass in this parameter to turn on virtual scrolling, [VirtualListProps](#VirtualListProps) | `VirtualListProps` | `-` |
| default-expand-selected | Whether to expand the parent node of the selected node by default | `boolean` | `false` |
| default-expand-checked | Whether to expand the parent node of the checked node by default | `boolean` | `false` |
| auto-expand-parent | Whether to automatically expand the parent node of the expanded node | `boolean` | `true` |
| half-checked-values **(v-model)** | The keys of half checked. Only valid when checkable and checkStrictly | `Array<string \| number>` | `-` |
| only-check-leaf | When enabled, checkedValues is only for checked leaf nodes, and the status of the parent node is determined by the child node.(Only valid when checkable and checkStrictly is false) | `boolean` | `false` |
| animation | Whether to enable expand transition animation | `boolean` | `true` |
| action-on-node-click | The action triggered when the node is clicked | `'expand'` | `-` |

### `<tree>` Events

| Event | Description | Arguments |
| ---------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| select | Emitted when a tree node is clicked | selectedValues: `Array<string \| number>`<br>data: `{ selected?: boolean; selectedNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; }` |
| check | Emitted when a node checkbox is clicked. `halfCheckedValues`/`halfCheckedNodes` are supported since `2.19.0` | checkedValues: `Array<string \| number>`<br>data: `{ checked?: boolean; checkedNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; halfCheckedValues: (string \| number)[]; halfCheckedNodes: TreeNodeData[]; }` |
| expand | Expand/collapse | expandKeys: `Array<string \| number>`<br>data: `{ expanded?: boolean; expandNodes: TreeNodeData[]; node?: TreeNodeData; e?: Event; }` |
| drag-start | Node drag starts | ev: `DragEvent`<br>node: `TreeNodeData` |
| drag-end | Node drag ends | ev: `DragEvent`<br>node: `TreeNodeData` |
| drag-over | Node enters a drop target | ev: `DragEvent`<br>node: `TreeNodeData` |
| drag-leave | Node leaves a drop target | ev: `DragEvent`<br>node: `TreeNodeData` |
| drop | Node is dropped on a target | data: `{ e: DragEvent; dragNode: TreeNodeData; dropNode: TreeNodeData; dropPosition: number; }` |

### `<tree>` Methods

| Method | Description | Arguments | Returns |
| ------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | -------------- |
| scrollIntoView | Scroll a virtual-list item into view | options: `{ index?: number; value?: number \| string; align: 'auto' \| 'top' \| 'bottom'}` | - |
| getSelectedNodes | Get selected nodes | - | TreeNodeData[] |
| getCheckedNodes | Get checked nodes; accepts `checkedStrategy`, otherwise uses the component setting | options: `checkedStrategy?: 'all' \| 'parent' \| 'child'; includeHalfChecked?: boolean;` | TreeNodeData[] |
| getHalfCheckedNodes | Get indeterminate nodes | - | TreeNodeData[] |
| getExpandedNodes | Get expanded nodes | - | TreeNodeData[] |
| checkAll | Set all nodes’ checkbox state | checked: `boolean` | - |
| checkNode | Set specified nodes’ checkbox state | value: `TreeNodeValue \| TreeNodeValue[]`<br>checked: `boolean`<br>onlyCheckLeaf: `boolean` | - |
| selectAll | Set all nodes’ selection state | selected: `boolean` | - |
| selectNode | Set specified nodes’ selection state | value: `TreeNodeValue \| TreeNodeValue[]`<br>selected: `boolean` | - |
| expandAll | Set all nodes’ expansion state | expanded: `boolean` | - |
| expandNode | Set specified nodes’ expansion state | value: `TreeNodeValue \| TreeNodeValue[]`<br>expanded: `boolean` | - |

### `<tree>` Slots

| Slot | Description | Arguments |
| ------------- | :----------------: | -------------------- |
| label | Node content | node: `TreeNodeData` |
| extra | Render additional node content | - |
| drag-icon | Custom drag icon | node: `TreeNodeData` |
| loading-icon | Custom loading icon | TreeNodeData |
| switcher-icon | Custom switcher icon | TreeNodeData |
| icon | Custom node icon | node: `TreeNodeData` |

### TreeNodeData

| Parameter | Description | Type | Default |
| --------------- | ----------------------------------- | ------------------ | :-----: |
| value | Unique identifier | `string \| number` | `-` |
| label | Displayed node title | `string` | `-` |
| selectable | Whether selection is allowed | `boolean` | `false` |
| disabled | Whether the node is disabled | `boolean` | `false` |
| disableCheckbox | Whether the checkbox is disabled | `boolean` | `false` |
| checkable | Whether to show a checkbox | `boolean` | `false` |
| draggable | Whether it can be dragged | `boolean` | `false` |
| isLeaf | Whether this is a leaf; effective during dynamic loading | `boolean` | `false` |
| icon | Node icon | `() => VNode` | `-` |
| switcherIcon | Custom switcher icon; overrides Tree | `() => VNode` | `-` |
| loadingIcon | Custom loading icon; overrides Tree | `() => VNode` | `-` |
| dragIcon | Custom drag icon; overrides Tree | `() => VNode` | `-` |
| children | Children | `TreeNodeData[]` | `-` |

### TreeFieldNames

| Parameter | Description | Type | Default |
| --------------- | ----------------------------------------------- | -------- | :---------------: |
| value | TreeNodeData field mapped to value | `string` | `value` |
| label | TreeNodeData field mapped to label | `string` | `label` |
| disabled | TreeNodeData field mapped to disabled | `string` | `disabled` |
| children | TreeNodeData field mapped to children | `string` | `children` |
| isLeaf | TreeNodeData field mapped to isLeaf | `string` | `isLeaf` |
| disableCheckbox | TreeNodeData field mapped to disableCheckbox | `string` | `disableCheckbox` |
| checkable | TreeNodeData field mapped to checkable | `string` | `checkable` |
| icon | TreeNodeData field mapped to icon | `string` | `checkable` |

### VirtualListProps

| Parameter | Description | Type | Default |
| ------------------ | ------------------------------------------------------------------ | ------------------ | :-----: |
| height | Viewport height | `number \| string` | `-` |
| threshold | Item-count threshold for virtual scrolling; counts below it do not enable virtualization | `number` | `-` |
| isStaticItemHeight | Removed fixed-height flag; use `fixedSize` | `boolean` | `false` |
| fixedSize | Whether item heights are fixed | `boolean` | `false` |
| estimatedSize | Estimated item height when heights vary | `number` | `-` |
| buffer | Number of items premounted beyond viewport boundaries | `number` | `10` |

### Type definitions

The component exports the following types

```ts
import type { TreeInstance } from '@cedar-design/ui'
```

### Five densities and icons

xs/sm/md/lg/xl consume their icon-size, font-size, line-height and title-padding-vertical. Icon sizes also determine expansion-button/indent geometry; show-line follows the matching line height.

| Variable | Default |
| --- | --- |
| `--c-tree-size-xl-icon-size` | `var(--c-size-4)` |
| `--c-tree-size-xl-font-size` | `var(--c-sys-font-size-lg)` |
| `--c-tree-size-xl-line-height` | `var(--c-size-xl)` |
| `--c-tree-size-xl-title-padding-vertical` | `12px` |

### Node fields and business values

Nodes default to `{ value, label, children }`. `value` is a tree-wide unique string/number, including `0`; `label` is display content. Map other backend fields with `fieldNames: { value: 'id', label: 'text', children: 'items' }` without changing backend data. Declarative child `name`, Vue `:key` and Table `rowKey` retain separate meanings.

Independent Tree state uses `selectedValues/defaultSelectedValues`, `checkedValues/defaultCheckedValues`, `halfCheckedValues` and `expandedValues/defaultExpandedValues`, updated through corresponding named v-models. `check` event indeterminate sets use `halfCheckedValues`. Node content uses `label`; TreeSelect forwards `tree-slot-label`. `scrollIntoView({ value })` locates business values; explicit `index` remains a zero-based virtual-list array `index`.


| Focus outline token | Default |
| --- | --- |
| `--c-tree-focus-outline-width` | `2px` |

## Reading direction and keyboard interaction

Tree mirrors indentation, connectors, disclosure icons and horizontal branch keys. Up/down and Home/End navigate enabled visible nodes independently of selection. Enter selects; Space checks a checkable node or selects it. The tree keeps DOM focus through virtual scrolling using aria-activedescendant. Vertical drop semantics remain unchanged. Embedded TreeSelect retains its own focus owner.

---

Document: llms/en-US/components/trigger.md

<!-- Source: src/trigger/README.en-US.md; locale: en-US; page: /en/components/trigger/ -->

# Trigger

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `trigger="click"`, `:popup-offset="10"`, `show-arrow`.

Example source: src/trigger/__demos__/basic.vue

```vue
<template>
  <div class="trigger-demo">
    <c-trigger trigger="click" :popup-offset="10" show-arrow>
      <c-button>点击打开</c-button>
      <template #content>
        <div class="trigger-demo__panel">Trigger 只负责浮层行为，面板外观由使用者决定。</div>
      </template>
    </c-trigger>
  </div>
</template>

<style scoped>
.trigger-demo {
  display: flex;
  justify-content: center;
  padding: calc(var(--c-sys-space-8) * 2) var(--c-sys-space-6);
}

.trigger-demo__panel {
  max-width: 260px;
  padding: var(--c-sys-space-5) var(--c-sys-space-6);
  color: var(--c-sys-color-content-primary);
  background: var(--c-sys-color-surface-overlay);
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-md);
}
</style>
```

## Layout and arrangement

### Placement

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `trigger` | Trigger modes; may be combined | Placement |
| `placement` | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Placement |
| `popup-offset` | Outward distance along placement's main axis | Placement |
| `show-arrow` | Render a decorative arrow | Placement |
<!-- demo-config-notes:end -->


- `placement`: Chooses the position relative to the trigger.

Example source: src/trigger/__demos__/placement.vue

```vue
<script setup lang="ts">
const placements = ['top', 'right', 'bottom', 'left'] as const
</script>

<template>
  <div class="trigger-placement-demo">
    <c-trigger v-for="placement in placements" :key="placement" trigger="click" :placement="placement" :popup-offset="10" show-arrow>
      <c-button variant="outline">{{ placement }}</c-button>
      <template #content><div class="trigger-placement-demo__panel">{{ placement }}</div></template>
    </c-trigger>
  </div>
</template>

<style scoped>
.trigger-placement-demo {
  display: grid;
  grid-template-columns: repeat(2, minmax(100px, 1fr));
  gap: calc(var(--c-sys-space-8) * 2);
  padding: calc(var(--c-sys-space-8) * 3);
}

.trigger-placement-demo__panel {
  padding: var(--c-sys-space-4) var(--c-sys-space-5);
  color: var(--c-sys-color-content-primary);
  background: var(--c-sys-color-surface-overlay);
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-sm);
}
</style>
```

## Interaction and control

### Controlled

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `open` | Controlled open state | Controlled |
| `trigger` | Trigger modes; may be combined | Controlled |
| `placement` | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | Controlled |
| `popup-offset` | Outward distance along placement's main axis | Controlled |
| `popup-translate` | Screen-axis offset, or per-placement offsets | Controlled |
<!-- demo-config-notes:end -->


- `placement`: Chooses the position relative to the trigger.

Example source: src/trigger/__demos__/controlled.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'

const open = ref(false)
</script>

<template>
  <div class="trigger-controlled-demo">
    <c-space>
      <c-button @click="open = true">外部打开</c-button>
      <c-button variant="outline" @click="open = false">外部关闭</c-button>
    </c-space>
    <c-trigger v-model:open="open" trigger="click" placement="bottom-start" :popup-offset="10" :popup-translate="[16, 0]">
      <c-button variant="text">受控触发元素</c-button>
      <template #content><div class="trigger-controlled-demo__panel">open = {{ open }}</div></template>
    </c-trigger>
  </div>
</template>

<style scoped>
.trigger-controlled-demo {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: var(--c-sys-space-8);
  padding: calc(var(--c-sys-space-8) * 2) var(--c-sys-space-6);
}

.trigger-controlled-demo__panel {
  padding: var(--c-sys-space-5) var(--c-sys-space-6);
  color: var(--c-sys-color-content-primary);
  background: var(--c-sys-color-surface-overlay);
  border: 1px solid var(--c-sys-color-border-default);
  border-radius: var(--c-sys-radius-sm);
}
</style>
```

## API

### `<Trigger>` Props

| Prop | Description | Type | Default |
| --- | --- | --- | --- |
| dir | Reading direction; inherits the source scope when omitted. Physical left/right placements keep their meaning. | `ReadingDirection` (`ltr` / `rtl`) | — |
| open | Controlled open state | `boolean` | `-` |
| default-open | Initial uncontrolled state | `boolean` | `false` |
| trigger | Trigger modes; may be combined | `hover \| click \| focus \| contextMenu \| manual \| TriggerEvent[]` | `hover` |
| disabled | Prevent opening | `boolean` | `false` |
| reference | External reference element; defaults to the first actual element in the default slot | `string \| HTMLElement \| SVGElement` | `-` |
| placement | Preferred popup side relative to the trigger, default bottom. With the default auto-fit-position enabled, Trigger may flip and constrain it to the viewport when space is limited; this is not a fixed final position | `TriggerPlacement` | `bottom` |
| strategy | Positioning strategy | `absolute \| fixed` | `absolute` |
| cover | Cover the reference on the main axis | `boolean` | `false` |
| popup-offset | Outward distance along placement's main axis | `number` | `0` |
| popup-translate | Screen-axis offset, or per-placement offsets | `[number, number] \| Partial<Record<TriggerPlacement, [number, number]>>` | `-` |
| align-point | Use pointer coordinates as a virtual reference | `boolean` | `false` |
| popup-container | Mount container; `false` renders in place | `string \| HTMLElement \| false` | `body` |
| auto-fit-position | Flip and constrain to the viewport when space is insufficient | `boolean` | `true` |
| auto-fit-popup-width | Match popup width to the reference | `boolean` | `false` |
| auto-fit-popup-min-width | Match minimum popup width to the reference | `boolean` | `false` |
| auto-fix-position | Reposition automatically on size changes | `boolean` | `true` |
| update-at-scroll | Reposition while scrolling | `boolean` | `false` |
| scroll-to-close | Close when scrolling exceeds the threshold | `boolean` | `false` |
| scroll-to-close-distance | Close threshold | `number` | `0` |
| show-arrow | Render a decorative arrow | `boolean` | `false` |
| hide-empty | Do not render when content is empty | `boolean` | `false` |
| prevent-focus | Prevent popup mousedown from taking focus | `boolean` | `false` |
| unmount-on-close | Unmount content after the leave transition | `boolean` | `true` |
| animation-name | Vue Transition name | `string` | `trigger-fade` |
| duration | Transition duration | `number \| { enter: number; leave: number }` | `-` |
| auto-fit-transform-origin | Derive transform origin from final placement | `boolean` | `false` |
| opened-class | Class added to the first reference node while open | `ClassName` | `-` |
| popup-class / popup-style | Positioning-layer class/style | `ClassName / CSSProperties` | `-` |
| content-class / content-style | Content-layer class/style | `ClassName / CSSProperties` | `-` |
| arrow-class / arrow-style | Arrow class/style | `ClassName / CSSProperties` | `-` |
| mouse-enter-delay / mouse-leave-delay | Hover open/close delay in ms | `number` | `100 / 100` |
| focus-delay | Focus-open delay in ms | `number` | `0` |
| popup-hover-stay | Keep open when the pointer enters the popup | `boolean` | `true` |
| blur-to-close | Close on blur | `boolean` | `true` |
| close-on-click-reference | Close on another reference click | `boolean` | `true` |
| click-outside-to-close | Close on outside click | `boolean` | `true` |
| esc-to-close | Close on Escape | `boolean` | `true` |
| restore-focus | Restore reference focus after closing is accepted | `boolean` | `true` |

### Events

| Event | Description | Arguments |
| --- | --- | --- |
| update:open | Controlled update request from user interaction | `open: boolean` |
| open-change | User-interaction request notification | `open: boolean` |
| open / close | Actual enter/leave begins | `-` |
| opened / closed | Enter/leave transition completes | `-` |
| click-outside | The topmost popup receives an outside click | `event: Event` |
| resize | Reference size changes | `-` |

### Slots

| Slot | Description |
| --- | --- |
| default | Reference node |
| content | Popup content |

### Expose

`open()`、`close()`、`resize()`、`allowClose()`、`getReference()`、`setReference(reference?)`、`focusReference()`、`isTopLayer(event?)`。

## Keyboard and accessibility

`trigger="focus"` supports keyboard focus. `esc-to-close` lets only the topmost popup handle Escape. Trigger does not assign `role`, `aria-describedby` or business labels; semantic wrappers such as Tooltip, Popover and Menu must supply them.

## Public CSS variables

These are actual :root defaults. Prefer component variables for business customization; internal positioning variables are not public API.

| Variable | Default | Meaning and use case |
| --- | --- | --- |
| `--c-trigger-arrow-background` | `var(--c-sys-color-surface-overlay)` | Standalone Trigger arrow background; wrappers use their own variables |
| `--c-trigger-arrow-size` | `var(--c-sys-space-4)` | Arrow square size |
| `--c-trigger-arrow-radius` | `var(--c-sys-radius-sm)` | Arrow border radius |
| `--c-trigger-transition-duration` | `var(--c-sys-motion-duration-fast)` | Default Trigger fade duration |
| `--c-trigger-transition-easing` | `var(--c-sys-motion-easing-standard)` | Default Trigger easing |

Tooltip/Popover define arrow appearance themselves. Override their component variables rather than Trigger arrow-background.

With Teleport, variables must be in the actual popup scope, for example through `popup-style`. Trigger-button variables do not automatically inherit into popups.

### Reduced motion

Built-in CSS transitions follow `prefers-reduced-motion: reduce`. Removing transitions does not change final visibility, selected/expanded state or event semantics. Applications control custom animations inside slots.


### Placement semantics and configuration

placement is a preferred side; final placement may change while auto-fit-position is true (the default). It is not a position coordinate. top-start is anchor-side alignment, whereas top-left denotes a container corner. Current Trigger start/end follows physical cross-axis geometry; automatic RTL mirroring is not promised.

## Native event modifiers on the reference

Native click, mouseenter, mouseleave, focusin, focusout and contextmenu listeners, including .once, .capture and .passive, belong to the actual reference element rather than the popup. Updating a consumed once callback does not rearm it; replacing the reference or removing and readding the listener starts a new native lifetime. Suspension and unmount detach listeners. Listener promises do not control opening or loading; errors follow Vue event error handling.

---

Document: llms/en-US/components/typography.md

<!-- Source: src/typography/README.en-US.md; locale: en-US; page: /en/components/typography/ -->

# Typography

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `bold`, `:heading="2"`, `mark`, `underline`.

Example source: src/typography/__demos__/basic.vue

```vue
<template>
  <c-typography>
    <c-typography-title>Design system</c-typography-title>
    <c-typography-paragraph>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design.
    </c-typography-paragraph>
    <c-typography-paragraph>
      In some cases, the direct construction of an object without an explicit prior plan (such as in
      craftwork, some engineering, coding, and graphic design) may also be considered
      <c-typography-text bold>to be a design activity.</c-typography-text>
    </c-typography-paragraph>
    <c-typography-title :heading="2">Cedar Design</c-typography-title>
    <c-typography-paragraph>
      The component library defines a set of default particle variables, and a custom theme is to
      <c-typography-text mark>customize</c-typography-text> and
      <c-typography-text underline>overwrite</c-typography-text> this variable list.
    </c-typography-paragraph>
    <c-typography-paragraph blockquote>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a
      <c-typography-text code>prototype</c-typography-text>,
      <c-typography-text code>product</c-typography-text> or
      <c-typography-text code>process</c-typography-text>. The verb to design expresses the process of
      developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph mark underline delete>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process.
    </c-typography-paragraph>
    <c-typography-paragraph>
      <ul>
        <li>
          Architectural blueprints
          <ul>
            <li>Architectural blueprints</li>
          </ul>
        </li>
        <li>Engineering drawings</li>
        <li>Business processes</li>
      </ul>
    </c-typography-paragraph>
    <c-typography-paragraph>
      <ol>
        <li>Architectural blueprints</li>
        <li>Engineering drawings</li>
        <li>Business processes</li>
      </ol>
    </c-typography-paragraph>
  </c-typography>
</template>
```

## Content and presentation

### Title

Preview configuration: `:heading="2"`, `:heading="3"`, `:heading="4"`, `:heading="5"`.

Example source: src/typography/__demos__/title.vue

```vue
<template>
  <c-typography>
    <c-typography-title>H1. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="2">H2. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="3">H3. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="4">H4. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="5">H5. The Pragmatic Romanticism</c-typography-title>
    <c-typography-title :heading="6">H6. The Pragmatic Romanticism</c-typography-title>
  </c-typography>
</template>
```

### Text

Preview configuration: `status="secondary"`, `status="primary"`, `status="success"`, `status="warning"`.

Example source: src/typography/__demos__/text.vue

```vue
<template>
  <c-space direction="column" :size="10">
    <c-typography-text>Cedar Design</c-typography-text>
    <c-typography-text status="secondary">Secondary</c-typography-text>
    <c-typography-text status="primary">Primary</c-typography-text>
    <c-typography-text status="success">Success</c-typography-text>
    <c-typography-text status="warning">Warning</c-typography-text>
    <c-typography-text status="danger">Danger</c-typography-text>
    <c-typography-text bold>Bold</c-typography-text>
    <c-typography-text disabled>Disabled</c-typography-text>
    <c-typography-text mark>Mark</c-typography-text>
    <c-typography-text underline>Underline</c-typography-text>
    <c-typography-text delete>Line through</c-typography-text>
    <c-typography-text code>Code snippet</c-typography-text>
  </c-space>
</template>
```

### Paragraph

Preview configuration: `:heading="5"`, `status="secondary"`, `spacing="close"`.

Example source: src/typography/__demos__/paragraph.vue

```vue
<template>
  <c-typography>
    <c-typography-title :heading="5">Default</c-typography-title>
    <c-typography-paragraph>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. In some cases, the direct construction of an object without an explicit prior plan
      (such as in craftwork, some engineering, coding, and graphic design) may also be considered to
      be a design activity.
    </c-typography-paragraph>
    <c-typography-title :heading="5">Secondary</c-typography-title>
    <c-typography-paragraph status="secondary">
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. In some cases, the direct construction of an object without an explicit prior plan
      (such as in craftwork, some engineering, coding, and graphic design) may also be considered to
      be a design activity.
    </c-typography-paragraph>
    <c-typography-title :heading="5">Spacing default</c-typography-title>
    <c-typography-paragraph>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. In some cases, the direct construction of an object without an explicit prior plan
      (such as in craftwork, some engineering, coding, and graphic design) may also be considered to
      be a design activity.
    </c-typography-paragraph>
    <c-typography-title :heading="5">Spacing close</c-typography-title>
    <c-typography-paragraph status="secondary" spacing="close">
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design.
    </c-typography-paragraph>
  </c-typography>
</template>
```

### Ellipsis

Preview configuration: `:heading="4"`, `ellipsis`, `:ellipsis="{
        rows: 2,
        showTooltip: true,
      }"`, `:ellipsis="{
        rows: 2,
        showTooltip: true,
        css: true,
      }"`.

Example source: src/typography/__demos__/ellipsis.vue

```vue
<template>
  <div>
    <c-typography-title :heading="4" ellipsis>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process.
    </c-typography-title>
    <c-typography-paragraph
      :ellipsis="{
        rows: 2,
        showTooltip: true,
      }"
    >
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph
      :ellipsis="{
        rows: 2,
        showTooltip: true,
        css: true,
      }"
    >
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph
      :ellipsis="{
        suffix: '--Cedar Design',
        rows: 2,
        expandable: true,
        showTooltip: {
          type: 'popover',
          props: {
            style: { maxWidth: '500px' },
          },
        },
      }"
    >
      <template #expand-node="{ expanded }">
        {{ expanded ? '' : 'More' }}
      </template>
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
    <c-typography-paragraph
      :ellipsis="{
        suffix: '--Cedar Design',
        rows: 3,
        expandable: true,
      }"
    >
      A design is a plan or specification for the construction of an object or system or for the
      implementation of an activity or process, or the result of that plan or specification in the
      form of a prototype, product or process. The verb to design expresses the process of developing
      a design. The verb to design expresses the process of developing a design. A design is a plan
      or specification for the construction of an object or system or for the implementation of an
      activity or process, or the result of that plan or specification in the form of a prototype,
      product or process. The verb to design expresses the process of developing a design. The verb
      to design expresses the process of developing a design.
    </c-typography-paragraph>
  </div>
</template>
```

## Interaction and control

### Operations

Preview configuration: `copyable`, `editable`, `v-model:edit-text="str"`.

Example source: src/typography/__demos__/operations.vue

```vue
<template>
  <c-typography>
    <c-typography-paragraph copyable>Click the icon to copy this text.</c-typography-paragraph>
    <c-typography-paragraph editable v-model:edit-text="str">
      {{ str }}
    </c-typography-paragraph>
  </c-typography>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const str = ref('Click the icon to edit this text.')
</script>
```

## Lifecycle and edge cases

### Scheduler Lifecycle

Example source: src/typography/__demos__/scheduler-lifecycle.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import { TypographyText } from "../index";

const active = ref(true);
const mounted = ref(true);
const copies = ref(0);
</script>

<template>
  <div>
    <c-button html-type="button" @click="active = !active"
      >切换 KeepAlive</c-button
    >
    <c-button html-type="button" @click="mounted = !mounted"
      >卸载／挂载</c-button
    >
    <p>复制通知：{{ copies }}。连续复制后等待 3 秒，或复制后停用再激活。</p>
    <KeepAlive v-if="mounted">
      <TypographyText
        v-if="active"
        copyable
        :ellipsis="{ rows: 1, expandable: true }"
        @copy="copies++"
      >
        Typography
        测量调度与复制反馈生命周期示例：重复复制只保留最新反馈，停用和卸载取消待处理工作。
      </TypographyText>
    </KeepAlive>
  </div>
</template>
```

## API

### Common Props

`Typography.Title`, `Typography.Paragraph` and `Typography.Text` share these props.

| Prop | Description | Type | Default |
| --- | --- | --- | :---: |
| status | Semantic text status | `SemanticStatus` | `-` |
| bold | Bold | `boolean` | `false` |
| mark | Mark styling | `boolean \| { color: string }` | `false` |
| underline | Underline styling | `boolean` | `false` |
| delete | Strikethrough styling | `boolean` | `false` |
| code | Code-block styling | `boolean` | `false` |
| disabled | Whether to disable link | `boolean` | `false` |
| editable | Enable editing | `boolean` | `false` |
| editing **(v-model)** | Whether currently editing | `boolean` | `-` |
| default-editing | Default editing state | `boolean` | `false` |
| edit-text **(v-model)** | Edited text | `string` | `-` |
| copyable | Enable copying | `boolean` | `false` |
| copy-text | Text to copy | `string` | `-` |
| copy-delay | Delay in ms before the copy button becomes clickable again after successful copying | `number` | `3000` |
| ellipsis | Automatic truncation; see EllipsisConfig | `boolean \| EllipsisConfig` | `false` |
| edit-tooltip-props | Edit-button Tooltip options | `object` | `-` |
| copy-tooltip-props | Copy-button Tooltip options | `object` | `-` |

### Common Events

| Event | Description | Arguments |
| --- | --- | --- |
| edit-start | Editing starts | `-` |
| change | Edited content changes | `text: string` |
| edit-end | Editing ends | `-` |
| copy | Copy | `text: string` |
| ellipsis | Ellipsis-state change | `isEllipsis: boolean` |
| expand | Expand/collapse event | `expanded: boolean` |

### Common Slots

| Slot | Description | Arguments |
| --- | --- | --- |
| expand-node | Custom expand/collapse buttons | `expanded: boolean` |
| copy-icon | Custom copy-button icon | `copied: boolean` |
| copy-tooltip | Custom copy-button tooltip content | `copied: boolean` |

### `<TypographyTitle>` Props

| Prop | Description | Type | Default |
| --- | --- | --- | :---: |
| heading | Heading level, equivalent to `h1`/`h2`/`h3`/`h4`/`h5`/`h6` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` |

### `<TypographyParagraph>` Props

| Prop | Description | Type | Default |
| --- | --- | --- | :---: |
| blockquote | Block quotation | `boolean` | `false` |
| spacing | Paragraph line height; use the default for long text and `close` for short text | `'default' \| 'close'` | `'default'` |

### EllipsisConfig

| Prop | Description | Type | Default |
| --- | --- | --- | :---: |
| rows | Number of displayed lines before truncation | `number` | `1` |
| expandable | Whether expand/collapse is supported | `boolean` | `false` |
| ellipsisStr | Ellipsis | `string` | `'...'` |
| suffix | Suffix | `string` | `-` |
| showTooltip | Popup options for truncated content | `boolean \| { type: 'tooltip' \| 'popover'; props: Record<string, any> }` | `false` |
| css | Use CSS truncation; currently does not support expansion, custom ellipsis or suffix | `boolean` | `false` |

### Type definitions

The component exports the following types:

```ts
import type {
  TypographyInstance,
  TypographyParagraphInstance,
  TypographyTitleInstance,
  TypographyTextInstance,
  EllipsisConfig,
} from '@cedar-design/ui'
```

---

Document: llms/en-US/components/upload.md

<!-- Source: src/upload/README.en-US.md; locale: en-US; page: /en/components/upload/ -->

# Upload

Upload UI and a headless useUploader composable. The application owns transport and server file deletion.

## Replacement and video metadata

Enable reupload for per-item replacement, or call replace(file, replacementFile). Validation and beforeRemove rejection preserve the original item. An accepted replacement occupies the same position with a new UID and emits replace/change, not remove. A failed new upload can be retried; it does not automatically restore the old server file or delete it.

Video duration is expressed in seconds and rendered as mm:ss or h:mm:ss. Local files are inspected; remote echoes provide duration from application metadata. Temporary resources are released on success, error, cancellation and disposal.

| Variable                                | Default                                  |
| --------------------------------------- | ---------------------------------------- |
| --c-upload-gap                          | var(--c-sys-space-4)                     |
| --c-upload-trigger-min-height           | var(--c-sys-control-height-md)           |
| --c-upload-trigger-padding-horizontal   | var(--c-sys-space-6)                     |
| --c-upload-trigger-draggable-min-height | calc(var(--c-sys-control-height-md) * 2) |
| --c-upload-card-size                    | calc(var(--c-sys-control-height-md) * 2) |
| --c-upload-item-min-height              | var(--c-sys-control-height-md)           |
| --c-upload-item-padding                 | var(--c-sys-space-4)                     |
| --c-upload-thumb-size                   | var(--c-sys-control-height-lg)           |
| --c-upload-border-radius                | var(--c-sys-radius-md)                   |
| --c-upload-border-color                 | var(--c-sys-color-border-default)        |
| --c-upload-background                   | var(--c-sys-color-surface-default)       |
| --c-upload-text-color                   | var(--c-sys-color-content-primary)       |
| --c-upload-secondary-text-color         | var(--c-sys-color-content-secondary)     |
| --c-upload-hover-background             | var(--c-sys-color-state-hover)           |
| --c-upload-active-color                 | var(--c-sys-color-action-primary)        |
| --c-upload-error-color                  | var(--c-sys-color-content-danger)        |
| --c-upload-action-size                  | var(--c-sys-control-touch-target)        |
| --c-upload-progress-height              | var(--c-sys-space-2)                     |
| --c-upload-disabled-opacity             | .56                                      |
| --c-upload-font-size                    | var(--c-sys-font-size-md)                |

## Basic examples

### Read Only

Example source: src/upload/__demos__/read-only.vue

```vue
<script setup>
import { ref } from 'vue'
const files = ref([])
const last = ref('')
</script>
<template><div><p>不配置 action/custom-request：只读取文件，不发送请求。</p><c-upload v-model="files" multiple list-type="picture" @read="file => last = file.name" /><p>最近读取：{{ last }}</p></div></template>
```

## Appearance and states

### State Controls

Example source: src/upload/__demos__/state-controls.vue

```vue
<script setup>
import { ref } from "vue";

const readonly = ref(false);
const disabled = ref(false);
const chooseCount = ref(0);
const previewCount = ref(0);
const initialFile = {
  uid: "state-image",
  name: "state-example.svg",
  type: "image/svg+xml",
  url: "data:image/svg+xml,%3Csvg xmlns=%22http://www.w3.org/2000/svg%22 width=%22120%22 height=%22120%22%3E%3Crect width=%22120%22 height=%22120%22 fill=%22%236750a4%22/%3E%3C/svg%3E",
  status: "success",
  percent: 100,
};
const files = ref([{ ...initialFile }]);
function choose() {
  chooseCount.value++;
}
function restore() {
  files.value = [{ ...initialFile }];
}
</script>

<template>
  <section class="upload-state-demo">
    <div class="controls">
      <c-checkbox v-model="readonly"> Readonly upload</c-checkbox>
      <c-checkbox v-model="disabled"> Disabled upload</c-checkbox>
      <c-button html-type="button" @click="restore">Restore sample</c-button>
    </div>
    <p>Local selection callback only; no file chooser or network request.</p>
    <c-upload
      v-model="files"
      data-testid="state-upload"
      :readonly="readonly"
      :disabled="disabled"
      :request-choose="choose"
      @preview="previewCount++"
    />
    <p role="status">
      Files: {{ files.length }}; choose: {{ chooseCount }}; preview:
      {{ previewCount }}
    </p>
  </section>
</template>

<style scoped>
.controls {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 12px;
}
.controls label {
  display: inline-flex;
  align-items: center;
  gap: 4px;
}
</style>
```

### State Lab

Example source: src/upload/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref([]);
const __demoState = __demoReactive({ disabled: false, readonly: false });
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
    </c-space>
    <c-upload
      v-model="value"
      :auto-upload="false"
      v-bind="__demoState"
    ></c-upload>
  </c-space>
</template>
```

### Api Review

### Props

| Prop                                                         | Type                                                     | Default/Description                                                               |
| ------------------------------------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------------- |
| model-value / default-value                                  | UploadFileItem[]                                         | Controlled value / initial uncontrolled value []                                  |
| accept / capture                                             | string / native capture                                  | Unspecified                                                                       |
| multiple / directory / draggable                             | boolean                                                  | false                                                                             |
| disabled / readonly                                          | boolean                                                  | undefined; inherits Form; explicit false wins                                     |
| action / method                                              | string                                                   | None / post                                                                       |
| headers / data                                               | object or async(file) => object                          | Request preparation remains cancellable                                           |
| name                                                         | string / (file) => string                                | file                                                                              |
| with-credentials                                             | boolean                                                  | false                                                                             |
| custom-request                                               | (UploadRequestOptions) => UploadRequest / Promise / void | Custom transport; may return an abort handle                                      |
| auto-upload                                                  | boolean                                                  | true; starts only when action or custom-request is provided                       |
| max-files / max-file-size / max-total-size                   | number                                                   | Unspecified; sizes are bytes; max-files applies when greater than zero            |
| resolve-type                                                 | file / data-url / object-url                             | object-url; all files get a URL and images also get thumbnailUrl                  |
| create-thumbnail-url                                         | (options) => string / Promise                            | Custom URLs are caller-owned and are not automatically revoked                    |
| before-add                                                   | async(files) => File[]                                   | Filter or replace a batch                                                         |
| before-read                                                  | async(file) => boolean / File                            | false/rejection rejects; replacement files are revalidated                        |
| before-upload                                                | async(item) => boolean / File / Blob                     | false/rejection cancels preparation; replacements are revalidated                 |
| before-remove                                                | async(item,list) => boolean                              | false/rejection keeps the file                                                    |
| is-success-response                                          | (xhr,item) => boolean                                    | HTTP 2xx by default                                                               |
| request-choose                                               | (chooseFile,event) => void / Promise                     | Own file selection; errors do not automatically fall back to a native file picker |
| list-type                                                    | text / picture / picture-card                            | text; supported on both platforms                                                 |
| image-fit                                                    | fill / contain / cover / none / scale-down               | cover; item.fit takes priority                                                    |
| preview                                                      | boolean                                                  | true                                                                              |
| show-file-list / show-upload-button / show-remove-button     | boolean                                                  | true                                                                              |
| show-retry-button / show-cancel-button / show-preview-button | boolean                                                  | true                                                                              |
| show-download-button                                         | boolean                                                  | false; unavailable while interaction is disabled                                  |
| elevation / ripple                                           | boolean or number / boolean                              | false / true                                                                      |

### Custom Surface

Example source: src/upload/__demos__/custom-surface.vue

```vue
<script setup>
import { ref } from 'vue'
const files = ref([])
const message = ref('')
const preview = (file, event) => { event.preventDefault(); message.value = file.name }
</script>
<template><div><c-upload v-model="files" list-type="picture-card" multiple @preview="preview"><template #trigger><span>选择图片</span></template><template #remove-button="{ remove }"><c-button variant="text" @click="remove">删除</c-button></template></c-upload><p>自定义预览：{{ message }}</p></div></template>
```

## File sources and validation

### Directory

Example source: src/upload/__demos__/directory.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import type { UploadFileItem } from '@cedar-design/ui'
const files = ref<UploadFileItem[]>([])
</script>
<template>
  <c-space direction="column">
    <p>选择目录后查看文件列表；本例只读取本地文件，不发送请求。目录选择取决于浏览器与系统文件选择器，移动设备可使用普通多选入口。</p>
    <p>目录选择</p>
    <c-upload v-model="files" directory multiple />
    <p>普通文件多选</p>
    <c-upload multiple />
  </c-space>
</template>
```

### Clipboard

Example source: src/upload/__demos__/clipboard.vue

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { useUploader, type UploadFileItem } from '@cedar-design/ui'
const files = ref<UploadFileItem[]>([])
const message = ref('')
const rejectionMessages: Record<string, string> = { 'max-files': '最多接收 3 张图片', 'max-file-size': '单张图片不能超过 1 MiB', accept: '仅支持图片文件' }
const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: value => { files.value = value },
  accept: () => 'image/*',
  maxFiles: () => 3,
  maxFileSize: () => 1024 * 1024,
  autoUpload: () => false,
  onRejected: rejected => { message.value = rejected.map(item => rejectionMessages[item.reason] ?? '文件未能读取，请重新选择').join(', ') },
})
function paste(event: ClipboardEvent) {
  const incoming = Array.from(event.clipboardData?.files ?? [])
  if (!incoming.length) return
  event.preventDefault()
  message.value = ''
  uploader.addFiles(incoming)
}
function addExample() {
  message.value = ''
  uploader.addFiles([new File(['<svg xmlns="http://www.w3.org/2000/svg" width="8" height="8"/>'], 'local-example.svg', { type: 'image/svg+xml' })])
}
function reset() { uploader.reset(); message.value = '' }
</script>
<template>
  <c-space direction="column">
    <p>将剪贴板图片粘贴到输入区。最多 3 张，每张不超过 1 MiB；只读取文件，不上传。普通文本粘贴仍按原生输入处理。</p>
    <c-textarea placeholder="在这里粘贴图片或文本" @paste="paste" />
    <c-space wrap>
      <c-button @click="addExample">加入本地示例图片</c-button>
      <c-button @click="reset">清空列表</c-button>
    </c-space>
    <p role="status">已接收 {{ files.length }} 个文件。{{ message }}</p>
    <ul><li v-for="file in files" :key="file.uid">{{ file.name }}</li></ul>
  </c-space>
</template>
```

### Replacement Validation

Example source: src/upload/__demos__/replacement-validation.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from "vue";
import { useUploader } from "@cedar-design/ui";

const files = ref([]);
const readDataUrl = ref(false);
const readObjectUrl = ref(false);
const pauseThumbnail = ref(false);
const pendingThumbnails = shallowRef([]);
const decoded = ref(0);
const reasons = ref([]);
const replacements = new WeakMap();
const maxFileSize = 1048576;
const maxTotalSize = 2097152;
const maxFiles = 3;
const svg =
  '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16"><rect width="16" height="16" fill="#4caf50"/></svg>';
let sequence = 0;

function replace(file) {
  const mode = replacements.get(file);
  if (mode === "type") {
    return new File(["text replacement"], file.name.replace(".svg", ".txt"), {
      type: "text/plain",
    });
  }
  if (mode === "size") {
    return new File([new Uint8Array(maxFileSize + 1)], file.name, {
      type: file.type,
    });
  }
  return new File([file], file.name, { type: file.type });
}

const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: (value) => {
    files.value = value;
  },
  accept: () => "image/*",
  maxFiles: () => maxFiles,
  createThumbnailUrl: () =>
    pauseThumbnail.value
      ? () =>
          new Promise((resolve, reject) => {
            pendingThumbnails.value = [
              ...pendingThumbnails.value,
              { resolve, reject },
            ];
          })
      : undefined,
  maxFileSize: () => maxFileSize,
  maxTotalSize: () => maxTotalSize,
  resolveType: () =>
    readObjectUrl.value
      ? "object-url"
      : readDataUrl.value
        ? "data-url"
        : "file",
  beforeRead: () => replace,
  onRejected: (items) => {
    reasons.value = items.map((item) => item.reason);
  },
});

function probe(mode) {
  reasons.value = [];
  const payload = mode === "total" ? svg.padEnd(786432, " ") : svg;
  const file = new File([payload], `sample-${++sequence}.svg`, {
    type: "image/svg+xml",
  });
  replacements.set(file, mode);
  return uploader.addFiles([file]);
}

function reset() {
  uploader.reset();
  decoded.value = 0;
  reasons.value = [];
}
function settleThumbnail(fail = false, latest = false) {
  const tasks = [...pendingThumbnails.value];
  const task = latest ? tasks.pop() : tasks.shift();
  if (!task) return;
  pendingThumbnails.value = tasks;
  if (fail) task.reject(new Error("Local thumbnail failure"));
  else task.resolve("data:image/svg+xml," + encodeURIComponent(svg));
}
function cleanupThumbnails() {
  const tasks = pendingThumbnails.value;
  pendingThumbnails.value = [];
  tasks.forEach((task) => task.resolve(undefined));
}
onBeforeUnmount(cleanupThumbnails);
onDeactivated(cleanupThumbnails);
</script>

<template>
  <div class="upload-read-demo">
    <p class="thumbnail-pending">
      Pending thumbnails: {{ pendingThumbnails.length }}
    </p>
    <c-button
      html-type="button"
      :disabled="!pendingThumbnails.length"
      @click="settleThumbnail(false, true)"
    >
      返回最新缩略图
    </c-button>
    <c-button
      html-type="button"
      :disabled="!pendingThumbnails.length"
      @click="settleThumbnail()"
      >返回最早缩略图</c-button
    >
    <c-button
      html-type="button"
      :disabled="!pendingThumbnails.length"
      @click="settleThumbnail(true)"
      >拒绝最早缩略图</c-button
    >
    <c-checkbox v-model="readDataUrl" edit-mode="direct"
      >使用原生 FileReader 读取为 data-url</c-checkbox
    >
    <c-checkbox v-model="readObjectUrl" edit-mode="direct"
      >使用原生 Blob/object-url（优先）</c-checkbox
    >
    <output
      >Blob URLs:
      {{ files.filter((file) => file.url?.startsWith("blob:")).length }}</output
    >
    <p role="status">
      Data URLs:
      {{ files.filter((file) => file.url?.startsWith("data:")).length }} ·
      Decoded images: {{ decoded }}
    </p>
    <img
      v-for="file in files.filter((file) =>
        /^(data:|blob:)/.test(file.thumbnailUrl || ''),
      )"
      :key="file.uid"
      :src="file.thumbnailUrl"
      :alt="file.name"
      width="16"
      height="16"
      @load="decoded++"
    />
    <p>
      仅接受图片；单文件 1 MiB、合计 2 MiB、最多 3 个。每个示例均经过
      before-read。
    </p>
    <c-space wrap>
      <c-button @click="probe('valid')">加入小图片</c-button>
      <c-button @click="probe('type')">替换为文本</c-button>
      <c-button @click="probe('size')">替换为超大图片</c-button>
      <c-button @click="probe('total')">加入 768 KiB 图片</c-button>
      <c-button @click="reset">重置队列</c-button>
    </c-space>
    <c-checkbox v-model="pauseThumbnail" edit-mode="direct"
      >暂停本地缩略图 Promise</c-checkbox
    >
    <c-upload
      v-model="files"
      edit-mode="direct"
      :show-upload-button="false"
      :preview="false"
    />
    <p>队列：{{ files.map((file) => file.name).join(", ") || "空" }}</p>
    <p>拒绝原因：{{ reasons.join(", ") || "无" }}</p>
  </div>
</template>
```

## Queues and progress

### External State

Example source: src/upload/__demos__/external-state.vue

```vue
<script setup>
import { computed, ref } from "vue";

const files = ref([]);
const hasUploading = computed(() =>
  files.value.some((file) => file.status === "uploading"),
);
const hasRetryable = computed(() =>
  files.value.some((file) => ["error", "canceled"].includes(file.status)),
);
let sequence = 0;

function read(file) {
  file.status = "uploading";
  file.percent = 40;
}

function addExample() {
  const file = new File(
    ["Local external upload demo."],
    `external-${++sequence}.txt`,
    { type: "text/plain" },
  );
  const item = {
    uid: `external-${sequence}`,
    name: file.name,
    size: file.size,
    type: file.type,
    file,
    status: "ready",
    percent: 0,
  };
  read(item);
  files.value = [...files.value, item];
}

function complete() {
  files.value = files.value.map((file) =>
    file.status === "uploading"
      ? { ...file, status: "success", percent: 100 }
      : file,
  );
}

function retry() {
  files.value = files.value.map((file) =>
    ["error", "canceled"].includes(file.status)
      ? { ...file, status: "uploading", percent: 40 }
      : file,
  );
}
</script>

<template>
  <div>
    <p>业务端托管进度和结果；可加入本地示例项，无需选择文件，也不发送请求。</p>
    <c-space wrap>
      <c-button @click="addExample">加入外部上传项</c-button>
      <c-button :disabled="!hasUploading" @click="complete"
        >模拟外部完成</c-button
      >
      <c-button :disabled="!hasRetryable" @click="retry">模拟外部重试</c-button>
    </c-space>
    <c-upload
      v-model="files"
      edit-mode="direct"
      :show-retry-button="false"
      @read="read"
    />
    <p>
      队列状态：{{
        files
          .map((file) => `${file.name}: ${file.status} (${file.percent}%)`)
          .join("；") || "空"
      }}
    </p>
  </div>
</template>
```

### Queue Request

Example source: src/upload/__demos__/queue-request.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, onDeactivated, ref } from "vue";
import type {
  UploadFileItem,
  UploadInstance,
  UploadProgressEvent,
  UploadRequestOptions,
} from "@cedar-design/ui";

const files = ref<UploadFileItem[]>([]);
const uploader = ref<UploadInstance>();
const failOnce = ref(false);
const activeRequests = ref(0);
const timers = new Set<ReturnType<typeof setInterval>>();
const attempts = new Map<string, number>();
const exampleUrls = new Set<string>();
let sequence = 0;

function addExample() {
  const file = new File(
    ["Local upload demo; no network."],
    `example-${++sequence}.txt`,
    { type: "text/plain" },
  );
  const url = URL.createObjectURL(file);
  exampleUrls.add(url);
  files.value = [
    ...files.value,
    {
      uid: `demo-queue-${sequence}`,
      name: file.name,
      size: file.size,
      type: file.type,
      file,
      url,
      status: "ready",
      percent: 0,
    },
  ];
}

function request({
  file,
  onProgress,
  onSuccess,
  onError,
}: UploadRequestOptions) {
  const attempt = (attempts.get(file.uid) ?? 0) + 1;
  attempts.set(file.uid, attempt);
  const reject = failOnce.value && attempt === 1;
  let percent = 0;
  const stop = () => {
    clearInterval(timer);
    timers.delete(timer);
    activeRequests.value = timers.size;
  };
  const timer = setInterval(() => {
    percent += 10;
    onProgress({ percent } as UploadProgressEvent);
    if (percent >= 100) {
      stop();
      if (reject) {
        onError(new Error("Simulated first-attempt failure"));
      } else {
        onSuccess({ ok: true, attempt });
      }
    }
  }, 200);
  timers.add(timer);
  activeRequests.value = timers.size;
  return { abort: stop };
}

function cleanup() {
  uploader.value?.abort();
  timers.forEach((timer) => clearInterval(timer));
  timers.clear();
  activeRequests.value = 0;
}
onBeforeUnmount(() => {
  cleanup();
  exampleUrls.forEach((url) => URL.revokeObjectURL(url));
  exampleUrls.clear();
});
onDeactivated(cleanup);
</script>

<template>
  <div>
    <p>本地模拟请求；支持取消、重试和手动提交，不访问网络。</p>
    <c-checkbox v-model="failOnce" edit-mode="direct"
      >首次请求失败（重试成功）</c-checkbox
    >
    <c-space wrap>
      <c-button @click="addExample">加入示例文件</c-button>
      <c-button @click="uploader?.submit()">提交队列</c-button>
    </c-space>
    <c-upload
      ref="uploader"
      v-model="files"
      edit-mode="direct"
      multiple
      :auto-upload="false"
      :custom-request="request"
    />
    <p>
      队列状态：{{
        files
          .map((file) => `${file.name}: ${file.status} (${file.percent}%)`)
          .join("；") || "空"
      }}
    </p>
    <p>活动请求：{{ activeRequests }}</p>
  </div>
</template>
```

## Async hooks and requests

### Before Remove

Example source: src/upload/__demos__/before-remove.vue

```vue
<script setup lang="ts">
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from "vue";
import type { UploadFileItem } from "@cedar-design/ui";

const files = ref<UploadFileItem[]>([
  {
    uid: "sample",
    name: "sample.txt",
    type: "text/plain",
    status: "success",
    percent: 100,
  },
]);
const allow = ref(false);
const manual = ref(false);
const blocked = ref(false);
const attempts = ref(0);
const removed = ref(0);
const uploadRef = ref();
const mounted = ref(true);
const pending = shallowRef<
  Array<{
    resolve: (accepted: boolean) => void;
    reject: (error: Error) => void;
  }>
>([]);
const beforeRemove = () => {
  attempts.value++;
  if (!manual.value) return allow.value;
  return new Promise<boolean>((resolve, reject) => {
    pending.value = [...pending.value, { resolve, reject }];
  });
};
function settle(accepted: boolean | "reject") {
  const jobs = pending.value;
  pending.value = [];
  jobs.forEach((job) =>
    accepted === "reject"
      ? job.reject(new Error("Local removal rejection"))
      : job.resolve(accepted),
  );
}
function replace() {
  files.value = files.value.map((item) => ({
    ...item,
    name: "replacement.txt",
    type: "text/plain",
    file: new File(["local replacement"], "replacement.txt", {
      type: "text/plain",
    }),
  }));
}
function restore() {
  files.value = [
    {
      uid: "sample",
      name: "restored.txt",
      type: "text/plain",
      status: "success",
      percent: 100,
      file: new File(["local sample"], "restored.txt", { type: "text/plain" }),
    },
  ];
}
onBeforeUnmount(() => settle(false));
onDeactivated(() => settle(false));
</script>

<template>
  <section class="remove-confirm-demo">
    <c-checkbox v-model="allow"> 允许此操作</c-checkbox>
    <c-checkbox v-model="manual"> 手动异步确认</c-checkbox>
    <c-checkbox v-model="blocked"> 禁用上传组件</c-checkbox>
    <c-button
      html-type="button"
      :disabled="!pending.length"
      @click="settle(true)"
      >确认删除</c-button
    >
    <c-button
      html-type="button"
      :disabled="!pending.length"
      @click="settle(false)"
      >取消删除</c-button
    >
    <c-button
      html-type="button"
      :disabled="!pending.length"
      @click="settle('reject')"
      >异常拒绝删除</c-button
    >
    <c-button html-type="button" :disabled="!files.length" @click="replace"
      >替换同 UID 文件</c-button
    >
    <c-button html-type="button" @click="uploadRef?.reset()"
      >重置上传队列</c-button
    >
    <c-button html-type="button" @click="restore">恢复示例文件</c-button>
    <c-checkbox v-model="mounted"> 激活上传组件</c-checkbox>
    <KeepAlive>
      <c-upload
        v-if="mounted"
        ref="uploadRef"
        v-model="files"
        :before-remove="beforeRemove"
        :disabled="blocked"
        @remove="removed++"
      />
    </KeepAlive>
    <p role="status">
      文件：{{ files.length }}；等待：{{ pending.length }}；钩子：{{
        attempts
      }}；删除：{{ removed }}
    </p>
  </section>
</template>
```

### Prepare Request

Example source: src/upload/__demos__/prepare-request.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref } from 'vue'
import { useUploader } from '@cedar-design/ui'

const files = ref([])
const reasons = ref([])
const mode = ref('valid')
const preparing = ref(0)
const requestCount = ref(0)
const pending = new Set()
const modes = [
  { label: '有效副本', value: 'valid' },
  { label: '替换为文本', value: 'type' },
  { label: '替换为超大图片', value: 'size' },
  { label: '每项替换600B，合计上限1024B', value: 'total' },
]
let sequence = 0

function beforeUpload(file) {
  return new Promise((resolve) => {
    pending.add({ file, resolve })
    preparing.value = pending.size
  })
}

const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: (value) => {
    files.value = value
  },
  accept: () => 'image/*',
  maxFileSize: () => 1024,
  maxFiles: () => mode.value === 'total' ? 2 : 1,
  maxTotalSize: () => 1024,
  resolveType: () => 'file',
  autoUpload: () => false,
  beforeUpload: () => beforeUpload,
  customRequest:
    () =>
    ({ onSuccess }) => {
      requestCount.value++
      onSuccess({ ok: true })
    },
  onRejected: (items) => {
    reasons.value = items.map((item) => item.reason)
  },
})

function add() {
  const svg = '<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"/>'
  return uploader.addFiles([new File([svg], `prepare-${++sequence}.svg`, { type: 'image/svg+xml' })])
}

function submit() {
  reasons.value = []
  return uploader.submit()
}

function finish() {
  const jobs = [...pending]
  pending.clear()
  preparing.value = 0
  jobs.forEach(({ file, resolve }) => {
    const raw = file.file
    if (mode.value === 'type') {
      resolve(new File(['text'], 'replacement.txt', { type: 'text/plain' }))
    } else if (mode.value === 'size') {
      resolve(new File([new Uint8Array(1025)], raw.name, { type: raw.type }))
    } else if (mode.value === 'total') {
      resolve(new File([new Uint8Array(600)], raw.name, { type: raw.type }))
    } else {
      resolve(new File([raw], raw.name, { type: raw.type }))
    }
  })
}

function cleanup() {
  uploader.abort()
  pending.forEach(({ resolve }) => resolve(false))
  pending.clear()
  preparing.value = 0
}

function reset() {
  cleanup()
  uploader.reset()
  reasons.value = []
  requestCount.value = 0
}
onBeforeUnmount(cleanup)
onDeactivated(cleanup)
</script>

<template>
  <div class="upload-prepare-demo">
    <p>提交后暂停 before-upload；可取消后再次提交，再统一完成准备，只有当前有效尝试可以发起本地请求。</p>
    <c-radio-group v-model="mode" :options="modes" />
    <c-space wrap>
      <c-button :disabled="files.length >= (mode === 'total' ? 2 : 1)" @click="add">加入示例图片</c-button>
      <c-button :disabled="!files.some((file) => ['ready', 'error', 'canceled'].includes(file.status))" @click="submit"
        >准备并提交</c-button
      >
      <c-button :disabled="preparing === 0" @click="uploader.abort()">取消准备</c-button>
      <c-button :disabled="preparing === 0" @click="finish">完成准备</c-button>
      <c-button @click="reset">重置队列</c-button>
    </c-space>
    <c-upload v-model="files" :show-upload-button="false" :show-retry-button="false" :preview="false" />
    <p>待返回准备任务：{{ preparing }}</p>
    <p>请求次数：{{ requestCount }}</p>
    <p>队列状态：{{ files.map((file) => `${file.status} (${file.percent}%)`).join(', ') || '空' }}</p>
    <p>队列字节：{{ files.map((file) => file.size).join(', ') || '0' }}</p>
    <p>拒绝原因：{{ reasons.join(', ') || '无' }}</p>
  </div>
</template>
```

### Metadata Request

Example source: src/upload/__demos__/metadata-request.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from "vue";
import { useUploader } from "@cedar-design/ui";
const endpoint = ref("");
const files = ref([]);
const headers = shallowRef([]);
const data = shallowRef([]);
const successes = ref(0);
const errors = ref(0);
const response = ref(null);
let sequence = 0;
function wait(queue, file) {
  return new Promise((resolve, reject) => {
    queue.value = [...queue.value, { file, resolve, reject }];
  });
}
function finish(queue, kind) {
  const jobs = queue.value;
  queue.value = [];
  jobs.forEach((job) =>
    job.resolve(
      kind === "headers"
        ? { "X-Demo-Upload": job.file.name }
        : { auditMarker: "audit-local" },
    ),
  );
}
const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: (value) => {
    files.value = value;
  },
  action: () => endpoint.value,
  headers: () => (file) => wait(headers, file),
  data: () => (file) => wait(data, file),
  name: () => "attachment",
  autoUpload: () => false,
  resolveType: () => "file",
  onSuccess: (file) => {
    successes.value++;
    response.value = file.response;
  },
  onError: () => {
    errors.value++;
  },
});
function add() {
  return uploader.addFiles([
    new File(["Synthetic upload audit only."], `metadata-${++sequence}.txt`, {
      type: "text/plain",
    }),
  ]);
}
function cleanup() {
  uploader.abort();
  finish(headers, "headers");
  finish(data, "data");
}
function finishHeaders() {
  finish(headers, "headers");
}
function finishData() {
  finish(data, "data");
}
function rejectHeaders() {
  rejectPending(headers, "headers");
}
function rejectData() {
  rejectPending(data, "data");
}
function rejectPending(queue, kind) {
  const jobs = queue.value;
  queue.value = [];
  jobs.forEach((job) => job.reject(new Error(`Synthetic ${kind} rejection`)));
}
function reset() {
  cleanup();
  uploader.reset();
  successes.value = 0;
  errors.value = 0;
  response.value = null;
}
onBeforeUnmount(cleanup);
onDeactivated(cleanup);
</script>
<template>
  <section class="metadata-upload-demo">
    <p>
      默认 XHR 请求；先配置你控制的本地接口。headers 与 data
      分别等待手动返回，默认不访问任何地址。
    </p>
    <label
      >Local upload endpoint
      <c-input v-model="endpoint" placeholder="http://127.0.0.1:4197/upload"
    /></label>
    <c-space wrap>
      <c-button :disabled="files.length > 0" @click="add"
        >加入合成文件</c-button
      >
      <c-button
        :disabled="
          !endpoint ||
          !files.some((file) =>
            ['ready', 'error', 'canceled'].includes(file.status),
          )
        "
        @click="uploader.submit()"
        >提交元数据请求</c-button
      >
      <c-button
        :disabled="!files.some((file) => file.status === 'uploading')"
        @click="uploader.abort()"
        >取消元数据请求</c-button
      >
      <c-button :disabled="!headers.length" @click="finishHeaders"
        >返回 headers</c-button
      >
      <c-button :disabled="!data.length" @click="finishData"
        >返回 data</c-button
      >
      <c-button :disabled="!headers.length" @click="rejectHeaders"
        >拒绝 headers</c-button
      >
      <c-button :disabled="!data.length" @click="rejectData"
        >拒绝 data</c-button
      >
      <c-button @click="reset">重置元数据示例</c-button>
    </c-space>
    <c-upload
      v-model="files"
      :show-upload-button="false"
      :show-retry-button="false"
      :preview="false"
    />
    <p role="status">
      headers 等待：{{ headers.length }}；data 等待：{{ data.length }}；成功：{{
        successes
      }}；错误：{{ errors }}
    </p>
    <p>
      模型：{{
        files.map((file) => file.name + ": " + file.status).join(", ") || "空"
      }}
    </p>
    <pre>{{ response }}</pre>
  </section>
</template>
```

### Late Request

Example source: src/upload/__demos__/late-request.vue

```vue
<script setup>
import { onBeforeUnmount, onDeactivated, ref, shallowRef } from 'vue'
import { useUploader } from '@cedar-design/ui'

const files = ref([])
const handles = shallowRef([])
const callbacks = shallowRef([])
const requests = ref(0)
const aborts = ref(0)
const accepted = ref(0)
let sequence = 0
let generation = 0
const uploader = useUploader({
  modelValue: () => files.value,
  onUpdateModelValue: value => { files.value = value },
  resolveType: () => 'file',
  autoUpload: () => false,
  customRequest: () => options => {
    const current = generation
    requests.value++
    callbacks.value = [...callbacks.value, options]
    return new Promise(resolve => {
      handles.value = [...handles.value, {
        resolve: () => resolve({ abort: () => { if (current === generation) aborts.value++ } }),
      }]
    })
  },
  onSuccess: () => { accepted.value++ },
})
function add() {
  return uploader.addFiles([new File(['Local delayed transport; no network.'], `late-${++sequence}.txt`, { type: 'text/plain' })])
}
function release() {
  const pending = handles.value
  handles.value = []
  pending.forEach(job => job.resolve())
}
function complete() {
  const pending = callbacks.value
  callbacks.value = []
  pending.forEach(options => options.onSuccess({ local: true }))
}
function cleanup() {
  generation++
  uploader.abort()
  release()
  callbacks.value = []
}
function reset() {
  cleanup()
  uploader.reset()
  requests.value = 0
  aborts.value = 0
  accepted.value = 0
}
onBeforeUnmount(cleanup)
onDeactivated(cleanup)
</script>

<template>
  <section class="late-upload-demo">
    <p>请求句柄延迟返回；先取消再返回句柄，旧句柄应立即 abort，迟到成功回调不能恢复取消项。不访问网络。</p>
    <c-space wrap>
      <c-button :disabled="files.length > 0" @click="add">加入本地文件</c-button>
      <c-button :disabled="!files.some(file => ['ready', 'error', 'canceled'].includes(file.status))" @click="uploader.submit()">发起模拟请求</c-button>
      <c-button :disabled="!files.some(file => file.status === 'uploading')" @click="uploader.abort()">取消模拟请求</c-button>
      <c-button :disabled="!handles.length" @click="release">返回所有句柄</c-button>
      <c-button :disabled="!callbacks.length" @click="complete">返回所有成功回调</c-button>
      <c-button @click="reset">重置模拟</c-button>
    </c-space>
    <c-upload v-model="files" :show-upload-button="false" :show-retry-button="false" :preview="false" />
    <p role="status">句柄等待：{{ handles.length }}；发起：{{ requests }}；abort：{{ aborts }}；有效成功：{{ accepted }}</p>
    <p>模型：{{ files.map(file => file.name + ': ' + file.status).join(', ') || '空' }}</p>
  </section>
</template>
```

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Prop                                                         | Type                                                     | Default / description                                                        |
| ------------------------------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------- |
| model-value / default-value                                  | UploadFileItem[]                                         | Controlled value / uncontrolled initial []                                   |
| accept / capture                                             | string / native capture                                  | Unspecified                                                                  |
| multiple / directory / draggable                             | boolean                                                  | false                                                                        |
| disabled / readonly                                          | boolean                                                  | undefined inherits Form; explicit false overrides                            |
| action / method                                              | string                                                   | None / post                                                                  |
| headers / data                                               | object or async(file) => object                          | Cancelable during request preparation                                        |
| name                                                         | string / (file) => string                                | file                                                                         |
| with-credentials                                             | boolean                                                  | false                                                                        |
| custom-request                                               | (UploadRequestOptions) => UploadRequest / Promise / void | Custom transport; may return abort                                           |
| auto-upload                                                  | boolean                                                  | true; requires action or custom-request to start                             |
| max-files / max-file-size / max-total-size                   | number                                                   | Unspecified; sizes use bytes, max-files applies when >0                      |
| resolve-type                                                 | file / data-url / object-url                             | object-url; all files get url, images also get thumbnailUrl                  |
| create-thumbnail-url                                         | (options) => string / Promise                            | Custom URLs belong to callers and are not automatically revoked              |
| before-add                                                   | async(files) => File[]                                   | Batch filtering/replacement                                                  |
| before-read                                                  | async(file) => boolean / File                            | false/rejection rejects; replacements are revalidated                        |
| before-upload                                                | async(item) => boolean / File / Blob                     | false/rejection cancels preparation; replacements are revalidated            |
| before-remove                                                | async(item,list) => boolean                              | false/rejection prevents removal                                             |
| is-success-response                                          | (xhr,item) => boolean                                    | HTTP 2xx by default                                                          |
| request-choose                                               | (chooseFile,event) => void / Promise                     | Own the selection entry; exceptions do not automatically open a file chooser |
| list-type                                                    | text / picture / picture-card                            | text; supported on both platforms                                            |
| image-fit                                                    | fill / contain / cover / none / scale-down               | cover; item.fit overrides                                                    |
| preview                                                      | boolean                                                  | true                                                                         |
| show-file-list / show-upload-button / show-remove-button     | boolean                                                  | true                                                                         |
| show-retry-button / show-cancel-button / show-preview-button | boolean                                                  | true                                                                         |
| show-download-button                                         | boolean                                                  | false; disabled prevents interaction                                         |
| elevation / ripple                                           | boolean or number / boolean                              | false / true                                                                 |

UploadFileItem requires uid, status and percent. name/size/type/file/url/thumbnailUrl/fit/response/error are optional. status is ready/reading/uploading/success/error/canceled/removed.

### Events

- update:model-value(files), change(files, changedFile?): queue proposal order; Form receives one change notification per change, including progress/state updates.
- read(item): reading completed; business code may take over uploading. It does not indicate server success.
- rejected(UploadRejectedFile[]): reason is accept/before-add/before-read/read-error/max-file-size/max-total-size/max-files.
- exceed(nativeFiles, acceptedList): file-count limit exceeded.
- progress(item,event?), success(item), error(item): active-request notifications. Stale/canceled callbacks have no effect.
- remove(item): removal proposal after removal hooks accept it.
- preview(item, UploadPreviewEvent): event.preventDefault() cancels built-in image/video preview. Programmatic previews are cancelable too; originalEvent is optional.

### Slots

- trigger({chooseFile,dragOver,disabled}): custom selection entry.
- item({file,index,remove,retry,abort}): custom complete item.
- remove-button({file,index,remove,retry,abort}): custom removal action.

### Expose

chooseFile(), submit(file?), abort(file?), retry(file), remove(file), reset(), clearSuccess(), clearError(), getFiles(status?), preview(file), closePreview(). useUploader(options) supplies matching UI-free logic plus addFiles(files) and input/drag handlers.

### Controlled state and lifecycle

If a controlled parent rejects an addition, only read/list proposals emit; automatic upload waits until that uid is accepted, then runs once. Same-tick proposals merge transactionally; across ticks, the actual parent list is authoritative. Rejected entries do not count toward total size. Parents own consistency of late list replacements. Explicit removal of rejected items, reset or unmount releases generated URLs; external URLs are never revoked. Built-in preview retains its own URL ownership until closing and does not close another component's later preview.

Cancellation covers before-upload, asynchronous headers/data/name and asynchronous custom-request handles. Retrying or replacing a File under the same uid invalidates old callbacks. before-read/before-upload replacements recheck limits. max-total-size counts accepted entries and the current valid prepared batch/request only. Disabled/readonly block selection, removal, submission and other mutations; readonly allows preview/download. KeepAlive deactivation cancels preparation/requests; reactivation allows new operations.

## Type definitions

UploadProps、UploadEmits、UploadSlots、UploadExpose、UploadPublicMethods、UploadFileItem、UploadStatus、UploadListType、UploadResolveType、UploadImageFit、UploadCapture、UploadRejectedFile、UploadRejectedReason、UploadRequestOptions、UploadRequest、UploadCustomRequest、UploadProgressEvent、UploadData、UploadHeaders、UploadBeforeRead、UploadBeforeUpload、UploadBeforeRemove、UploadCreateThumbnailUrl、UploadIsSuccessResponse、UploadRequestChoose、UploadPreviewEvent、UseUploaderOptions、UploadInstance。

## Style variables

Public variable suffixes match across platforms; all defaults appear below with c/mp prefixes respectively.

| Variable                                | Default                                  |
| --------------------------------------- | ---------------------------------------- |
| --c-upload-gap                          | var(--c-sys-space-4)                     |
| --c-upload-trigger-min-height           | var(--c-sys-control-height-md)           |
| --c-upload-trigger-padding-horizontal   | var(--c-sys-space-6)                     |
| --c-upload-trigger-draggable-min-height | calc(var(--c-sys-control-height-md) * 2) |
| --c-upload-card-size                    | calc(var(--c-sys-control-height-md) * 2) |
| --c-upload-item-min-height              | var(--c-sys-control-height-md)           |
| --c-upload-item-padding                 | var(--c-sys-space-4)                     |
| --c-upload-thumb-size                   | var(--c-sys-control-height-lg)           |
| --c-upload-border-radius                | var(--c-sys-radius-md)                   |
| --c-upload-border-color                 | var(--c-sys-color-border-default)        |
| --c-upload-background                   | var(--c-sys-color-surface-default)       |
| --c-upload-text-color                   | var(--c-sys-color-content-primary)       |
| --c-upload-secondary-text-color         | var(--c-sys-color-content-secondary)     |
| --c-upload-hover-background             | var(--c-sys-color-state-hover)           |
| --c-upload-active-color                 | var(--c-sys-color-action-primary)        |
| --c-upload-error-color                  | var(--c-sys-color-content-danger)        |
| --c-upload-action-size                  | var(--c-sys-control-touch-target)        |
| --c-upload-progress-height              | var(--c-sys-space-2)                     |
| --c-upload-disabled-opacity             | .56                                      |
| --c-upload-font-size                    | var(--c-sys-font-size-md)                |

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

Attachment confirmation commits file-list relationships; it cannot undo completed remote uploads or permanent deletion. To defer network side effects, set `auto-upload="false"` and upload after the final business submission.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

## Cover attachments and video duration

`reupload` (default false) enables a per-item replacement action, including when maxFiles has been reached. `replace(file, replacement?: File): Promise<void>` opens a single-file chooser or validates the supplied File. It respects readonly/disabled and the chooser hook. Validation and beforeRemove run before an atomic in-place replacement proposal with a new UID; count and total size exclude the old item. Cancellation, rejection, guard veto and stale targets preserve the old item. A controlled parent decides acceptance. The `replace(next, previous)` event is a model proposal, not remote success or removal; remove is not emitted. Once accepted, obsolete transport callbacks are ignored; new upload failures can be retried. The item slot also exposes replace().

`UploadFileItem.duration?: number` uses seconds, displayed as mm:ss / h:mm:ss; unknown/invalid durations are hidden. Metadata reads local File objects only, waits at most 5 seconds and cleans temporary resources. Business code supplies remote durations. Video previews use popupContainer.

Duration-badge variables: `--c-upload-duration-background: var(--c-sys-color-surface-tooltip)`, `--c-upload-duration-color: var(--c-sys-color-content-on-dark)`, `--c-upload-duration-radius: var(--c-sys-radius-sm)`, `--c-upload-duration-padding: var(--c-sys-space-1) var(--c-sys-space-2)`, `--c-upload-duration-font-size: var(--c-sys-font-size-sm)`.

### Before-hook waiting feedback

Before-hook waits show visible feedback and aria-busy. Rejected or failed operations recover; duplicate submissions do not start another copy. Notification event Promises never drive loading. Independent file operations retain concurrency and share aggregate hook feedback.

`useUploader()` exposes readonly `guardPending`, aggregating currently awaited before hooks. It does not represent upload progress.

---

Document: llms/en-US/components/verification-code.md

<!-- Source: src/verification-code/README.en-US.md; locale: en-US; page: /en/components/verification-code/ -->

# Verification Code

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `aria-label="验证码"`.

Example source: src/verification-code/__demos__/basic.vue

```vue
<script setup>
import { ref } from 'vue'

const code = ref('')
</script>
<template>
  <div class="verification-demo">
    <c-verification-code v-model="code" aria-label="验证码" />
    <p>当前值：{{ code || '未输入' }}</p>
  </div>
</template>
<style scoped>
.verification-demo {
  max-width: 420px;
}
</style>
```

## Appearance and states

### Appearance

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration   | Purpose                                                      | Related examples           |
| --------------- | ------------------------------------------------------------ | -------------------------- |
| `default-value` | Uncontrolled initial value                                   | Appearance, States         |
| `length`        | Positive integer cell count, measured in Unicode code points | Appearance, Appearance Lab |
| `aria-label`    | Group name and numbered cell labels                          | Appearance, States         |
| `masked`        | Visual character masking only, not encryption                | Appearance                 |
| `mask-symbol`   | Use the first Unicode code point                             | Appearance                 |
| `variant`       | Input variant                                                | Appearance                 |

<!-- demo-config-notes:end -->

- `variant`: Selects the visual variant.
- `size`: Controls the component size.
- `align`: Controls alignment on the cross axis.

Example source: src/verification-code/__demos__/appearance.vue

```vue
<template>
  <div class="verification-demo">
    <c-verification-code
      default-value="1234"
      :length="4"
      masked
      mask-symbol="*"
      aria-label="掩码验证码"
    /><c-verification-code
      default-value="1234"
      :length="4"
      variant="filled"
      size="lg"
      align="start"
      :gutter="12"
      aria-label="填充验证码"
    /><c-verification-code
      default-value="12"
      :length="4"
      variant="standard"
      focus-color="#6750a4"
      aria-label="线条验证码"
    />
  </div>
</template>
<style scoped>
.verification-demo {
  display: flex;
  flex-direction: column;
  gap: 20px;
  max-width: 420px;
}
</style>
```

### Appearance Lab

Preview configuration: `layout="vertical"`, `aria-label="variant"`, `options`, `variant="button"`.

Example source: src/verification-code/__demos__/appearance-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("123456");
const __demoAppearance = __demoReactive({ variant: "filled", size: "md" });

import { computed as demoComputed, ref as demoRef } from 'vue'
const demoCompareFields = [{"name":"variant","values":["filled","outline","standard"]},{"name":"size","values":["xs","sm","md","lg","xl"]}]
const demoCompareAxis = demoRef("variant")
const demoComparedOptions = demoComputed(() => demoCompareFields.find(field => field.name === demoCompareAxis.value)?.values ?? [])
</script>
<template>
  <c-space direction="column" :size="16">
    <c-form layout="vertical">
      <c-form-item layout="vertical" size="sm" label="variant">
        <c-radio-group
          v-model="__demoAppearance['variant']"
          aria-label="variant"
          :options="[
            { label: 'filled', value: 'filled' },
            { label: 'outline', value: 'outline' },
            { label: 'standard', value: 'standard' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
      <c-form-item layout="vertical" size="sm" label="size">
        <c-radio-group
          v-model="__demoAppearance['size']"
          aria-label="size"
          :options="[
            { label: 'xs', value: 'xs' },
            { label: 'sm', value: 'sm' },
            { label: 'md', value: 'md' },
            { label: 'lg', value: 'lg' },
            { label: 'xl', value: 'xl' },
          ]"
          variant="button"
          size="sm"
        />
      </c-form-item>
    </c-form>
    <p class="demo-config-comparison-hint"><span lang="zh-CN">选择一个对比维度；其他配置和内容保持一致。输入类示例共享同一个值，便于比较外观。</span><span lang="en-US">Compare one dimension while keeping the other settings and content identical. Input specimens share the same value.</span></p>
<c-radio-group v-model="demoCompareAxis" aria-label="Compare configuration" :options="demoCompareFields.map(field => ({ label: field.name, value: field.name }))" />
<div class="demo-config-comparison">
<section v-for="sample in demoComparedOptions" :key="String(sample)">
<p><code>{{ demoCompareAxis }}={{ sample }}</code></p>
<c-verification-code
      v-model="value"
      :length="6"
      v-bind="{ ...__demoAppearance, [demoCompareAxis]: sample }"
    ></c-verification-code>
</section>
</div>
  </c-space>
</template>

<style scoped>
.demo-config-comparison { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(100%, 220px), 1fr)); gap: 20px; min-width: 0; max-width: 100%; }
.demo-config-comparison > section { min-width: 0; }
.demo-config-comparison p { margin: 0 0 8px; }
html:not([lang='en-US']) .demo-config-comparison-hint > [lang='en-US'],
html[lang='en-US'] .demo-config-comparison-hint > [lang='zh-CN'] { display: none; }
</style>
```

### States

- `readonly`: Displays the current value without allowing edits.
- `disabled`: Prevents user interaction.

Example source: src/verification-code/__demos__/states.vue

```vue
<template>
  <div class="verification-demo">
    <c-verification-code default-value="123456" readonly aria-label="只读验证码" /><c-verification-code
      default-value="123456"
      disabled
      aria-label="禁用验证码"
    /><c-verification-code default-value="12" error aria-label="错误验证码" />
  </div>
</template>
<style scoped>
.verification-demo {
  display: flex;
  flex-direction: column;
  gap: 20px;
  max-width: 420px;
}
</style>
```

## Data and options

### Formatting

<!-- demo-config-notes:start -->

#### Configuration reference for this comparison

| Configuration     | Purpose                                                                                                                   | Related examples |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `type`            | Character set                                                                                                             | Formatting       |
| `paste-transform` | Paste preprocessing, before type/formatter                                                                                | Formatting       |
| `formatter`       | Per-character formatting: false rejects; true/undefined retains. A returned string contributes its first valid code point | Formatting       |
| `aria-label`      | Group name and numbered cell labels                                                                                       | Formatting       |

<!-- demo-config-notes:end -->

Preview configuration: `type="alphanumeric"`, `:paste-transform="transform"`, `:formatter="(char) => char.toUpperCase()"`, `aria-label="字母数字验证码"`.

Example source: src/verification-code/__demos__/formatting.vue

```vue
<script setup>
import { ref } from 'vue'

const code = ref('')
const transform = (value) => value.replace(/[-\s]/g, '').toUpperCase()
</script>
<template>
  <div class="verification-demo">
    <p>可粘贴 ab-12-cd；从当前格开始写入。</p>
    <c-verification-code
      v-model="code"
      type="alphanumeric"
      :paste-transform="transform"
      :formatter="(char) => char.toUpperCase()"
      aria-label="字母数字验证码"
      ><template #separator="{ index }"><span v-if="index === 2">−</span></template></c-verification-code
    >
    <p>{{ code }}</p>
  </div>
</template>
<style scoped>
.verification-demo {
  max-width: 420px;
}
</style>
```

## Interaction and control

### State Lab

Preview configuration: `:length="6"`.

Example source: src/verification-code/__demos__/state-lab.vue

```vue
<script setup>
import { reactive as __demoReactive } from "vue";
import { ref } from "vue";
const value = ref("123456");
const __demoState = __demoReactive({
  disabled: false,
  readonly: false,
  error: false,
});
</script>
<template>
  <c-space direction="column" :size="16">
    <c-space wrap>
      <c-checkbox v-model="__demoState['disabled']">disabled</c-checkbox>
      <c-checkbox v-model="__demoState['readonly']">readonly</c-checkbox>
      <c-checkbox v-model="__demoState['error']">error</c-checkbox>
    </c-space>
    <c-verification-code
      v-model="value"
      :length="6"
      v-bind="__demoState"
    ></c-verification-code>
  </c-space>
</template>
```

## Reading direction

Inherits the nearest `dir="ltr|rtl"` and supports runtime and nested overrides. Codes form an LTR content island: display, paste and focus navigation preserve string order. Outer start/end alignment still follows reading direction. RTL never reverses code characters; numeric and text codes share this ordering contract.

## API

### Empty values and reading placeholders

`empty-values` recognizes empty data; `empty-value` keeps existing clear output. `empty-text` defaults to `'-'` under `read-pretty`, with Field > FormItem > Form precedence and custom read slots first. With explicit empty-values, built-in required uses the policy; custom validators receive original data. See the [shared guide](llms/en-US/guide/empty-values.md).

| Prop         | Type               | Default and scope                                                           |
| ------------ | ------------------ | --------------------------------------------------------------------------- |
| empty-values | readonly unknown[] | Field > FormItem > Form > component-family default; replaces the whole list |
| empty-text   | string             | Field > FormItem > Form > '-'; explicit '' is valid                         |

These props belong to field presentation; pure panels do not gain reading mode. Form and FormItem provide inherited settings. The existing empty-value type and clear fallback remain component-specific.

### Props

| Prop                                    | Description                                                                                                               | Type                                            | Default             |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------- |
| `model-value`                           | Controlled complete code                                                                                                  | `string`                                        | `undefined`         |
| `default-value`                         | Uncontrolled initial value                                                                                                | `string`                                        | `''`                |
| `length`                                | Positive integer cell count, measured in Unicode code points                                                              | `number`                                        | `6`                 |
| `type`                                  | Character set                                                                                                             | `digit / text / alphanumeric`                   | `digit`             |
| `size`                                  | Five wrapper sizes                                                                                                        | `xs / sm / md / lg / xl`                        | Inherited / md      |
| `variant`                               | Input variant                                                                                                             | `filled / outline / standard`                   | Inherited / outline |
| `disabled / readonly / error`           | State; explicit values override Form                                                                                      | `boolean`                                       | `undefined`         |
| `masked`                                | Visual character masking only, not encryption                                                                             | `boolean`                                       | `false`             |
| `mask-symbol`                           | Use the first Unicode code point                                                                                          | `string`                                        | `•`                 |
| `autofocus`                             | Focus the first empty cell after mounting                                                                                 | `boolean`                                       | `false`             |
| `gutter`                                | Cell gap; numbers are px                                                                                                  | `number / string`                               | Component token     |
| `align`                                 | Horizontal alignment                                                                                                      | `start / center / end`                          | `center`            |
| `allow-paste`                           | Allow pasting; false prevents native paste                                                                                | `boolean`                                       | `true`              |
| `paste-transform`                       | Paste preprocessing, before type/formatter                                                                                | `(text: string) => string`                      | `undefined`         |
| `formatter`                             | Per-character formatting: false rejects; true/undefined retains. A returned string contributes its first valid code point | `(character, index, value) => string / boolean` | `undefined`         |
| `separator`                             | Separator after each nonfinal cell                                                                                        | `(index, character) => VNodeChild`              | `undefined`         |
| `aria-label`                            | Group name and numbered cell labels                                                                                       | `string`                                        | `undefined`         |
| `text-color / focus-color / blur-color` | Dynamic instance colors; prefer tokens for static themes                                                                  | `string`                                        | `undefined`         |

### Events

| Event              | Arguments               | Semantics                                                                                                                                   |
| ------------------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| input              | character, index, event | Starting character and zero-based index of each valid native input proposal                                                                 |
| update:model-value | value                   | Complete-code proposal                                                                                                                      |
| change             | value                   | Complete-code proposal for each valid edit, not necessarily accepted by a controlled parent                                                 |
| finish             | value                   | The changed complete code was accepted and filled all cells; accepted edits to already-full codes also emit it. External assignments do not |
| paste              | text, event             | Pasted text after paste-transform/type processing                                                                                           |
| focus / blur       | FocusEvent              | Focus enters/leaves the whole component; moving between cells does not duplicate notifications                                              |
| click              | MouseEvent              | Non-disabled click                                                                                                                          |

Valid input order: input → update:modelValue → change. finish waits until the parent accepts the complete value in that render. Rejected controlled values restore native inputs; later asynchronous parent assignments do not add finish. reset() proposes empty and emits update:modelValue/change without simulating native input. Disabled, readonly or composing state prevents reset from changing values.

Paste overwrites from the current cell; pasting on the root starts at cell 1. Input beyond the first empty cell is redirected there. SMS autofill entered as a whole code distributes across later cells. Typing one character in a filled cell replaces it even with the caret after the old character. IME prefers the current compositionend text and distributes multiple code points, falling back to native value only when committed text is absent. Processing is type filter → formatter → length trim; rejected characters occupy no cells. text counts Unicode code points, not grapheme clusters. External updates affect display without formatting/writeback.

### Slots

| Slot      | Arguments            | Description                                           |
| --------- | -------------------- | ----------------------------------------------------- |
| separator | { index, character } | Overrides separator; not rendered after the last cell |

### Expose

- focus(index?): zero-based index; omission selects the first empty cell or last cell when full. Disabled prevents focusing; readonly allows focus/copy.
- blur(): remove focus.
- reset(): propose clearing, respecting controlled/disabled/readonly state.

### Keyboard and Form

Left/Right move between cells. Backspace removes the current character, or the previous one when empty. Delete removes the current character; following characters shift forward. IME composition does not trim, delete or move focus. Each native input has an SSR-stable id. Cell 1 uses autocomplete=one-time-code, others off. Provide aria-label.

InputGroup/Form state is inherited, with explicit disabled/readonly/error/size taking precedence. Internal cell Inputs do not duplicate Form notifications; the complete control notifies input/change once per edit. Both platforms implement three variants/five sizes using local FieldDecorator tokens.

## Type definitions

VerificationCodeProps、VerificationCodeType、VerificationCodeAlign、VerificationCodeVariant、VerificationCodeFormatter、VerificationCodeSeparator、VerificationCodeEmits、VerificationCodeSlots、VerificationCodeExpose、VerificationCodeInstance。

## Style variables

| Variable                              | Default              | Description                                                      |
| ------------------------------------- | -------------------- | ---------------------------------------------------------------- |
| --c-verification-code-gutter          | var(--c-sys-space-2) | Cell gap                                                         |
| --c-verification-code-cell-height     | initial              | Follows size-specific field-size-*-height when not overridden    |
| --c-verification-code-cell-max-width  | initial              | Follows size-specific field-size-*-height when not overridden    |
| --c-verification-code-input-font-size | initial              | Follows size-specific field-size-*-font-size when not overridden |

initial means no public override. CSS reads size fallbacks at the component element. Override through component style or theme. Old Cedar column-gap is removed; use gutter.

### Form field presentation and confirmation

This component supports `edit-mode` with field > FormItem > Form precedence. When unset, it defaults to `direct` and preserves `direct` editing. Supported values: `direct / click / dblclick`. Non-`direct` modes open the editor through the field value trigger and keep one draft; v-model updates only after confirmation. Cancel, reset or enabling readPretty discards the draft.

Cedar uses edit-mode="click" / "dblclick" to open an editor popup near the field. Enter/F2 also opens it; cancel/Escape discards the draft, and confirmation commits it. readPretty is an independent reading setting, separate from readonly and disabled.

`before-commit(value, { previousValue, signal })` can reject an overlay save. FormItem validates the candidate first and keeps the editor open on failure. `open / default-open / update:open` control the editor. Use `#read="{ value, text }"` to customize display. See the full field comparison in Form.

`read-pretty` is an independent boolean alongside `readonly` and `disabled`. It inherits from field to FormItem to Form; explicit `false` overrides the parent. The default is `false`. Reading mode renders no editor.

---

Document: llms/en-US/components/watermark.md

<!-- Source: src/watermark/README.en-US.md; locale: en-US; page: /en/components/watermark/ -->

# Watermark

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Basic usage

Preview configuration: `:content="content"`, `:font="{ color: dark ? 'rgba(255,255,255,0.4)' : 'rgba(0,0,0,0.25)' }"`.

Example source: src/watermark/__demos__/basic.vue

```vue
<script setup>
import { ref } from "vue";
const dark = ref(false);
const shown = ref(true);
const content = ref("LOCAL DEMO 200");
const clicks = ref(0);
</script>

<template>
  <section class="watermark-contrast-demo">
    <c-checkbox v-model="dark"> Dark surface / 深色底</c-checkbox>
    <c-checkbox v-model="shown"> Show watermark / 显示水印</c-checkbox>
    <label>Watermark text / 水印文字<c-input v-model="content" /></label>
    <c-watermark
      v-if="shown"
      :content="content"
      :font="{ color: dark ? 'rgba(255,255,255,0.4)' : 'rgba(0,0,0,0.25)' }"
      :style="{
        background: dark ? '#1f2937' : '#ffffff',
        color: dark ? '#ffffff' : '#111827',
      }"
    >
      <div class="watermark-contrast-surface">
        <p>Local synthetic content / 本地合成内容</p>
        <c-button html-type="button" @click="clicks++"
          >Click through / 点击内容</c-button
        >
      </div>
    </c-watermark>
    <p role="status">
      Visible: {{ shown }} · Dark: {{ dark }} · Clicks: {{ clicks }}
    </p>
  </section>
</template>
<style scoped>
.watermark-contrast-surface {
  min-height: 240px;
  display: grid;
  place-content: center;
  gap: 12px;
}
</style>
```

## Content and presentation

### Multiline

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | One or more text lines; also used when an image fails | Multiline, Image, Fullscreen |
| `image` | Image URL, preferred over text | Image |
| `width` | Mark width; measured from content by default | Image |
| `height` | Mark height; measured from content by default | Image |
| `font` | Text style | Image |
| `fullscreen` | Cover the viewport | Fullscreen |
<!-- demo-config-notes:end -->


Preview configuration: `:content="['Cedar Design', dayjs().format('YYYY-MM-DD')]"`.

Example source: src/watermark/__demos__/multiline.vue

```vue
<template>
  <c-watermark :content="['Cedar Design', dayjs().format('YYYY-MM-DD')]">
    <div style="width: 100%; height: 300px" />
  </c-watermark>
</template>

<script lang="ts" setup>
import dayjs from "dayjs";
</script>
```

### Image

- `width`: Sets the configured width.
- `height`: Constrains the component height.

Example source: src/watermark/__demos__/image.vue

```vue
<script setup>
import { computed, ref } from "vue";
const failed = ref(false);
const errors = ref([]);
const localImage =
  "data:image/svg+xml," +
  encodeURIComponent(
    '<svg xmlns="http://www.w3.org/2000/svg" width="160" height="48"><rect width="160" height="48" rx="8" fill="#0284c7"/><circle cx="80" cy="24" r="14" fill="white"/></svg>',
  );
const image = computed(() =>
  failed.value ? "data:image/png;base64,invalid-local-image" : localImage,
);
</script>
<template>
  <section class="watermark-image-failure-demo">
    <c-checkbox v-model="failed"> Fail local image / 本地图片失败</c-checkbox>
    <c-button html-type="button" :disabled="!failed" @click="failed = false"
      >Restore image / 恢复图片</c-button
    >
    <c-watermark
      content="FALLBACK 201"
      :image="image"
      :width="160"
      :height="48"
      :font="{ color: '#be123c' }"
      style="background: white"
      @error="errors.push($event.source)"
    >
      <div style="height: 240px" />
    </c-watermark>
    <p role="status">
      Mode: {{ failed ? "failure" : "image" }} · Errors:
      {{ errors.join(",") || "-" }}
    </p>
  </section>
</template>
```

### Fullscreen

Preview configuration: `content="Cedar Design"`, `:fullscreen="fullscreen"`, `:z-index="99"`.

Example source: src/watermark/__demos__/fullscreen.vue

```vue
<script setup lang="ts">
import { ref } from "vue";

const fullscreen = ref(false);
</script>

<template>
  <c-watermark content="Cedar Design" :fullscreen="fullscreen" :z-index="99">
    <div class="watermark-fullscreen-demo">
      <c-button status="primary" @click="fullscreen = !fullscreen">
        {{ fullscreen ? "退出全屏水印" : "开启全屏水印" }}
      </c-button>
    </div>
  </c-watermark>
</template>

<style scoped>
.watermark-fullscreen-demo {
  min-height: 160px;
  display: grid;
  place-items: center;
}
</style>
```

## Customization and slots

### Custom

<!-- demo-config-notes:start -->
#### Configuration reference for this comparison

| Configuration | Purpose | Related examples |
| --- | --- | --- |
| `content` | One or more text lines; also used when an image fails | Custom |
| `rotate` | Rotation angle | Custom |
| `gap` | Watermark gap `[x, y]` | Custom |
| `offset` | First mark offset; defaults to half the gap | Custom |
| `font` | Text style | Custom |
<!-- demo-config-notes:end -->


Preview configuration: `size="sm"`, `:model="form"`, `auto-label-width`, `:gutter="16"`.

Example source: src/watermark/__demos__/custom.vue

```vue
<template>
  <c-form size="sm" :model="form" auto-label-width>
    <c-row :gutter="16">
      <c-col :span="24">
        <c-form-item field="rotate" label="rotate">
          <c-slider v-model="form.rotate" :min="-180" :max="180" />
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="gap">
          <c-input-group>
            <c-input-number
              v-model="form.gap[0]"
              placeholder="gap[x]"
              :min="0"
            />
            <c-input-number
              v-model="form.gap[1]"
              placeholder="gap[y]"
              :min="0"
            />
          </c-input-group>
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="offset">
          <c-input-group>
            <c-input-number v-model="form.offset[0]" placeholder="offsetLeft" />
            <c-input-number v-model="form.offset[1]" placeholder="offsetTop" />
          </c-input-group>
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="fontSize">
          <c-input-number v-model="form.font.fontSize" mode="button" />
        </c-form-item>
      </c-col>
      <c-col :span="12">
        <c-form-item label="zIndex">
          <c-input-number v-model="form.zIndex" mode="button" />
        </c-form-item>
      </c-col>
      <c-col :span="6">
        <c-form-item label="repeat">
          <c-switch v-model="form.repeat" />
        </c-form-item>
      </c-col>
      <c-col :span="6">
        <c-form-item label="staggered">
          <c-switch v-model="form.staggered" />
        </c-form-item>
      </c-col>
    </c-row>
  </c-form>
  <c-watermark content="arco.design" v-bind="form">
    <div style="width: 100%; border: 1px solid #e5e6eb; box-sizing: border-box">
      <c-typography-title :heading="5"> Design system</c-typography-title>
      <c-typography>
        <c-typography-paragraph>
          A design is a plan or specification for the construction of an object
          or system or for the implementation of an activity or process, or the
          result of that plan or specification in the form of a prototype,
          product or process. The verb to design expresses the process of
          developing a design.
        </c-typography-paragraph>
        <c-typography-paragraph>
          A design is a plan or specification for the construction of an object
          or system or for the implementation of an activity or process, or the
          result of that plan or specification in the form of a prototype,
          product or process. The verb to design expresses the process of
          developing a design.
        </c-typography-paragraph>
      </c-typography>
      <img
        style="position: relative; z-index: 7"
        src="https://p1-arco.byteimg.com/tos-cn-i-uwbnlip3yd/24e0dd27418d2291b65db1b21aa62254.png~tplv-uwbnlip3yd-webp.webp"
      />
    </div>
  </c-watermark>
</template>

<script lang="ts" setup>
import { reactive } from "vue";

const form = reactive({
  rotate: 0,
  gap: [50, 50],
  offset: [],
  font: { fontSize: 16 },
  zIndex: 6,
  repeat: true,
  staggered: true,
});
</script>
```

## API

### Props

| Arguments | Description | Type | Default |
| ------------- | ------------------------------------------ | -------------------- | -------------------------- |
| `content` | One or more text lines; also used when an image fails | `string \| string[]` | `-` |
| `image` | Image URL, preferred over text | `string` | `-` |
| `width` | Mark width; measured from content by default | `number` | `-` |
| `height` | Mark height; measured from content by default | `number` | `-` |
| `gap` | Watermark gap `[x, y]` | `[number, number]` | `[90, 90]` |
| `offset` | First mark offset; defaults to half the gap | `[number, number]` | `[gap[0] / 2, gap[1] / 2]` |
| `rotate` | Rotation angle | `number` | `-22` |
| `font` | Text style | `WatermarkFont` | `-` |
| `z-index` | Layer z-index | `number` | `6` |
| `alpha` | Overall opacity in the `0..1` range | `number` | `1` |
| `anti-tamper` | Restore a removed or modified layer | `boolean` | `true` |
| `grayscale` | Render in grayscale | `boolean` | `false` |
| `repeat` | Repeat the mark | `boolean` | `true` |
| `staggered` | Stagger repeated rows | `boolean` | `true` |
| `fullscreen` | Cover the viewport | `boolean` | `false` |

### WatermarkFont

| Arguments | Type | Default |
| ------------ | ----------------------------------- | ---------------------------------- |
| `color` | `string` | `var(--c-watermark-content-color)` |
| `fontSize` | `number` | `16` |
| `fontFamily` | `string` | `sans-serif` |
| `fontStyle` | `'normal' \| 'italic' \| 'oblique'` | `normal` |
| `fontWeight` | `string \| number` | `normal` |
| `textAlign` | `CanvasTextAlign` | `center` |
| `lineHeight` | `number` | `fontSize × 1.4` |

### Events

| Event | Description | Arguments |
| ------- | -------------------------- | ------------------------------------------------- |
| `error` | Image loading or Canvas rendering failed | `{ source: 'image' \| 'canvas'; error: unknown }` |

### Methods

| Method | Description | Returns |
| -------- | ---------------------- | --------------- |
| `redraw` | Regenerate the watermark from current props | `Promise<void>` |

### Slots

| Slot | Description |
| --------- | -------------------- |
| `default` | Page content covered by the watermark |

### CSS variables

| Variable | Default |
| ----------------------------- | --------------------- |
| `--c-watermark-content-color` | `rgba(0, 0, 0, 0.15)` |

---

Document: llms/en-US/guide/controlled-uncontrolled.md

<!-- Source: docs/en/guide/controlled-uncontrolled.md; locale: en-US; page: /en/guide/controlled-uncontrolled/ -->

# Controlled state, defaults and clear values: learn by interaction

Start with Input behavior, then expand v-model and finally examine emptyValue. This guide describes current workspace behavior; the proposed unified contract is discussed separately at the end.

Register components and include styles as described in Quick Start. Each complete Vue example is independent. Input examples explicitly use `edit-mode="direct"` so popup confirmation drafts do not obscure ownership.

## 1. Separate the questions

| Question                                | What determines it?                          | Example                                                |
| --------------------------------------- | -------------------------------------------- | ------------------------------------------------------ |
| Who decides the final current value?    | modelValue and the component ownership check | Parent supplies A, rejects B, final value remains A    |
| Is this only an initial value?          | defaultValue                                 | Start with Hangzhou, let the user change it later      |
| What value does a clear action propose? | emptyValue, written empty-value in templates | null, an empty string, or a configured value           |
| Does a value look empty?                | Component type, options and formatting       | Input renders null as blank, but EMPTY as literal text |

Controlled means the parent owns the final value. It does not mean disabled, unfocusable, without input events, or stored on a server. The parent is the Vue component containing `<c-input ... />`; its ref or form object holds the external state.

emptyValue answers the clear-output question. It does not automatically answer ownership or empty-value recognition. It is not a list of values considered empty.

## 2. Uncontrolled: provide a seed, let the component store later edits

```vue
<script setup lang="ts">
import { ref } from "vue";

const seed = ref("Hangzhou");
const instanceKey = ref(0);
const lastRequest = ref<string | null>();
function record(next: string | null) {
  lastRequest.value = next;
}
</script>

<template>
  <c-input
    :key="instanceKey"
    :default-value="seed"
    edit-mode="direct"
    @update:model-value="record"
  />
  <p>Initial seed: {{ seed }}</p>
  <p>Last update request: {{ JSON.stringify(lastRequest) }}</p>
  <button type="button" @click="seed = 'Beijing'">Change default only</button>
  <button type="button" @click="instanceKey++">Remount</button>
</template>
```

| Action                             | Input text   | Parent seed | Explanation                                                            |
| ---------------------------------- | ------------ | ----------- | ---------------------------------------------------------------------- |
| Mount                              | Hangzhou     | Hangzhou    | The component reads the default                                        |
| Select all and replace with Suzhou | Suzhou       | Hangzhou    | The component stores the edit; recording an event does not modify seed |
| Change default only                | Still Suzhou | Beijing     | Defaults do not overwrite current edits                                |
| Remount                            | Beijing      | Beijing     | The new instance reads the current default                             |

An update listener only observes candidates. Without binding the recorded value back through modelValue, it does not control the component. Initialization does not emit an initial value to populate the parent.

Changing defaultValue is not a reset command. Use controlled binding when the application needs to replace the current value programmatically.

## 3. Controlled and accepting updates

```vue
<script setup lang="ts">
import { ref } from "vue";
const text = ref<string | null>("A");
</script>

<template>
  <c-input v-model="text" edit-mode="direct" />
  <p>Parent value: {{ JSON.stringify(text) }}</p>
  <button type="button" @click="text = 'C'">Parent sets C</button>
</template>
```

Select A and replace it with B. Parent text becomes B and the input follows that parent value. Click the button and the parent replaces it with C.

```text
Parent text=A → input receives A
User enters B → component emits update:modelValue(B)
Parent assigns text=B → prop becomes B → final display is B
```

Writing back means assigning the parent's own ref/form field and passing that value down again. The child does not directly modify the parent variable. v-model generates the write-back binding for you. [Vue documentation](https://vuejs.org/guide/components/v-model.html)

## 4. Controlled and rejecting updates

```vue
<script setup lang="ts">
import { ref } from "vue";
const text = ref<string | null>("A");
const requested = ref<string | null>();
const count = ref(0);
function recordOnly(next: string | null) {
  requested.value = next;
  count.value++;
  // Deliberately do not assign text.value = next.
}
</script>

<template>
  <c-input
    :model-value="text"
    edit-mode="direct"
    @update:model-value="recordOnly"
  />
  <p>Parent value: {{ JSON.stringify(text) }}</p>
  <p>Candidate: {{ JSON.stringify(requested) }}; requests: {{ count }}</p>
</template>
```

Select all of A and try entering B. The candidate becomes B and the counter increases, but parent text stays A. The settled input remains A. Native editing text can appear briefly before the component reconciles; judge the final state after the current update settles.

| Item                | Before | After proposing B |
| ------------------- | ------ | ----------------- |
| Parent text         | A      | A                 |
| Candidate           | None   | B                 |
| Final model/display | A      | A                 |

An update event is not proof of acceptance. The parent can accept, reject or correct a candidate.

For an intentionally non-editable field, use readonly/disabled and their documented focus, copy and event semantics. Ignoring updates here demonstrates ownership; it is not the recommended way to implement readonly UI.

## 5. Accept conditionally

A boolean Switch makes the decision easy to see:

```vue
<script setup lang="ts">
import { ref } from "vue";
const enabled = ref(false);
const allowUpdate = ref(false);
const requested = ref<string | number | boolean | null>();
function decide(next: string | number | boolean | null) {
  requested.value = next;
  if (allowUpdate.value && typeof next === "boolean") {
    enabled.value = next;
  }
}
</script>

<template>
  <label
    ><input v-model="allowUpdate" type="checkbox" />Parent accepts
    updates</label
  >
  <c-switch :model-value="enabled" @update:model-value="decide" />
  <p>Parent value: {{ enabled }}；Candidate: {{ JSON.stringify(requested) }}</p>
</template>
```

With the native checkbox unchecked, clicking Switch proposes true but leaves the parent and Switch false. Enable the checkbox, click again, and the parent accepts true.

This uses Switch's default boolean values. Adapt the parent type and decision if checkedValue/uncheckedValue are customized. When acceptance requires asynchronous work, show pending explicitly so a request is not mistaken for a completed change.

## 6. What does v-model generate?

```html
<c-input v-model="text" />
```

The corresponding template binding is:

```html
<c-input :model-value="text" @update:model-value="text = $event" />
```

Script functions assign `text.value = next`; templates unwrap refs automatically.

| Binding                             | Passes an external value? | Writes updates back?                                          | Meaning for strict controlled components |
| ----------------------------------- | ------------------------- | ------------------------------------------------------------- | ---------------------------------------- |
| default-value only                  | No                        | No                                                            | Component stores subsequent values       |
| Update listener only                | No                        | Depends on listener, but not controlling without binding back | Observation                              |
| model-value=A only                  | Yes                       | No                                                            | Final value remains A                    |
| model-value plus recording listener | Yes                       | No                                                            | Observe candidates, keep A               |
| model-value plus assignment handler | Yes                       | Yes                                                           | Parent may filter updates                |
| v-model=text                        | Yes                       | Automatically                                                 | Usually accepts every update             |

For components checking modelValue !== undefined, a v-model ref initialized to undefined still starts uncontrolled. Local proxy exceptions also exist; see section 15.

Adding an update listener to v-model and returning false does not cancel v-model's generated assignment. Use an explicit value binding and handler when rejection matters. Returning false from change is not a guard either. Do not execute the same save twice in both update and change handlers.

## 7. Does emptyValue conflict with controlled state?

The features are compatible. The specific problem is undefined carrying two meanings in a particular binding.

For models using this ownership rule, including Input, InputNumber, Switch, Slider and Select:

```ts
// Conceptual rule, not code users need to add.
const isControlled = modelValue !== undefined;
```

An empty string, 0, false and a supported null are defined values. Validity remains component-specific: a defined 0 is not automatically a valid page number.

| Clear candidate | Parent decision                    | Returned modelValue | Result                                             |
| --------------- | ---------------------------------- | ------------------- | -------------------------------------------------- |
| null            | Accept                             | null                | Controlled if null is supported                    |
| Empty string    | Accept                             | Empty string        | Controlled                                         |
| undefined       | Accept unchanged                   | undefined           | Becomes uncontrolled                               |
| undefined       | Normalize to null                  | null                | Remains controlled                                 |
| Any candidate   | Ignore, retain A                   | A                   | Retains the original controlled state              |
| undefined       | Component was already uncontrolled | Unbound             | Internal empty state; no parent control to release |

Do not infer ownership loss from emptyValue alone. The mode changes when the parent actually passes undefined back, not merely when the factory runs or an event is observed.

## 8. The empty-value forms are different

Current resolveEmptyValue behavior uses each component's fallback when no override is provided:

| Configuration                    | Meaning                                                                 |
| -------------------------------- | ----------------------------------------------------------------------- |
| Omitted                          | Component's current default clear output                                |
| `:empty-value="undefined"`       | Same fallback; does not force undefined output                          |
| `:empty-value="() => undefined"` | Explicit undefined output, where the component type permits the factory |
| `:empty-value="null"`            | Explicit null output                                                    |
| `empty-value="EMPTY"`            | Literal EMPTY string, not necessarily a blank display                   |
| `:empty-value="0"`               | Numeric zero, if valid for this component                               |
| `:empty-value="() => []"`        | New empty array, subject to model and business constraints              |

The factory distinguishes absence from an explicit undefined result. Input's clear type is string/null or a matching factory; do not bypass its type to force an unsupported undefined factory. The next undefined example uses InputNumber, which supports it.

Vue binding matters: `empty-value="null"` is a string, while `:empty-value="null"` is null. An unbound `empty-value="0"` is not a numeric binding.

Verified current default paths:

| Component/path                               | Default candidate without an override                   |
| -------------------------------------------- | ------------------------------------------------------- |
| Input clear button                           | Empty string                                            |
| InputNumber clear button                     | undefined                                               |
| Select single without an empty-string option | Usually empty string                                    |
| Select single with a value='' option         | undefined, distinguishing that option from no selection |
| Select multiple                              | Usually []; protected disabled selections may remain    |

This is not an inventory of all component empty-value contracts. Dates, times and panels have additional paths. emptyValue does not bypass disabled/readonly, pending transactions or protected selections.

## 9. Input clears to null and stays controlled

```vue
<script setup lang="ts">
import { ref } from "vue";
const text = ref<string | null>("A");
const updates = ref<string[]>([]);
function accept(next: string | null) {
  updates.value.push(JSON.stringify(next));
  text.value = next;
}
</script>

<template>
  <c-input
    :model-value="text"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:model-value="accept"
  />
  <p>Parent value: {{ JSON.stringify(text) }}</p>
  <p>Update log: {{ updates.join(" → ") }}</p>
</template>
```

| Action                               | Candidate    | Parent text  | Display |
| ------------------------------------ | ------------ | ------------ | ------- |
| Mount                                | None         | A            | A       |
| Click clear                          | null         | null         | Blank   |
| Type B                               | B            | B            | B       |
| Select all and delete with Backspace | Empty string | Empty string | Blank   |

null and an empty string look blank but are different model values. Current emptyValue controls the clear action; it does not transform manual deletion into null. If your business requires every empty text value to be null, assign `text.value = next === '' ? null : next` in the parent.

Likewise, an Input configured with literal EMPTY emits and displays EMPTY on clear. A clear button does not guarantee a blank final model.

## 10. Why can undefined clear change ownership?

This example observes current behavior. It is not the recommended configuration for a persistently controlled form.

```vue
<script setup lang="ts">
import { ref } from "vue";
const quantity = ref<number | null | undefined>(12);
const clearToUndefined = () => undefined;
const describe = (value: unknown) =>
  value === undefined ? "undefined" : JSON.stringify(value);
const lastRequest = ref("No update yet");
function accept(next: number | null | undefined) {
  lastRequest.value = describe(next);
  quantity.value = next;
}
</script>

<template>
  <c-input-number
    :model-value="quantity"
    :empty-value="clearToUndefined"
    edit-mode="direct"
    clearable
    @update:model-value="accept"
  />
  <p>Parent value: {{ describe(quantity) }}；Candidate: {{ lastRequest }}</p>
  <p>Controlled by the current check: {{ quantity !== undefined }}</p>
</template>
```

| Step                                                     | Parent quantity | quantity !== undefined | Final owner                                      |
| -------------------------------------------------------- | --------------- | ---------------------- | ------------------------------------------------ |
| Initially 12                                             | 12              | true                   | Parent                                           |
| Component proposes undefined, before handling            | Still 12        | true                   | Still parent                                     |
| Parent accepts unchanged                                 | undefined       | false                  | Component                                        |
| Later interaction while parent supplies no defined value | undefined       | false                  | Component may store subsequent values internally |

The trigger is the actual modelValue becoming undefined, not the blank display. A later defined parent value makes it controlled again. Current handoff retention varies between components; do not rely on mode changes for reset.

A ref's declared number/null type does not convert a runtime undefined event into null automatically.

## 11. Recommended: normalize at the parent boundary

```vue
<script setup lang="ts">
import { ref } from "vue";
const quantity = ref<number | null>(12);
const lastRequest = ref("No update yet");
function acceptNormalized(next: number | null | undefined) {
  lastRequest.value = next === undefined ? "undefined" : JSON.stringify(next);
  quantity.value = next ?? null;
}
</script>

<template>
  <c-input-number
    :model-value="quantity"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:model-value="acceptNormalized"
  />
  <p>组件Candidate: {{ lastRequest }}</p>
  <p>Final parent value: {{ JSON.stringify(quantity) }}</p>
  <p>Controlled by the current check: {{ quantity !== undefined }}</p>
</template>
```

This handles the clear button and other update paths producing undefined: null → null, undefined → null, 0 → 0, other numbers unchanged. The parent's quantity remains defined, preserving final controlled ownership.

Why use a handler as well as empty-value=null? InputNumber's clear-button path calls resolveEmptyValue, while manual deletion followed by commit can directly produce undefined. modelEvent='input' may propose the empty value earlier. emptyValue is not an input parser or a normalizer for every submission path.

Avoid `next || null`, which also discards valid zero. Use `next ?? null` for null/undefined only. Do not apply this nullable-number example to a model such as pagination that does not accept null.

A writable computed setter can perform the same normalization behind v-model; a readonly computed cannot accept assignments. Separate local updates from persistence. Usually update the form synchronously and save on explicit submission; if acceptance must wait for approval, keep the old value and show pending deliberately.

## 12. A valid empty-string option differs from no selection

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref<string | null>(null);
const options = [
  { label: "All", value: "" },
  { label: "Enabled only", value: "enabled" },
];
</script>

<template>
  <c-select
    v-model="selected"
    :options="options"
    :empty-value="null"
    edit-mode="direct"
    clearable
  />
  <p>Parent value: {{ JSON.stringify(selected) }}</p>
</template>
```

| Action              | Parent selected | Meaning                        |
| ------------------- | --------------- | ------------------------------ |
| Initially           | null            | No selection                   |
| Choose All          | Empty string    | A valid selected option        |
| Choose Enabled only | enabled         | Another valid option           |
| Clear               | null            | No selection, still controlled |

Do not use selected === '' to mean both All and no selection. Element Plus illustrates a similar case but exposes separate empty-values and value-on-clear APIs. Our emptyValue does not automatically provide its empty-values functionality.

For multiple selection, initialize and clear according to the array model. A nullable single-selection example does not imply that every multi-selection should use null. Protected disabled selections can survive clear; emptyValue does not override that rule.

## 13. Value and popup visibility are separate models

```vue
<script setup lang="ts">
import { ref } from "vue";
const selected = ref<string | null>(null);
const panelOpen = ref(false);
const allowClose = ref(true);
const options = [
  { label: "Hangzhou", value: "hz" },
  { label: "Beijing", value: "bj" },
];
function acceptOpen(next: boolean) {
  if (next || allowClose.value) panelOpen.value = next;
}
</script>

<template>
  <label
    ><input v-model="allowClose" type="checkbox" />Accept close requests</label
  >
  <c-select
    v-model="selected"
    :open="panelOpen"
    :options="options"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:open="acceptOpen"
  />
  <p>Value: {{ JSON.stringify(selected) }}; open: {{ panelOpen }}</p>
  <button type="button" @click="panelOpen = false">
    Parent closes directly
  </button>
</template>
```

The value binding accepts updates directly; the visibility handler can reject close requests. Disable Accept close requests: value changes can still be accepted while close requests are ignored. Parent closes directly changes panelOpen itself.

There is no single global controlled flag for the whole component. Each model has its own owner. v-model:open is shorthand for open plus its update assignment.

This example uses Select's direct editing mode. Confirmation presentations additionally own a draft: selecting edits the draft, confirmation submits it and cancellation discards it. A visible draft changing does not prove the committed model is uncontrolled.

## 14. Initialize, reset and serialize form data

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const form = reactive<{ name: string | null; quantity: number | null }>({
  name: null,
  quantity: null,
});
const payloadText = ref("Not submitted yet");
function updateQuantity(next: number | null | undefined) {
  form.quantity = next ?? null;
}
function reset() {
  form.name = null;
  form.quantity = null;
}
function submit() {
  const payload = {
    name: form.name === null ? undefined : form.name,
    quantity: form.quantity === null ? undefined : form.quantity,
  };
  payloadText.value = JSON.stringify(payload);
}
</script>

<template>
  <c-input
    v-model="form.name"
    :empty-value="null"
    edit-mode="direct"
    clearable
  />
  <c-input-number
    :model-value="form.quantity"
    :empty-value="null"
    edit-mode="direct"
    clearable
    @update:model-value="updateQuantity"
  />
  <button type="button" @click="reset">Reset parent data</button>
  <button type="button" @click="submit">Build payload</button>
  <p>Payload: {{ payloadText }}</p>
</template>
```

This uses an ordinary reactive object without depending on Form layout/validation APIs. The parent initializes and resets its fields. defaultValue does not populate an empty parent form; initialize form.name directly when a name is required initially.

Serialization maps UI null to undefined object properties, which JSON omits, without changing the UI model itself. If the API expects explicit JSON null, retain null in the payload instead.

UI empty values and transport formats need not match. A backend's omitted-field convention does not require modelValue to be undefined. Empty strings are still sent unchanged in this example; omit them explicitly at the serialization boundary if your business requires it.

## 15. Current exceptions

These describe current behavior, not an implemented target contract:

| Scope                                | Difference                                                                                 |
| ------------------------------------ | ------------------------------------------------------------------------------------------ |
| Maple ActionSheet.open               | Default useVModel local proxy can change internal state                                    |
| Maple NumberKeyboard.open/modelValue | Both use the default proxy                                                                 |
| Maple FloatingPanel.modelValue       | Proxy anchor plus separate gesture display height                                          |
| Maple Popup with beforeClose         | Internal visible can intercept external open=false and emit update:open(true) on rejection |
| Both Collapse implementations        | Nullish fallback; null falls back internally, use [] to collapse all                       |

For the first three, ignoring update does not guarantee the display remains unchanged. Passing the same external value again may not trigger the proxy watcher. Both libraries have equivalent useVModel helpers, but Input/Switch/Slider manage their own ownership.

InputNumber may retain intermediate text, Input has IME composition, and Popup can retain transition DOM. Distinguish final models from editing/gesture state and animation retention.

## 16. Documentation patterns worth borrowing

These are references for explanation style, not interchangeable APIs, empty values or handoff rules. All examples above were written for our components.

| Reference                                                                                                                            | Useful teaching pattern                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| [Reka controlled state](https://www.reka-ui.com/docs/guides/controlled-state)                                                        | Place explicit write-back, v-model and defaultValue side by side              |
| [React Input](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable)                     | Explain ownership through visible reversion when updates are ignored          |
| [Radix async Dialog submission](https://www.radix-ui.com/primitives/docs/components/dialog#close-after-asynchronous-form-submission) | Show why a parent closes only after saving                                    |
| [Element Plus Select empty values](https://element-plus.org/en-US/component/select.html#empty-values)                                | Separate empty recognition and clear output using a valid empty-string option |
| [Naive UI controlled state](https://www.naiveui.com/zh-CN/docs/controlled-uncontrolled)                                              | State how undefined affects ownership explicitly                              |

React's native controlled text input should not receive null/undefined. Our Input supports null and renders it blank. Borrow explanations, not framework-specific empty-value constraints. A value-only binding can also be intentional; it is an error only relative to an expectation of accepting edits.

## 17. Proposed design and existing emptyValue

The unified design is not implemented. The recommendation is parent-owned final state, initialize-only defaults, defined domain values for standard clear output, and separate drafts/gestures/animation.

Retain configurable emptyValue output rather than treating every () => undefined as invalid. It remains useful with explicit parent normalization, published APIs and intentional business behavior. Passing the result back unchanged as undefined must still mean uncontrolled under the chosen predicate.

Audit all empty paths separately: clear buttons, keyboard deletion, panel clearing and Form reset. Fixing the button alone leaves gaps. Changing published default empty values, ownership handoff or proxy behavior requires a versioned migration; changing documentation does not implement that behavior.

## 18. Troubleshooting order

1. Identify the exact state: modelValue, open or a draft.
2. Inspect the actual external value, not only the ref's static type or blank display.
3. Record update candidates and inspect whether/how the parent assigns them.
4. Distinguish clear button, manual deletion, panel confirmation and Form reset.
5. Check whether emptyValue is omitted, null, a string or an undefined-returning factory.
6. Check the proxy/guard exceptions in section 15.

Source references: both libraries' packages/_-ui/src/input/use-input-value.ts, input-number/use-number-value.ts, select/use-select-controller.ts and empty-value helpers; packages/_-use/src/useVModel.ts; Maple's listed proxy components and Popup. Expected-value tables explain audited paths; they are not a claim that every component and browser interaction has been verified.

---

Document: llms/en-US/guide/empty-values.md

<!-- Source: docs/en/guide/empty-values.md; locale: en-US; page: /en/guide/empty-values/ -->

# Empty recognition, clear output and reading placeholders

## Choose the setting for your task

| Task                                                       | Setting                                    | Example                               |
| ---------------------------------------------------------- | ------------------------------------------ | ------------------------------------- |
| Emit null, -1 or another supported value when clearing     | empty-value / emptyValue                   | Clear icon and manual deletion        |
| Treat API marker -1 as unselected and missing for required | empty-values / emptyValues                 | Empty markers and required validation |
| Keep an empty string as a valid All option                 | Exclude the empty string from empty-values | Valid empty-string option             |
| Show '-' or No data for empty reading content              | empty-text / emptyText                     | Reading placeholders and inheritance  |

Each prop has one job. emptyValue defines clear output, emptyValues defines empty identity, and emptyText defines reading text. They do not derive one another. Rendering or configuration changes do not write the model or change controlled ownership.

## Learn by scenario

### Clear icon and manual deletion

Clear with the icon to produce null. Restore the initial value and delete all text with Backspace to produce `''`. The model output quotes strings so the two outcomes are visible.

Example source: src/input/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive } from "vue";
const model = reactive({ text: "Hello" as string | null });
</script>
<template>
  <c-space direction="column">
    <p>
      The clear icon produces null; Backspace to empty produces an empty string.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="text" label="Keyword">
        <c-input
          v-model="model.text"
          edit-mode="direct"
          clearable
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.text = 'Hello'">Restore initial value</c-button>
    <p>
      Current model: <output>{{ JSON.stringify(model.text) }}</output>
    </p>
  </c-space>
</template>
```

Manual deletion is an input event and does not invoke emptyValue. Form reset restores recorded initial values. See [Input value model and interaction](llms/en-US/components/input.md).

### Valid empty-string option

All has value `''` and remains selected. emptyValues excludes it with `[null, undefined]`, while emptyValue independently clears to null. Clear, then choose All again and compare model outputs.

Example source: src/select/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ status: "" as string | null });
const multiple = ref(["active"]);
const optional = ref<string | undefined>("active");
const options = [
  { value: "", label: "All" },
  { value: "active", label: "Active" },
];
</script>
<template>
  <c-space direction="column">
    <p>
      All uses an empty string as a valid option value. Clearing produces null.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="status" label="Status">
        <c-select
          v-model="model.status"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined]"
          :empty-value="null"
        />
      </c-form-item>
    </c-form>
    <c-button @click="model.status = ''">Choose All</c-button>
    <p>
      Current model: <output>{{ JSON.stringify(model.status) }}</output>
    </p>
    <c-form layout="vertical">
      <c-form-item label="Multiple: clear to []">
        <c-select
          v-model="multiple"
          :options="options"
          edit-mode="direct"
          multiple
          clearable
          :empty-value="() => []"
        />
        <output>{{ JSON.stringify(multiple) }}</output>
      </c-form-item>
      <c-form-item label="Single: clear to undefined">
        <c-select
          v-model="optional"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="() => undefined"
        />
        <output>{{ String(optional) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

Select preserves empty-string options by default. Explicit settings align field and required semantics. Deleting the search query does not delete selection. See [Select value model and linked fields](llms/en-US/components/select.md).

### Empty markers and valid zero

Include -1 in emptyValues when an API uses it for missing data; also set emptyValue=-1 if clearing should emit it. The initial input is blank while the model stays -1. Set it to 0 to see a valid zero, then clear back to -1.

Example source: src/input-number/__demos__/en-US/empty-value.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ quantity: -1 as number | null | undefined });
const restored = ref<number | null | undefined>(12);
</script>
<template>
  <c-space direction="column">
    <p>
      -1 means missing and renders blank; 0 remains a valid number. Clearing
      produces -1.
    </p>
    <c-form :model="model" layout="vertical">
      <c-form-item field="quantity" label="Quantity">
        <c-input-number
          v-model="model.quantity"
          edit-mode="direct"
          clearable
          :empty-values="[null, undefined, -1]"
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-space wrap>
      <c-button @click="model.quantity = 0">Set to 0</c-button>
      <c-button @click="model.quantity = -1">Set to -1</c-button>
    </c-space>
    <p>
      Current model: <output>{{ String(model.quantity) }}</output>
    </p>
    <p>This field clears to 0 without treating 0 as missing.</p>
    <c-form layout="vertical">
      <c-form-item label="Clear restores valid zero">
        <c-input-number
          v-model="restored"
          edit-mode="direct"
          clearable
          :empty-value="0"
        />
        <output>{{ String(restored) }}</output>
      </c-form-item>
    </c-form>
  </c-space>
</template>
```

0 and false are valid by default; do not classify both with `!value`. InputNumber manual empty commits retain numeric parsing rules and may emit undefined. See [InputNumber numeric input and formatting](llms/en-US/components/input-number.md).

### Empty markers and required validation

Form provides `[null, undefined, -1]` to its fields, while Select defines clear output -1. Validate the initial value, select a department and validate again, then clear and validate the missing value.

Example source: src/form/__demos__/en-US/empty-values-validation.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const model = reactive({ department: -1 as number | null | undefined });
const form = ref();
const result = ref("Not validated");
const options = [
  { value: 1, label: "Engineering" },
  { value: 2, label: "Product" },
];
async function validate() {
  const errors = await form.value.validate();
  result.value = errors ? "Required error" : "Valid";
}
</script>
<template>
  <c-space direction="column">
    <p>
      Validate the initial -1, then select a department and validate again.
      Clearing restores -1.
    </p>
    <c-form
      ref="form"
      :model="model"
      layout="vertical"
      :empty-values="[null, undefined, -1]"
    >
      <c-form-item field="department" label="Department" required>
        <c-select
          v-model="model.department"
          :options="options"
          edit-mode="direct"
          clearable
          :empty-value="-1"
        />
      </c-form-item>
    </c-form>
    <c-button @click="validate">Validate</c-button>
    <p role="status">{{ result }}</p>
    <p>
      Current model: <output>{{ String(model.department) }}</output>
    </p>
  </c-space>
</template>
```

emptyValue=-1 alone does not identify -1 as empty; emptyValues alone does not change clear output. Required runs on validation calls or configured triggers, not merely because an input looks blank. See [Form validation and submission](llms/en-US/components/form.md).

### Reading placeholders and inheritance

Initially, Name inherits Form's default `'-'`, Code uses the FormItem override, Nickname uses the field override, and Quantity remains 0. Change Form's text to No data: only inheriting empty fields change. Toggle reading/editing and observe the unchanged model.

Example source: src/form/__demos__/en-US/empty-text.vue

```vue
<script setup lang="ts">
import { reactive, ref } from "vue";
const reading = ref(true);
const emptyText = ref("-");
const model = reactive({
  name: null as string | null,
  code: null as string | null,
  nickname: null as string | null,
  quantity: 0 as number | null | undefined,
});
</script>
<template>
  <c-space direction="column">
    <p>
      Initially, reading mode shows “-” for Name, overrides for Code and
      Nickname, and the valid number 0 for Quantity.
    </p>
    <c-space wrap>
      <c-button @click="reading = !reading">Toggle reading/editing</c-button>
      <c-button @click="emptyText = 'No data'">Use “No data”</c-button>
      <c-button @click="emptyText = '-'">Use default “-”</c-button>
    </c-space>
    <c-form
      :model="model"
      layout="vertical"
      :read-pretty="reading"
      :empty-text="emptyText"
    >
      <c-form-item field="name" label="Name: inherits Form"
        ><c-input v-model="model.name"
      /></c-form-item>
      <c-form-item
        field="code"
        label="Code: FormItem override"
        empty-text="Unassigned"
        ><c-input v-model="model.code"
      /></c-form-item>
      <c-form-item
        field="nickname"
        label="Nickname: field override"
        empty-text="Unassigned"
        ><c-input v-model="model.nickname" empty-text="Anonymous"
      /></c-form-item>
      <c-form-item field="quantity" label="Quantity"
        ><c-input-number v-model="model.quantity"
      /></c-form-item>
    </c-form>
    <p>
      Current model: <output>{{ JSON.stringify(model) }}</output>
    </p>
  </c-space>
</template>
```

Precedence is **Field > FormItem > Form > '-'**. Explicit emptyText=`''` renders blank; custom read slots win. This text is separate from an input placeholder and never becomes validation or submitted data. See [Form field presentation and interaction](llms/en-US/components/form.md).

## Rules and boundaries

### emptyValues: recognize the current model

Field settings override FormItem, which overrides Form. Lists replace rather than merge. Unconfigured text fields recognize null, undefined and the empty string; Select and numeric fields retain their nullish defaults.

Scalars use includes; 0 and false remain valid by default. Objects use reference identity. Empty arrays always mean an empty collection; nonempty `[null]` does not. An explicit empty list removes additional scalar markers without turning an empty collection into a selection.

Fixed state controls and Upload consume the policy for reading and required without rewriting checked state, bounds or transport. Invalid dates and unfinished numeric drafts retain domain rules.

### emptyValue: define clear output

Omission preserves component defaults. Check each component's supported types: Input declares string/null and corresponding factories. Where undefined output is supported, such as InputNumber and date/time fields, use `:empty-value="() => undefined"`; a directly bound undefined leaves the fallback in place.

Factories run during actual clear actions, not initialization, reading or validation. Arrays follow existing independent-result rules. Output is not automatically classified as empty: clearing to 0 can restore valid data.

Some shared editing panels fall back to defaultValue. Their clear action updates a draft; confirmation commits and cancellation discards it. Clear icons, manual deletion, removing the last item and reset retain component-specific behavior.

### Required and custom rules

With explicit emptyValues, built-in required follows the primary field policy. Unconfigured validation retains each library's behavior; Cedar b-validate and Maple function/Zod validation need not agree on every boundary value.

Custom validators, Zod, min/max and enum receive raw values. A UI marker -1 does not make `number().positive()` accept it; business schemas define optional handling. Recognition also does not imply business validity.

false is valid by default, so required does not mean must agree. Classify false explicitly or require true in a custom agreement rule. Prefer one primary field per FormItem and separate independently validated values.

### Controlled ownership

Business emptiness differs from ownership. Adding -1 or removing undefined from emptyValues does not change existing controlled predicates. Do not replace every internal undefined check with isEmpty: ownership, failed parsing, invalid dates and business markers have distinct meanings.

## Relationship to Element Plus

The separation follows [Element Plus configuration](https://element-plus.org/en-US/component/config-provider.html#empty-values-configurations) and [useEmptyValues](https://github.com/element-plus/element-plus/blob/dev/packages/hooks/use-empty-values/index.ts). Our emptyValue serves the role of valueOnClear; no synonym is added.

We use Form/FormItem inheritance and action-time factories, preserving component defaults and collection rules. Array deep equality, clear-output warnings and ConfigProvider integration are not copied.

---

Document: llms/en-US/guide/llms.md

<!-- Source: docs/guide/llms.en-US.md; locale: en-US; page: /en/guide/llms/ -->

# LLM documentation

Cedar Design Web provides plain text and Markdown documentation for large language models (LLMs), including guides, component APIs and Vue examples. Give an AI coding assistant the online URLs so it can consult the documentation before writing code.

## Online documentation

Assistants that can read web pages can access these URLs directly. **Start with the index and read the component pages relevant to your task.**

| Document | Online URL | When to use |
| --- | --- | --- |
| Documentation index | [https://cedar.show/llms.txt](https://cedar.show/llms.txt) | Find guides and individual component Markdown pages; recommended starting point |
| Full documentation | [https://cedar.show/llms-full.txt](https://cedar.show/llms-full.txt) | Read all documentation and examples when the tool has enough context capacity |

Each component in the index has its own Markdown URL. Open it, give it to an assistant, or save it locally.

## Use with an AI assistant

### Provide the documentation URL

Copy this prompt and add your requirements at the end:

```text
Use Cedar Design Web and Vue 3 to implement my requirements.
Read the official documentation index first: https://cedar.show/llms.txt
Then read the quick start and relevant component pages. Check installation, imports and styles.
Use only the documented props, events, slots and examples.
If an API is not documented, say so instead of guessing.

My requirements:
```

### Add project reference material

If your coding assistant supports documentation sources, add the online index URL above. In your project instructions, ask it to consult the official documentation when using `@cedar-design/ui`.

If the tool cannot access the web, save the files you need as `.txt` or `.md` and attach them to your task. The full document may exceed tool reading limits; prefer the index and individual pages for focused tasks.

## Choose a language

| Language | Documentation index | Full documentation |
| --- | --- | --- |
| 中文 | [https://cedar.show/llms.zh-CN.txt](https://cedar.show/llms.zh-CN.txt) | [https://cedar.show/llms-full.zh-CN.txt](https://cedar.show/llms-full.zh-CN.txt) |
| English | [https://cedar.show/llms.en-US.txt](https://cedar.show/llms.en-US.txt) | [https://cedar.show/llms-full.en-US.txt](https://cedar.show/llms-full.en-US.txt) |

Language-specific files only include authored documentation in that language. Missing translations are not generated automatically. Use the combined index above to find all available pages.

## Content and updates

Files are generated from the guides and component documentation. API tables are retained and Demo references are expanded to Vue source. Relative imports inside examples remain relative to their annotated source paths.

Files are regenerated during each documentation site build and deployed with the site. Check that the documentation matches your installed library version.

---

Document: llms/en-US/index.md

<!-- Source: docs/en/README.md; locale: en-US; page: /en/ -->

## Cedar × Maple. Two platforms, one architecture.

Cedar is the desktop counterpart to Maple. The two libraries align component APIs, interaction semantics and design tokens, so familiar patterns carry across platforms while each keeps the interactions its platform needs.

| | Cedar Design Web | Maple Design Mobile |
| --- | --- | --- |
| Platform | Desktop · mouse and keyboard | Mobile · touch |
| Components | Shared API and behavior conventions | Shared API and behavior conventions |
| Themes | Semantic tokens · brand themes · light and dark modes | Semantic tokens · brand themes · light and dark modes |
| Explore | You are here | [Visit Maple ↗](https://maple.show) |

## Start with Cedar

```shell
pnpm add @cedar-design/ui
```

See the [quick start guide](en/guide/quickstart) for setup, component imports and styles. For mobile applications, explore [Maple Design Mobile](https://maple.show).

## Contributors

孟帅 · 吴甲明

---

Document: llms/en-US/showcase/loading.md

<!-- Source: docs/en/showcase/loading.md; locale: en-US; page: /en/showcase/loading/ -->

# Loading and waiting

Explore an event registration workspace. Try each component, hold all loading states, or start a two-second local wait. Labels in the live scenario are currently in Chinese.

1. Fill in registration information or use the button on its card to start a two-second wait.
2. Enable “全部保持加载” to compare every visible indicator; “重置加载” restores the state without clearing input.
3. Toggle editing independently, then compare default indicators and bottom lines on decorated fields.
4. Open the confirmation dialog to observe before-close feedback, including a rejected close.

Example source: docs/showcase/demos/loading-lab.vue

```vue
<script setup lang="ts">
import { computed, markRaw, onBeforeUnmount, reactive, ref } from 'vue'
import CButton from '../../../src/button'
import '../../../src/button/style'
import CSplitButton from '../../../src/split-button'
import '../../../src/split-button/style'
import CLink from '../../../src/link'
import '../../../src/link/style'
import CSwitch from '../../../src/switch'
import '../../../src/switch/style'
import CTag from '../../../src/tag'
import '../../../src/tag/style'
import CInput from '../../../src/input'
import '../../../src/input/style'
import CTextarea from '../../../src/textarea'
import '../../../src/textarea/style'
import CInputNumber from '../../../src/input-number'
import '../../../src/input-number/style'
import CSelect from '../../../src/select'
import '../../../src/select/style'
import CCascader from '../../../src/cascader'
import '../../../src/cascader/style'
import CAutoComplete from '../../../src/auto-complete'
import '../../../src/auto-complete/style'
import CDate from '../../../src/date'
import '../../../src/date/picker/style'
import CDateRange from '../../../src/date-range'
import CTime from '../../../src/time'
import '../../../src/time/picker/style'
import CTimeRange from '../../../src/time-range'
import CPeopleSelect from '../../../src/people-select'
import '../../../src/people-select/style'
import CSearch from '../../../src/search'
import '../../../src/search/style'
import CFieldDecorator from '../../../src/field-decorator'
import '../../../src/field-decorator/style'
import CTable from '../../../src/table'
import '../../../src/table/style'
import CList from '../../../src/list'
import '../../../src/list/style'
import CSkeleton from '../../../src/skeleton'
import '../../../src/skeleton/style'
import CLoading from '../../../src/loading'
import '../../../src/loading/style'
import CTreeSelect from '../../../src/tree-select'
import '../../../src/tree-select/style'
import CInputTag from '../../../src/input-tag'
import '../../../src/input-tag/style'
import CMention from '../../../src/mention'
import '../../../src/mention/style'
import CForm from '../../../src/form'
import '../../../src/form/style'
import { FormItem as CFormItem } from '../../../src/form'
import CDialog from '../../../src/dialog'
import '../../../src/dialog/style'
const cities = [{ label: '上海', value: 'shanghai' }, { label: '杭州', value: 'hangzhou' }]
const venues = [{ label: '上海', value: 'shanghai', children: [{ label: '设计中心', value: 'studio' }] }]
const fieldCards = [{ id: 'input', component: markRaw(CInput), title: '姓名', description: '查询报名信息', props: { defaultValue: '林小满', placeholder: '姓名' }, text: '', lockable: true },
{ id: 'textarea', component: markRaw(CTextarea), title: '备注', description: '保存报名备注', props: { defaultValue: '希望参加设计工作坊', placeholder: '备注' }, text: '', lockable: true },
{ id: 'input-number', component: markRaw(CInputNumber), title: '同行人数', description: '更新人数', props: { defaultValue: 2, min: 1 }, text: '', lockable: true },
{ id: 'select', component: markRaw(CSelect), title: '活动城市', description: '读取候选城市', props: { defaultValue: 'shanghai', options: cities, editMode: 'direct' }, text: '', lockable: true },
{ id: 'cascader', component: markRaw(CCascader), title: '活动场地', description: '读取级联场地', props: { options: venues, editMode: 'direct' }, text: '', lockable: true },
{ id: 'auto-complete', component: markRaw(CAutoComplete), title: '活动搜索', description: '查询匹配活动', props: { options: ['设计工作坊', '开发者交流'], placeholder: '搜索活动' }, text: '', lockable: true },
{ id: 'date', component: markRaw(CDate), title: '报名日期', description: '读取可选日期', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'date-range', component: markRaw(CDateRange), title: '活动日期范围', description: '查询可用档期', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'time', component: markRaw(CTime), title: '到场时间', description: '读取可用时间', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'time-range', component: markRaw(CTimeRange), title: '参与时段', description: '查询可用时段', props: { editMode: 'direct' }, text: '', lockable: true },
{ id: 'people-select', component: markRaw(CPeopleSelect), title: '同行伙伴', description: '读取人员信息', props: { options: [{ label: '林小满', value: 'lin' }], editMode: 'direct' }, text: '', lockable: true },
{ id: 'search', component: markRaw(CSearch), title: '搜索报名', description: '查询报名记录', props: { placeholder: '输入姓名' }, text: '', lockable: true },
{ id: 'field-decorator', component: markRaw(CFieldDecorator), title: '通用字段容器', description: '观察容器的默认与底线反馈', props: {}, text: '容器内容', lockable: true },
{ id: 'tree-select', component: markRaw(CTreeSelect), title: '组织部门', description: '读取组织树', props: { options: [{ label: '设计部', value: 'design', children: [{ label: '体验组', value: 'ux' }] }], editMode: 'direct' }, text: '', lockable: true },
{ id: 'input-tag', component: markRaw(CInputTag), title: '活动标签', description: '保存标签', props: { defaultValue: ['设计', '交流'] }, text: '', lockable: true },
{ id: 'mention', component: markRaw(CMention), title: '邀请同伴', description: '查询提及候选', props: { options: [{ label: '林小满', value: 'lin' }] }, text: '', lockable: true }]
const actionCards = [{ id: 'button', component: markRaw(CButton), title: '提交报名', description: '业务控制按钮等待', props: {}, text: '提交报名', lockable: true },
{ id: 'split-button', component: markRaw(CSplitButton), title: '报名操作', description: '主按钮等待', props: {}, text: '保存报名', lockable: true },
{ id: 'link', component: markRaw(CLink), title: '查看报名详情', description: '链接等待', props: {}, text: '查看详情', lockable: true },
{ id: 'switch', component: markRaw(CSwitch), title: '接收短信', description: '开关保存', props: { defaultValue: true }, text: '', lockable: true },
{ id: 'tag', component: markRaw(CTag), title: '参与者身份', description: '标签状态更新', props: {}, text: '体验官', lockable: true }]
const groups = [{ title: '01 · 填写与数据选择', cards: fieldCards },
{ title: '02 · 提交与状态操作', cards: actionCards }]
const held = ref(false)
const lock = ref(false)
const line = ref(false)
const pending = reactive<Record<string, boolean>>({})
const completed = reactive<Record<string, boolean>>({})
const timers = new Map<string, ReturnType<typeof setTimeout>>()
const ids = [...fieldCards, ...actionCards].map(card => card.id).concat(['table', 'list', 'skeleton', 'loading'])

const busyCount = computed(() => ids.filter(id => isLoading(id)).length)
const status = ref('点击卡片上的「体验等待」，对照加载与恢复。')
function isLoading(id: string) { return held.value || Boolean(pending[id]) }
function run(id: string) {
  if (held.value || pending[id]) return
  pending[id] = true
  completed[id] = false
  status.value = `${id} 正在等待；2 秒后恢复。`
  timers.set(id, setTimeout(() => {
    pending[id] = false
    completed[id] = true
    timers.delete(id)
    status.value = `${id} 已完成，输入内容保留。`
  }, 2000))
}
function runAll() { held.value = false; ids.forEach(run) }
function reset() {
  held.value = false
  timers.forEach(timer => clearTimeout(timer))
  timers.clear()
  ids.forEach(id => { pending[id] = false; completed[id] = false })
  status.value = '已恢复全部加载状态，填写内容保留。'
}
const open = ref(false)
const allowClose = ref(true)
const guardStatus = ref('打开报名确认，关闭时等待 2 秒。')
const guardWaits = new Map<ReturnType<typeof setTimeout>, (allowed: boolean) => void>()
function beforeClose() {
  guardStatus.value = '正在检查报名状态…'
  return new Promise<boolean>(resolve => {
    const timer = setTimeout(() => {
      guardWaits.delete(timer)
      guardStatus.value = allowClose.value ? '检查通过，允许关闭。' : '本次未通过，弹层保留，可再次尝试。'
      resolve(allowClose.value)
    }, 2000)
    guardWaits.set(timer, resolve)
  })
}
onBeforeUnmount(() => { reset(); guardWaits.forEach((resolve, timer) => { clearTimeout(timer); resolve(false) }); guardWaits.clear() })
const columns = [{ title: '参与人', dataIndex: 'name' }, { title: '活动', dataIndex: 'event' }]
const rows = [{ key: '1', name: '林小满', event: '设计工作坊' }, { key: '2', name: '周青', event: '开发者交流' }]
</script>
<template>
  <div class="loading-lab">
    <header class="loading-lab__hero">
      <p class="loading-lab__eyebrow">LOADING / 活动报名工作台</p>
      <h2>让每一次等待都看得见</h2>
      <p>逐项填写报名信息，观察各组件如何表达等待；也可以保持全部加载，比较位置、尺寸与布局。</p>
      <CForm layout="vertical">
        <div class="loading-lab__controls">
          <CFormItem label="全部保持加载"><CSwitch v-model="held" aria-label="全部保持加载" /></CFormItem>
          <CFormItem label="等待时禁止编辑"><CSwitch v-model="lock" aria-label="等待时禁止编辑" /></CFormItem>
          <CFormItem label="文本字段使用底线"><CSwitch v-model="line" aria-label="文本字段使用底线" /></CFormItem>
        </div>
      </CForm>
      <div class="loading-lab__buttons"><CButton @click="runAll">全部等待 2 秒</CButton><CButton variant="outline" @click="reset">重置加载</CButton><span>{{ busyCount }} / {{ ids.length }} 项正在等待</span></div>
      <p role="status" aria-live="polite">{{ status }}</p>
      <small>所有等待均在本地模拟。loading 与 disabled 分别控制；切换底线只影响支持 loading-mode 的字段。</small>
    </header>
    <section v-for="group in groups" :key="group.title" class="loading-lab__section">
      <h3>{{ group.title }}</h3>
      <div class="loading-lab__grid">
        <article v-for="card in group.cards" :key="card.id" class="loading-lab__card" :data-loading-card="card.id">
          <div class="loading-lab__heading"><strong>{{ card.title }}</strong><code>{{ card.id }}</code></div>
          <p>{{ card.description }}</p>
          <div class="loading-lab__preview">
            <component v-if="card.text" :is="card.component" v-bind="card.id === 'split-button' ? { ...card.props, buttonProps: { loading: isLoading(card.id), disabled: lock && isLoading(card.id) } } : card.props" :loading="isLoading(card.id)" :disabled="lock && isLoading(card.id)" @change="run(card.id)">{{ card.text }}</component>
            <component v-else :is="card.component" v-bind="card.id === 'split-button' ? { ...card.props, buttonProps: { loading: isLoading(card.id), disabled: lock && isLoading(card.id) } } : card.props" :loading="isLoading(card.id)" :loading-mode="line ? 'line' : 'default'" :disabled="lock && isLoading(card.id)" @change="run(card.id)" />
          </div>
          <div class="loading-lab__footer"><CButton size="sm" variant="text" :disabled="isLoading(card.id)" @click="run(card.id)">体验等待</CButton><span>{{ isLoading(card.id) ? '等待中…' : completed[card.id] ? '已完成' : '就绪' }}</span></div>
        </article>
      </div>
    </section>
    <section class="loading-lab__section">
      <h3>03 · 内容区域</h3>
      <div class="loading-lab__grid">
        <article v-for="kind in ['table', 'list', 'skeleton', 'loading']" :key="kind" class="loading-lab__card" :data-loading-card="kind">
          <div class="loading-lab__heading"><strong>{{ {upload:'上传报名材料',table:'报名记录',list:'报名清单',skeleton:'初次读取占位',loading:'通用内容等待'}[kind] }}</strong><code>{{ kind }}</code></div>
          <div class="loading-lab__preview">
            
            <CTable v-if="kind === 'table'" :loading="isLoading(kind)" :columns="columns" :data="rows" :pagination="false" />
            <CList v-if="kind === 'list'" :loading="isLoading(kind)"><p>林小满 · 设计工作坊</p><p>周青 · 开发者交流</p></CList>
            <CSkeleton v-if="kind === 'skeleton'" :loading="isLoading(kind)"><p>报名信息已加载，可以继续填写。</p></CSkeleton>
            <CLoading v-if="kind === 'loading'" :loading="isLoading(kind)" tip="正在读取报名信息"><p class="loading-lab__placeholder">活动报名内容</p></CLoading>
          </div>
          <div class="loading-lab__footer"><CButton size="sm" variant="text" :disabled="isLoading(kind)" @click="run(kind)">体验等待</CButton><span>{{ isLoading(kind) ? '等待中…' : '就绪' }}</span></div>
        </article>
        
        
      </div>
    </section>
    <section class="loading-lab__section loading-lab__guard" data-loading-card="dialog">
      <h3>04 · 确认报名与关闭等待</h3>
      <p>关闭弹层时由 before-close 等待 2 秒。关闭检查不通过时保留弹层；可以切换后再次尝试。</p>
      <CForm layout="vertical"><CFormItem label="允许关闭"><CSwitch v-model="allowClose" aria-label="允许关闭" /></CFormItem></CForm>
      <CButton @click="open = true">打开报名确认</CButton>
      <CDialog v-model:open="open" title="确认报名" :before-close="beforeClose"><p>请确认活动报名信息。点击确认、取消或关闭，观察等待反馈。</p><CForm layout="vertical"><CFormItem label="允许关闭"><CSwitch v-model="allowClose" aria-label="弹层内允许关闭" /></CFormItem></CForm><p role="status">{{ guardStatus }}</p></CDialog>
      <p aria-live="polite">{{ guardStatus }}</p>
    </section>
  </div>
</template>
<style scoped>
.loading-lab { color: var(--c-sys-color-content-primary, inherit); min-width: 0; }
.loading-lab__hero, .loading-lab__guard { padding: 24px; border: 1px solid var(--c-sys-color-outline-default, #dce4e7); border-radius: 18px; background: var(--c-sys-color-surface-container, #f5f8f9); }
.loading-lab__eyebrow { letter-spacing: .12em; font-size: 12px; opacity: .7; }
.loading-lab__hero h2 { margin: 8px 0 12px; font-size: 28px; }
.loading-lab__controls { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; }
.loading-lab__buttons, .loading-lab__footer { display: flex; align-items: center; flex-wrap: wrap; gap: 12px; }
.loading-lab__section { margin-block: 28px; }
.loading-lab__grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px; }
.loading-lab__card { min-width: 0; padding: 20px; border: 1px solid var(--c-sys-color-outline-default, #dce4e7); border-radius: 14px; }
.loading-lab__card--wide { grid-column: 1 / -1; }
.loading-lab__heading { display: flex; flex-wrap: wrap; align-items: center; justify-content: space-between; gap: 8px; }
.loading-lab__heading code { font-size: 12px; opacity: .65; }
.loading-lab__card p { font-size: 13px; opacity: .8; }
.loading-lab__preview { min-height: 72px; padding-block: 18px; min-width: 0; overflow-wrap: anywhere; }
.loading-lab__footer { justify-content: space-between; font-size: 12px; }
.loading-lab__placeholder, .loading-lab__popup { padding: 24px; }
.loading-lab__popup { min-width: 0; max-width: 90vw; }
@media (max-width: 600px) { .loading-lab__grid { grid-template-columns: minmax(0, 1fr); } .loading-lab__hero, .loading-lab__card, .loading-lab__guard { padding: 16px; } .loading-lab__hero h2 { font-size: 24px; } }
</style>
```

This page focuses on input surfaces, data selection, actions and content loading. Ordinary events do not collect Promises. Upload keeps per-file progress and before-hook feedback; Scheduler persistence guards are documented on its own page.

## More before-hook scenarios

### Drawer

Example source: src/drawer/__demos__/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { DrawerBeforeClose } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(true);
const status = ref("");
const check: DrawerBeforeClose = (payload, done, { signal }) => {
  status.value = `等待： ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-form-item layout="vertical" label="允许关闭"><c-switch v-model="allowed" aria-label="允许关闭" /></c-form-item>
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done 回调' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">打开</c-button>
    <c-drawer
      v-model:open="open"
      :before-close="check"
      @guard-error="status = 'Error'"
    >
      <p>关闭前等待片刻。可以关闭开关体验一次拦截，再在抽屉内重新允许关闭并重试。</p>
      <c-form-item layout="vertical" label="允许关闭"><c-switch v-model="allowed" aria-label="抽屉内允许关闭" /></c-form-item>
      <c-button @click="allowed = true; open = false">允许并关闭</c-button>
      <p role="status">{{ status }}</p>
    </c-drawer>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

### Popconfirm

Example source: src/popconfirm/__demos__/guard-protocol.vue

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { PopconfirmBeforeConfirm } from "@cedar-design/ui";
const open = ref(false);
const mode = ref("promise");
const allowed = ref(false);
const status = ref("");
const check: PopconfirmBeforeConfirm = (payload, done, { signal }) => {
  status.value = `等待： ${payload.action}`;
  if (mode.value === "done") {
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      done(!signal.aborted && allowed.value);
    }, 500);
    return;
  }
  return new Promise<boolean>((resolve) =>
    setTimeout(() => {
      status.value = allowed.value ? "允许" : "阻止";
      resolve(!signal.aborted && allowed.value);
    }, 500),
  );
};
</script>
<template>
  <c-space direction="column" align="stretch">
    <c-switch v-model="allowed" />
    <c-form-item layout="vertical" size="sm" label="mode">
      <c-radio-group
        aria-label="mode"
        v-model="mode"
        :options="[
          { value: 'promise', label: 'Promise' },
          { value: 'done', label: 'done 回调' },
        ]"
        variant="button"
        size="sm"
      />
    </c-form-item>
    <c-button @click="open = true">打开</c-button>
    <c-popconfirm
      v-model:open="open"
      :before-confirm="check"
      @guard-error="status = 'Error'"
    >
      <template #default
        ><c-button v-if="true" @click="open = true">Confirm action</c-button
        ><span v-else>通过 beforeClose 关闭</span></template
      >
    </c-popconfirm>
    <p role="status">{{ status }}</p>
  </c-space>
</template>
```

---

Document: llms/en-US/themes.md

<!-- Source: src/themes/README.en-US.md; locale: en-US; page: /en/themes/ -->

# Themes

Start with the basic example, then compare related settings before moving to controlled, asynchronous or combined use cases.

## Basic examples

### Toggle

Example source: src/themes/__demos__/toggle.vue

```vue
<template>
  <c-space direction="column" fill>
    <c-space wrap>
      <c-button status="primary" @click="apply(Themes.default.light)">默认亮色</c-button>
      <c-button status="primary" @click="apply(Themes.default.dark)">默认暗色</c-button>
      <c-button status="primary" @click="apply(Themes.maple.light)">枫叶亮色</c-button>
      <c-button status="primary" @click="apply(Themes.maple.dark)">枫叶暗色</c-button>
    </c-space>

    <div class="preview c-rounded-md c-p-16">
      <div class="c-text-1 c-mb-8">主题预览</div>
      <div class="c-text-3 c-mb-16">主色按钮与语义文字会随 StyleProvider / cedar-theme 变化。</div>
      <c-space>
        <c-button status="primary">Primary</c-button>
        <c-button>Default</c-button>
        <span class="semantic-primary">primary</span>
        <span class="semantic-success">success</span>
        <span class="semantic-warning">warning</span>
      </c-space>
    </div>
  </c-space>
</template>

<script lang="ts" setup>
import { StyleProvider, Themes, type StyleVars } from '@cedar-design/ui'

function apply(theme: StyleVars | null) {
  StyleProvider.setStyleVars(theme)
}
</script>

<style scoped>
.preview {
  background: var(--c-color-fill-2);
  border: 1px solid var(--c-color-border-2);
}

.semantic-primary {
  color: var(--c-color-primary);
}

.semantic-success {
  color: var(--c-color-success);
}

.semantic-warning {
  color: var(--c-color-warning);
}
</style>
```