@yunlefun/vue 0.3.0 → 0.4.0

package/README.md

@@ -38,6 +38,8 @@ export default defineNuxtConfig({
 
 根入口目前提供类型和组件目录信息，组件通过 `components/*.vue` 子路径或 Nuxt 模块使用；没有公开的 `YlfResolver`。
 
+组件子路径提供预生成类型声明，运行时继续使用原始 SFC。现有 15 个 Reka UI 封装的验收范围见[组件验收](../guide/component-acceptance.md)。
+
 更多内容见 [Vue 接入](./index.md)、[子包职责](../guide/packages.md)与[设计体系](../guide/design-system.md)。
 
 ## AI 提示词入口

package/components/YlfAccordion.vue

@@ -9,7 +9,7 @@ interface AccordionItemData {
 }
 
 withDefaults(defineProps<{
-  items: AccordionItemData[]
+  items: readonly AccordionItemData[]
   type?: 'single' | 'multiple'
   collapsible?: boolean
 }>(), {

package/components/YlfAvatar.vue

@@ -10,13 +10,14 @@ withDefaults(defineProps<{
 }>(), {
   size: 'md',
   fallback: '',
+  alt: '',
 })
 </script>
 
 <template>
   <AvatarRoot class="ylf-avatar" :class="`ylf-avatar--${size}`">
     <AvatarImage v-if="src" :src="src" :alt="alt" class="ylf-avatar__img" />
-    <AvatarFallback class="ylf-avatar__fallback" :delay-ms="200">
+    <AvatarFallback class="ylf-avatar__fallback" :delay-ms="200" :role="alt || fallback ? 'img' : undefined" :aria-label="alt || fallback || undefined">
       {{ fallback }}
     </AvatarFallback>
   </AvatarRoot>

package/components/YlfDialog.vue

@@ -13,11 +13,15 @@ import {
 } from 'reka-ui'
 import { computed, useSlots } from 'vue'
 
+defineOptions({ inheritAttrs: false })
+
 const props = withDefaults(defineProps<{
   title?: string
   description?: string
   /** 没有可见标题时供屏幕阅读器使用 */
   accessibleTitle?: string
+  /** Existing container in the same theme boundary. */
+  portalTo?: string | HTMLElement
 }>(), {
   accessibleTitle: '对话框',
 })
@@ -37,9 +41,9 @@ const descriptionProps = computed(() => hasDescription.value
       <slot name="trigger" />
     </DialogTrigger>
 
-    <DialogPortal>
+    <DialogPortal :to="portalTo">
       <DialogOverlay class="ylf-dialog__overlay" />
-      <DialogContent class="ylf-dialog__content" v-bind="descriptionProps">
+      <DialogContent class="ylf-dialog__content" v-bind="{ ...descriptionProps, ...$attrs }">
         <DialogTitle v-if="hasVisibleTitle" class="ylf-dialog__title">
           <slot name="title">
             {{ title }}
@@ -110,6 +114,8 @@ const descriptionProps = computed(() => hasDescription.value
 
 .ylf-dialog__title {
   margin: 0 0 6px;
+  padding-right: 32px;
+  overflow-wrap: anywhere;
   font-family: var(--ylf-font-heading, inherit);
   font-size: 19px;
   font-weight: 700;
@@ -118,6 +124,7 @@ const descriptionProps = computed(() => hasDescription.value
 
 .ylf-dialog__desc {
   margin: 0 0 16px;
+  overflow-wrap: anywhere;
   font-size: 14px;
   line-height: 1.6;
   color: var(--ylf-c-text-2, #475569);
@@ -146,12 +153,26 @@ const descriptionProps = computed(() => hasDescription.value
     color: var(--ylf-c-text, #0f172a);
   }
 
+  &:focus-visible {
+    outline: 2px solid var(--ylf-c-brand, #2563eb);
+    outline-offset: 2px;
+  }
+
   svg {
     width: 18px;
     height: 18px;
   }
 }
 
+@media (pointer: coarse) {
+  .ylf-dialog__close {
+    top: 10px;
+    right: 10px;
+    width: 44px;
+    height: 44px;
+  }
+}
+
 @keyframes ylf-dialog-overlay-in {
   from {
     opacity: 0;

package/components/YlfDropdownMenu.vue

@@ -1,6 +1,15 @@
 <script lang="ts" setup>
 import { DropdownMenuContent, DropdownMenuItem, DropdownMenuPortal, DropdownMenuRoot, DropdownMenuSeparator, DropdownMenuTrigger } from 'reka-ui'
 
+defineOptions({ inheritAttrs: false })
+
+defineProps<{
+  items: readonly MenuItem[]
+  portalTo?: string | HTMLElement
+}>()
+
+const emit = defineEmits<{ select: [value: string] }>()
+
 interface MenuItem {
   label?: string
   value?: string
@@ -9,27 +18,23 @@ interface MenuItem {
   separator?: boolean
 }
 
-defineProps<{
-  items: MenuItem[]
-}>()
-
-const emit = defineEmits<{ select: [value: string] }>()
+const open = defineModel<boolean>('open', { default: false })
 </script>
 
 <template>
-  <DropdownMenuRoot>
+  <DropdownMenuRoot v-model:open="open">
     <DropdownMenuTrigger as-child>
       <slot name="trigger" />
     </DropdownMenuTrigger>
-    <DropdownMenuPortal>
-      <DropdownMenuContent class="ylf-menu" :side-offset="6" align="start">
+    <DropdownMenuPortal :to="portalTo">
+      <DropdownMenuContent v-bind="$attrs" class="ylf-menu" :side-offset="6" align="start">
         <template v-for="(it, i) in items" :key="i">
           <DropdownMenuSeparator v-if="it.separator" class="ylf-menu__sep" />
           <DropdownMenuItem
             v-else
             class="ylf-menu__item"
             :disabled="it.disabled"
-            @select="it.value && emit('select', it.value)"
+            @select="it.value !== undefined && emit('select', it.value)"
           >
             {{ it.label }}
           </DropdownMenuItem>
@@ -83,6 +88,12 @@ const emit = defineEmits<{ select: [value: string] }>()
   }
 }
 
+@media (pointer: coarse) {
+  .ylf-menu__item {
+    min-height: 44px;
+  }
+}
+
 @keyframes ylf-pop-in {
   from {
     opacity: 0;

package/components/YlfPopover.vue

@@ -1,9 +1,12 @@
 <script lang="ts" setup>
 import { PopoverArrow, PopoverContent, PopoverPortal, PopoverRoot, PopoverTrigger } from 'reka-ui'
 
+defineOptions({ inheritAttrs: false })
+
 withDefaults(defineProps<{
   side?: 'top' | 'right' | 'bottom' | 'left'
   align?: 'start' | 'center' | 'end'
+  portalTo?: string | HTMLElement
 }>(), {
   side: 'bottom',
   align: 'center',
@@ -17,8 +20,8 @@ const open = defineModel<boolean>('open', { default: false })
     <PopoverTrigger as-child>
       <slot name="trigger" />
     </PopoverTrigger>
-    <PopoverPortal>
-      <PopoverContent :side="side" :align="align" :side-offset="8" class="ylf-popover">
+    <PopoverPortal :to="portalTo">
+      <PopoverContent v-bind="$attrs" :side="side" :align="align" :side-offset="8" class="ylf-popover">
         <slot />
         <PopoverArrow class="ylf-popover__arrow" :width="12" :height="6" />
       </PopoverContent>

package/components/YlfProgress.vue

@@ -4,7 +4,8 @@ import { ProgressIndicator, ProgressRoot } from 'reka-ui'
 import { computed } from 'vue'
 
 const props = withDefaults(defineProps<{
-  value?: number
+  /** null means that progress is unknown. */
+  value?: number | null
   max?: number
   /** 进度条填充：brand 主色或 accent 纯色；aurora 是 accent 的旧别名 */
   variant?: 'brand' | 'accent' | 'aurora'
@@ -16,20 +17,24 @@ const props = withDefaults(defineProps<{
   tone: 'blue',
 })
 
-const percent = computed(() => Math.max(0, Math.min(100, (props.value / props.max) * 100)))
+const safeMax = computed(() => Number.isFinite(props.max) && props.max > 0 ? props.max : 100)
+const safeValue = computed(() => props.value === null || !Number.isFinite(props.value)
+  ? null
+  : Math.max(0, Math.min(safeMax.value, props.value)))
+const percent = computed(() => safeValue.value === null ? null : safeValue.value / safeMax.value * 100)
 </script>
 
 <template>
   <ProgressRoot
-    :model-value="value"
-    :max="max"
+    :model-value="safeValue"
+    :max="safeMax"
     class="ylf-progress"
     :data-ylf-tone="tone"
     :class="`ylf-progress--${variant}`"
   >
     <ProgressIndicator
       class="ylf-progress__indicator"
-      :style="{ transform: `translateX(-${100 - percent}%)` }"
+      :style="{ transform: percent === null ? undefined : `translateX(-${100 - percent}%)` }"
     />
   </ProgressRoot>
 </template>
@@ -52,6 +57,20 @@ const percent = computed(() => Math.max(0, Math.min(100, (props.value / props.ma
   transition: transform 0.4s var(--ylf-ease-bounce, cubic-bezier(0.34, 1.56, 0.64, 1));
 }
 
+.ylf-progress[data-state='indeterminate'] .ylf-progress__indicator {
+  width: 40%;
+  animation: ylf-progress-indeterminate 1.4s ease-in-out infinite;
+}
+
+@keyframes ylf-progress-indeterminate {
+  from {
+    transform: translateX(-100%);
+  }
+  to {
+    transform: translateX(250%);
+  }
+}
+
 .ylf-progress--accent .ylf-progress__indicator,
 .ylf-progress--aurora .ylf-progress__indicator {
   background: var(--ylf-accent, var(--ylf-c-brand, #2563eb));
@@ -61,5 +80,10 @@ const percent = computed(() => Math.max(0, Math.min(100, (props.value / props.ma
   .ylf-progress__indicator {
     transition: none;
   }
+
+  .ylf-progress[data-state='indeterminate'] .ylf-progress__indicator {
+    animation: none;
+    transform: translateX(75%);
+  }
 }
 </style>

package/components/YlfRadioGroup.vue

@@ -1,6 +1,7 @@
 <script lang="ts" setup>
 // 行为 / 可访问性由 reka-ui 提供（role=radiogroup、方向键 roving focus）；皮肤走 token。
 import { RadioGroupIndicator, RadioGroupItem, RadioGroupRoot } from 'reka-ui'
+import { nextTick } from 'vue'
 
 interface RadioOption {
   label: string
@@ -8,8 +9,8 @@ interface RadioOption {
   disabled?: boolean
 }
 
-withDefaults(defineProps<{
-  options: RadioOption[]
+const props = withDefaults(defineProps<{
+  options: readonly RadioOption[]
   disabled?: boolean
   orientation?: 'vertical' | 'horizontal'
 }>(), {
@@ -18,6 +19,22 @@ withDefaults(defineProps<{
 })
 
 const model = defineModel<string>()
+
+function selectFocusedRadio(event: KeyboardEvent) {
+  if (props.disabled || !event.defaultPrevented || !['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key))
+    return
+  const group = event.currentTarget as HTMLElement
+  // Reka 2.10.x defers selection until after focus; a fast keyup can clear its flag.
+  // Let Reka move focus and skip disabled items, then synchronize that choice.
+  nextTick(() => {
+    const focused = document.activeElement
+    if (!(focused instanceof HTMLElement) || !group.contains(focused) || focused.getAttribute('role') !== 'radio')
+      return
+    const option = props.options.find(option => option.value === focused.getAttribute('value'))
+    if (option && !option.disabled && model.value !== option.value)
+      model.value = option.value
+  })
+}
 </script>
 
 <template>
@@ -27,6 +44,7 @@ const model = defineModel<string>()
     :orientation="orientation"
     class="ylf-radio-group"
     :class="`ylf-radio-group--${orientation}`"
+    @keydown="selectFocusedRadio"
   >
     <RadioGroupItem
       v-for="opt in options"

package/components/YlfSegmentedControl.vue

@@ -155,7 +155,7 @@ function updateValue(value: unknown): void {
 
 .ylf-segmented__count {
   min-width: 16px;
-  color: var(--ylf-c-text-3, #64748b);
+  color: var(--ylf-c-text-2, #475569);
   font-size: 10px;
   font-variant-numeric: tabular-nums;
   text-align: center;

package/components/YlfSelect.vue

@@ -11,10 +11,16 @@ const props = withDefaults(defineProps<{
   size?: 'sm' | 'md'
   placeholder?: string
   disabled?: boolean
+  /** Native form field name and validation. */
+  name?: string
+  required?: boolean
+  /** Existing container in the same theme boundary. */
+  portalTo?: string | HTMLElement
 }>(), {
   size: 'md',
   placeholder: '请选择',
   disabled: false,
+  required: false,
 })
 
 const model = defineModel<T>()
@@ -22,7 +28,7 @@ const selectedOption = computed(() => props.options.find(option => option.value
 </script>
 
 <template>
-  <SelectRoot v-model="model" :disabled="disabled">
+  <SelectRoot v-model="model" :disabled="disabled" :name="name" :required="required">
     <SelectTrigger class="ylf-select__trigger" :data-size="size" :aria-label="$attrs.id || $attrs['aria-labelledby'] ? undefined : placeholder" v-bind="$attrs">
       <SelectValue :placeholder="placeholder" class="ylf-select__label">
         <span v-if="selectedOption?.color" class="ylf-select__swatch" :style="{ backgroundColor: selectedOption.color }" aria-hidden="true" />
@@ -36,7 +42,7 @@ const selectedOption = computed(() => props.options.find(option => option.value
         </slot>
       </SelectIcon>
     </SelectTrigger>
-    <SelectPortal>
+    <SelectPortal :to="portalTo">
       <SelectContent class="ylf-select__content" :data-size="size" position="popper" :side-offset="6">
         <SelectViewport class="ylf-select__viewport">
           <SelectItem

package/components/YlfSlider.vue

@@ -6,13 +6,19 @@ withDefaults(defineProps<{
   max?: number
   step?: number
   disabled?: boolean
+  /** Accessible name for a single value or the range as a whole. */
+  label?: string
+  /** Per-thumb accessible names, such as minimum and maximum price. */
+  thumbLabels?: readonly string[]
 }>(), {
   min: 0,
   max: 100,
   step: 1,
   disabled: false,
+  label: '数值',
 })
 
+const emit = defineEmits<{ valueCommit: [value: number[]] }>()
 const model = defineModel<number[]>({ default: () => [50] })
 </script>
 
@@ -24,11 +30,17 @@ const model = defineModel<number[]>({ default: () => [50] })
     :step="step"
     :disabled="disabled"
     class="ylf-slider"
+    @value-commit="emit('valueCommit', $event)"
   >
     <SliderTrack class="ylf-slider__track">
       <SliderRange class="ylf-slider__range" />
     </SliderTrack>
-    <SliderThumb v-for="(_, i) in model" :key="i" class="ylf-slider__thumb" />
+    <SliderThumb
+      v-for="(_, i) in model"
+      :key="i"
+      class="ylf-slider__thumb"
+      :aria-label="thumbLabels?.[i] || (model.length === 1 ? label : `${label} ${i + 1}`)"
+    />
   </SliderRoot>
 </template>
 
@@ -66,7 +78,7 @@ const model = defineModel<number[]>({ default: () => [50] })
     width: 18px;
     height: 18px;
     border-radius: 50%;
-    background: #fff;
+    background: var(--ylf-c-surface, #fff);
     border: 2px solid var(--ylf-c-brand, #2563eb);
     box-shadow: var(--ylf-shadow-sm, 0 2px 8px -2px rgba(15, 23, 42, 0.12));
     cursor: grab;
@@ -86,4 +98,22 @@ const model = defineModel<number[]>({ default: () => [50] })
     }
   }
 }
+
+@media (pointer: coarse) {
+  .ylf-slider {
+    height: 44px;
+  }
+
+  .ylf-slider__thumb::before {
+    position: absolute;
+    inset: -13px;
+    content: '';
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ylf-slider__thumb {
+    transition: none;
+  }
+}
 </style>

package/components/YlfTabs.vue

@@ -8,7 +8,7 @@ interface TabItem {
 }
 
 withDefaults(defineProps<{
-  items: TabItem[]
+  items: readonly TabItem[]
   orientation?: 'horizontal' | 'vertical'
 }>(), {
   orientation: 'horizontal',

package/components/YlfTooltip.vue

@@ -2,11 +2,14 @@
 // 行为 / 定位 / a11y 由 reka-ui 提供；皮肤走 token。
 import { TooltipArrow, TooltipContent, TooltipPortal, TooltipProvider, TooltipRoot, TooltipTrigger } from 'reka-ui'
 
+defineOptions({ inheritAttrs: false })
+
 withDefaults(defineProps<{
   content?: string
   side?: 'top' | 'right' | 'bottom' | 'left'
   delay?: number
   disabled?: boolean
+  portalTo?: string | HTMLElement
 }>(), {
   side: 'top',
   delay: 300,
@@ -17,10 +20,10 @@ withDefaults(defineProps<{
 <template>
   <TooltipProvider :delay-duration="delay">
     <TooltipRoot :disabled="disabled">
-      <TooltipTrigger as-child>
+      <TooltipTrigger as-child v-bind="$attrs">
         <slot />
       </TooltipTrigger>
-      <TooltipPortal>
+      <TooltipPortal :to="portalTo">
         <TooltipContent :side="side" :side-offset="6" class="ylf-tooltip">
           <slot name="content">
             {{ content }}

package/components/accordion/demo.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 const items = [
   { value: 'a', title: '什么是 YunLeFun Design？', content: '云乐坊设计系统，统一设计规范、品牌视觉与 UI 实现；默认晴空蓝为主，高饱和纯色点缀。' },
-  { value: 'b', title: '为什么基于 reka-ui？', content: 'reka 管行为与可访问性，我们只管皮肤——省心，且无障碍达标。' },
+  { value: 'b', title: '为什么基于 reka-ui？', content: 'Reka UI 提供键盘、焦点和 ARIA 行为，云乐坊提供产品接口与主题；封装后的场景仍需逐项验收。' },
   { value: 'c', title: '支持暗色吗？', content: '晴空白与深蓝夜空两套中性色，token 驱动，零配置随主题切换。' },
 ]
 </script>

package/components/accordion/index.md

@@ -17,3 +17,5 @@ title_zh: 手风琴
 ## Slots
 
 每项内容可用 `value` 同名插槽覆盖 `content`。
+
+`items` 支持只读数组。单开模式全部收起时值为 `undefined`，多开模式为字符串数组；调用方应允许收起状态。方向键、Home / End 在标题间移动焦点，跳过禁用项。

package/components/avatar/index.md

@@ -10,6 +10,8 @@ title_zh: 头像
 | 属性       | 说明                   | 类型             | 默认值 |
 | ---------- | ---------------------- | ---------------- | ------ |
 | `src`      | 图片地址               | `string`         | —      |
-| `alt`      | 替代文字               | `string`         | —      |
+| `alt`      | 替代文字               | `string`         | `''`   |
 | `fallback` | 回退文字（如姓名首字） | `string`         | —      |
 | `size`     | 尺寸                   | `sm \| md \| lg` | `md`   |
+
+有意义的头像使用完整 `alt`（例如用户姓名）；图片缺失时，回退图像也使用该名称。没有 `alt` 时回退文字作为名称；仅装饰的图片可保留空 `alt`。`fallback` 决定显示的文字，不会从图片地址自动推断姓名。

package/components/checkbox/demo.vue

@@ -1,28 +1,29 @@
 <script setup lang="ts">
-import { ref } from 'vue'
+import { ref, useId } from 'vue'
 
 const a = ref(true)
 const b = ref(false)
 const c = ref<boolean | 'indeterminate'>('indeterminate')
+const id = useId()
 </script>
 
 <template>
   <div class="flex flex-col gap-4">
     <div class="flex items-center gap-2">
-      <YlfCheckbox v-model="a" />
-      <span class="text-sm">已勾选</span>
+      <YlfCheckbox :id="`${id}-checked`" v-model="a" />
+      <label :for="`${id}-checked`" class="text-sm">已勾选</label>
     </div>
     <div class="flex items-center gap-2">
-      <YlfCheckbox v-model="b" />
-      <span class="text-sm">未勾选</span>
+      <YlfCheckbox :id="`${id}-unchecked`" v-model="b" />
+      <label :for="`${id}-unchecked`" class="text-sm">未勾选</label>
     </div>
     <div class="flex items-center gap-2">
-      <YlfCheckbox v-model="c" />
-      <span class="text-sm">半选 indeterminate</span>
+      <YlfCheckbox :id="`${id}-mixed`" v-model="c" />
+      <label :for="`${id}-mixed`" class="text-sm">半选 indeterminate</label>
     </div>
     <div class="flex items-center gap-2 op-60">
-      <YlfCheckbox :model-value="true" disabled />
-      <span class="text-sm">禁用</span>
+      <YlfCheckbox :id="`${id}-disabled`" :model-value="true" disabled />
+      <label :for="`${id}-disabled`" class="text-sm">禁用</label>
     </div>
   </div>
 </template>

package/components/checkbox/index.md

@@ -12,3 +12,5 @@ title_zh: 复选框
 | `v-model`  | 勾选状态   | `boolean \| 'indeterminate'` | `false` |
 | `value`    | 表单提交值 | `string`                     | —       |
 | `disabled` | 禁用       | `boolean`                    | `false` |
+
+每个复选框必须有可访问名称：传入 `aria-label="同意服务条款"`，或通过 `id` 与 `<label for>` 关联。旁边的普通 `<span>` 不会自动成为标签。`name` 和 `required` 透传给 Reka UI；置于原生表单时，勾选值进入 `FormData`，禁用项不提交。

package/components/dialog/index.md

@@ -7,15 +7,18 @@ title_zh: 对话框
 
 ## Props
 
-| 属性              | 说明                             | 类型      | 默认值     |
-| ----------------- | -------------------------------- | --------- | ---------- |
-| `v-model:open`    | 显隐状态                         | `boolean` | `false`    |
-| `title`           | 可见标题                         | `string`  | —          |
-| `description`     | 描述                             | `string`  | —          |
-| `accessibleTitle` | 无可见标题时供辅助技术读取的标题 | `string`  | `'对话框'` |
+| 属性              | 说明                             | 类型                    | 默认值                  |
+| ----------------- | -------------------------------- | ----------------------- | ----------------------- |
+| `v-model:open`    | 显隐状态                         | `boolean`               | `false`                 |
+| `title`           | 可见标题                         | `string`                | —                       |
+| `description`     | 描述                             | `string`                | —                       |
+| `accessibleTitle` | 无可见标题时供辅助技术读取的标题 | `string`                | `'对话框'`              |
+| `portalTo`        | 已存在的主题内浮层容器           | `string \| HTMLElement` | ConfigProvider / `body` |
 
 建议始终提供 `title`。只有视觉设计明确隐藏标题时，才改用描述场景的 `accessible-title`。
 
+`class`、`id`、`data-*` 和事件传给对话框内容；显式的 `aria-describedby` 可关联调用方的说明。焦点陷阱、Escape 关闭和关闭后回到触发器仍由 Reka UI 管理。局部主题中把 `portal-to` 指向同一主题边界内的容器。长标题会换行并为关闭按钮保留空间。
+
 ## Registry
 
 Dialog 可通过 [Registry 分发](/guide/registry)复制源码；安装时会自动带入 `reka-ui`、Sass 与共享 token。

package/components/dropdown-menu/index.md

@@ -7,9 +7,13 @@ title_zh: 下拉菜单
 
 ## Props
 
-| 属性    | 说明   | 类型         | 默认值 |
-| ------- | ------ | ------------ | ------ |
-| `items` | 菜单项 | `MenuItem[]` | —      |
+| 属性           | 说明                   | 类型                    | 默认值                  |
+| -------------- | ---------------------- | ----------------------- | ----------------------- |
+| `items`        | 菜单项                 | `readonly MenuItem[]`   | —                       |
+| `v-model:open` | 显隐状态               | `boolean`               | `false`                 |
+| `portalTo`     | 已存在的主题内浮层容器 | `string \| HTMLElement` | ConfigProvider / `body` |
+
+`class`、`data-*`、ARIA 属性和事件传给菜单内容。`portal-to` 可把菜单放入已有的局部主题容器；未传时继续使用 ConfigProvider 或 `body`。支持方向键、Home / End、Enter 选择和 Escape 关闭；禁用项会被跳过。
 
 ### MenuItem
 
@@ -25,3 +29,5 @@ title_zh: 下拉菜单
 | 名称     | 说明                         |
 | -------- | ---------------------------- |
 | `select` | 选中某项时触发，回传 `value` |
+
+`value=""` 可表示“全部”或“清除筛选”，仍会触发 `select`。没有 `value` 的项不触发选值事件。

package/components/popover/demo.vue

@@ -1,5 +1,5 @@
 <template>
-  <YlfPopover side="bottom" align="start">
+  <YlfPopover side="bottom" align="start" aria-label="云乐坊介绍">
     <template #trigger>
       <YlfButton variant="primary">
         打开浮层

package/components/popover/index.md

@@ -7,11 +7,14 @@ title_zh: 浮层
 
 ## Props
 
-| 属性           | 说明     | 类型                             | 默认值   |
-| -------------- | -------- | -------------------------------- | -------- |
-| `v-model:open` | 显隐状态 | `boolean`                        | `false`  |
-| `side`         | 方向     | `top \| right \| bottom \| left` | `bottom` |
-| `align`        | 对齐     | `start \| center \| end`         | `center` |
+| 属性           | 说明                   | 类型                             | 默认值                  |
+| -------------- | ---------------------- | -------------------------------- | ----------------------- |
+| `v-model:open` | 显隐状态               | `boolean`                        | `false`                 |
+| `side`         | 方向                   | `top \| right \| bottom \| left` | `bottom`                |
+| `align`        | 对齐                   | `start \| center \| end`         | `center`                |
+| `portalTo`     | 已存在的主题内浮层容器 | `string \| HTMLElement`          | ConfigProvider / `body` |
+
+`class`、`data-*`、ARIA 属性和事件传给浮层内容，内部关联 ID 由 Reka UI 管理。默认可访问名称与触发器关联；触发器应使用说明用途的文字。局部主题的 `portal-to` 容器应处于相同主题边界。
 
 ## Slots
 

package/components/progress/index.md

@@ -9,9 +9,11 @@ title_zh: 进度条
 
 | 属性      | 说明                      | 类型                                            | 默认值  |
 | --------- | ------------------------- | ----------------------------------------------- | ------- |
-| `value`   | 当前进度                  | `number`                                        | `0`     |
+| `value`   | 当前进度；`null` 表示未知 | `number \| null`                                | `0`     |
 | `max`     | 最大值                    | `number`                                        | `100`   |
 | `variant` | 填充                      | `brand \| accent`                               | `brand` |
 | `tone`    | 强调色，仅作用于 `accent` | `blue \| sun \| cyan \| coral \| pink \| green` | `blue`  |
 
 `tone` 接受 `blue | sun | cyan | coral | pink | green`，默认 `blue`（晴空蓝），只在 `accent` 下生效。旧 `aurora` 值映射到 `accent`。同一流程中的同类状态使用同一种颜色。
+
+提供用途名称，例如 `aria-label="文件上传进度"`。有限数值会限制在 `0…max`，无效的 `max` 回退到 `100`，确保显示与 ARIA 值一致。`null`、NaN 或无限值按未知进度显示，不输出 `aria-valuenow`；减少动态效果时显示静态进度段。

package/components/radio/demo.vue

@@ -12,7 +12,7 @@ const options = [
 
 <template>
   <div class="flex flex-col gap-4">
-    <YlfRadioGroup v-model="picked" :options="options" orientation="horizontal" />
+    <YlfRadioGroup v-model="picked" :options="options" orientation="horizontal" aria-label="主题颜色" />
     <p class="text-sm op-70">
       当前：{{ picked }}
     </p>

package/components/radio/index.md

@@ -21,3 +21,5 @@ title_zh: 单选框
 | `label`    | 文案     | `string`   |
 | `value`    | 值       | `string`   |
 | `disabled` | 禁用该项 | `boolean?` |
+
+`options` 支持只读数组。通过 `aria-label` 或 `aria-labelledby` 指定整组名称，单项名称来自 `label`。方向键跳过禁用项；`name` / `required` 透传给 Reka UI，可用于原生表单。