@greypan/web-ui 2.1.7 → 3.0.0

package/README.CN.md

@@ -33,7 +33,7 @@ import '@greypan/web-ui'
 
 ### React
 
-需要 `@types/react >= 16` 作为可选 peer 依赖。
+需要 `@types/react >= 19` 作为可选 peer 依赖。
 
 ```ts
 // vite.config.ts
@@ -56,7 +56,7 @@ function App() {
       <web-ui-button variant="primary" onClick={() => alert('点击')}>
         按钮
       </web-ui-button>
-      <web-ui-input onInput={e => console.log((e.target as any).value)} />
+      <web-ui-input onInput={e => console.log(e.currentTarget.value)} />
     </>
   )
 }
@@ -65,8 +65,11 @@ function App() {
 #### React 自定义元素事件与布尔属性
 
 React 19 按 JSX 键名中的 `on` 后缀原样注册 Custom Element 事件。事件名大小写敏感：`open-change`
-必须绑定为 `onopen-change`，不能写成 `onOpenChange`。标准 `input` 和 `change` 事件仍使用 React
-惯用的 `onInput` 和 `onChange`。布尔属性遵循原生 HTML 语义：属性缺失为 `false`，属性存在为 `true`。
+必须绑定为 `onopen-change`，不能写成 `onOpenChange`。标准 `input`、`change`、`focus`、`blur`
+事件使用 React 惯用的 `onInput`、`onChange`、`onFocus`、`onBlur` handler——其 `currentTarget`
+类型为组件实例，value/checked 读取无需 cast；`target` 遵循 React SyntheticEvent 语义（`EventTarget`），
+不承诺为组件实例。kebab-case 自定义事件携带精确类型的 `CustomEvent` detail。
+布尔属性遵循原生 HTML 语义：属性缺失为 `false`，属性存在为 `true`。
 
 ```tsx
 <web-ui-dialog
@@ -96,7 +99,7 @@ useEffect(() => {
 
 ### Vue
 
-需要 `vue >= 3` 作为可选 peer 依赖。
+需要 `vue >= 3.5` 作为可选 peer 依赖。
 
 ```ts
 // vite.config.ts
@@ -120,9 +123,25 @@ import '@greypan/web-ui/types/vue'
 <template>
   <web-ui-button variant="primary" @click="handleClick">按钮</web-ui-button>
   <web-ui-input v-model="value" />
+  <web-ui-select :value="framework" @change="framework = $event.target.value" />
 </template>
 ```
 
+Vue 事件类型零 cast：带值组件上的 `@input`/`@change` 解析到组件 emit，`$event.target` 即为组件实例，
+`value`/`checked` 直接读取；kebab-case 事件（如 `open-change`）的 `$event.detail` 保持 `CustomEvent` 载荷类型。
+命名 handler 用 `WebUiEvent<WebUiXxx, 'change'>` 标注。未声明为 emit 的原生事件（`@click`/`@focus` 等）
+在任何 `web-ui-*` 元素上仍可绑定。
+
+### 属性与事件边界
+
+`web-ui-*` 元素是公开 DOM 边界。`id`、`class`、`style`、全局 HTML 属性和 `data-*` 保留在 Custom Element 宿主上，
+不会复制到 Shadow DOM。只有组件文档明确声明语义映射时，原生元素属性才会传递。例如 `web-ui-button` 会把 `type`
+映射到内部按钮，且仅接受 `button`、`submit`、`reset`；非法值会回退为 `button`。
+
+ARIA 属性同样必须显式支持：使用组件文档化的命名属性，而不是通配 `aria-*` 透传。组件拥有自己的 role 和交互状态。
+`click`、`input`、`change` 等浏览器 composed 原生事件仍是主要交互 API。`open-change` 等 kebab-case 自定义事件
+仅描述用户操作导致的组件状态变化；程序化赋值 property 不会触发它们。
+
 ## 所有组件
 
 | 分类            | 组件                                                      |
@@ -131,6 +150,7 @@ import '@greypan/web-ui/types/vue'
 |                 | [`<web-ui-textarea>`](#web-ui-textarea)                   |
 |                 | [`<web-ui-input-number>`](#web-ui-input-number)           |
 |                 | [`<web-ui-select>`](#web-ui-select)                       |
+|                 | [`<web-ui-autocomplete>`](#web-ui-autocomplete)           |
 |                 | [`<web-ui-slider>`](#web-ui-slider)                       |
 |                 | [`<web-ui-checkbox>`](#web-ui-checkbox)                   |
 |                 | [`<web-ui-radio>`](#web-ui-radio)                         |
@@ -179,10 +199,12 @@ import '@greypan/web-ui/types/vue'
 | `placeholder` | `string`  | `''`     | 占位文本        |
 | `name`        | `string`  | `''`     | 表单字段名      |
 | `disabled`    | `boolean` | `false`  | 禁用状态        |
+| `readonly`    | `boolean` | `false`  | 只读状态        |
 | `required`    | `boolean` | `false`  | 必填校验        |
 | `clearable`   | `boolean` | `false`  | 显示清除按钮    |
 | `full`        | `boolean` | `false`  | 全宽            |
 | `borderless`  | `boolean` | `false`  | 无边框          |
+| `aria-label`  | `string`  | —        | 无障碍标签      |
 
 **事件：** `input`, `change`, `focus`, `blur`
 
@@ -192,23 +214,24 @@ import '@greypan/web-ui/types/vue'
 
 多行文本输入框，支持自动调整高度。
 
-| 属性              | 类型      | 默认值  | 说明           |
-| ----------------- | --------- | ------- | -------------- |
-| `value`           | `string`  | `''`    | 输入值         |
-| `placeholder`     | `string`  | `''`    | 占位文本       |
-| `rows`            | `number`  | `3`     | 显示行数       |
-| `name`            | `string`  | `''`    | 表单字段名     |
-| `disabled`        | `boolean` | `false` | 禁用状态       |
-| `readonly`        | `boolean` | `false` | 只读状态       |
-| `required`        | `boolean` | `false` | 必填校验       |
-| `clearable`       | `boolean` | `false` | 显示清除按钮   |
-| `full`            | `boolean` | `false` | 全宽           |
-| `borderless`      | `boolean` | `false` | 无边框         |
-| `autosize`        | `boolean` | `false` | 自动调整高度   |
-| `minlength`       | `number`  | —       | 最小长度校验   |
-| `maxlength`       | `number`  | —       | 最大长度校验   |
-| `aria-label`      | `string`  | —       | 无障碍标签     |
-| `aria-labelledby` | `string`  | —       | 无障碍标签引用 |
+| 属性              | 类型      | 默认值  | 说明                               |
+| ----------------- | --------- | ------- | ---------------------------------- |
+| `value`           | `string`  | `''`    | 输入值                             |
+| `placeholder`     | `string`  | `''`    | 占位文本                           |
+| `rows`            | `number`  | `3`     | 显示行数                           |
+| `name`            | `string`  | `''`    | 表单字段名                         |
+| `disabled`        | `boolean` | `false` | 禁用状态                           |
+| `readonly`        | `boolean` | `false` | 只读状态                           |
+| `required`        | `boolean` | `false` | 必填校验                           |
+| `clearable`       | `boolean` | `false` | 显示清除按钮                       |
+| `full`            | `boolean` | `false` | 全宽                               |
+| `borderless`      | `boolean` | `false` | 无边框                             |
+| `autosize`        | `boolean` | `false` | 自动调整高度                       |
+| `max-height`      | `number`  | `0`     | 自动高度上限（px），`0` 表示不限制 |
+| `minlength`       | `number`  | —       | 最小长度校验                       |
+| `maxlength`       | `number`  | —       | 最大长度校验                       |
+| `aria-label`      | `string`  | —       | 无障碍标签                         |
+| `aria-labelledby` | `string`  | —       | 无障碍标签引用                     |
 
 **事件：** `input`, `change`, `focus`, `blur`
 
@@ -230,11 +253,12 @@ import '@greypan/web-ui/types/vue'
 | `placeholder` | `string`  | `''`       | 占位文本   |
 | `name`        | `string`  | `''`       | 表单字段名 |
 | `disabled`    | `boolean` | `false`    | 禁用状态   |
+| `readonly`    | `boolean` | `false`    | 只读状态   |
 | `required`    | `boolean` | `false`    | 必填校验   |
 
 **事件：** `input`, `change`
 
-ArrowUp/ArrowDown 键增减数值。
+ArrowUp/ArrowDown 键增减数值。空输入或 `-` 在提交时被忽略，值保持在最后一个有效数字。
 
 #### `<web-ui-select>`
 
@@ -257,6 +281,32 @@ ArrowUp/ArrowDown 键增减数值。
 
 子 `<web-ui-option>` 通过 `option-register` / `option-unregister` 注册。支持 ArrowDown/ArrowUp/Enter/Escape 键盘导航。
 
+#### `<web-ui-autocomplete>`
+
+可输入并过滤候选的单值选择器。
+
+| 属性               | 类型                               | 默认值       | 说明                                                    |
+| ------------------ | ---------------------------------- | ------------ | ------------------------------------------------------- |
+| `value`            | `string`                           | `''`         | 当前输入文本（表单值）                                  |
+| `selected-value`   | `string`                           | `''`         | 输入文本精确匹配 label 的 option 的 value（派生，只读） |
+| `placeholder`      | `string`                           | `''`         | 占位文本                                                |
+| `filter`           | `'none' \| 'prefix' \| 'contains'` | `'contains'` | 候选过滤模式（按 option label 匹配）                    |
+| `name`             | `string`                           | `''`         | 表单字段名                                              |
+| `disabled`         | `boolean`                          | `false`      | 禁用状态                                                |
+| `readonly`         | `boolean`                          | `false`      | 只读状态（不可输入、不可展开下拉）                      |
+| `required`         | `boolean`                          | `false`      | 必填校验                                                |
+| `portal`           | `boolean`                          | `false`      | 在主题浮层容器中渲染                                    |
+| `no-scroll-lock`   | `boolean`                          | `false`      | 打开时不锁定页面滚动                                    |
+| `overlayContainer` | `HTMLElement \| () => HTMLElement` | —            | 显式 Portal 容器                                        |
+| `aria-label`       | `string`                           | —            | 无障碍名称                                              |
+| `aria-labelledby`  | `string`                           | —            | 无障碍名称引用                                          |
+
+**事件：** `input`, `change`, `focus`, `blur`, `open-change` (`CustomEvent<{ open: boolean }>`)
+
+**插槽：** `default`（投影 `<web-ui-option>` 元素）
+
+键入时按 label 过滤候选（`contains` 或 `prefix`，`none` 关闭过滤）。选择 option 时文本回填为该项 label，`selected-value` 暴露该项的 value；`change` 在选择提交时触发。支持 ArrowDown/ArrowUp/Enter/Escape 键盘导航。
+
 #### `<web-ui-slider>`
 
 范围滑块，支持刻度标记和垂直方向。
@@ -391,19 +441,23 @@ ArrowUp/ArrowDown 键增减数值。
 
 样式化按钮，支持多种变体和加载状态。
 
-| 属性       | 类型                                                         | 默认值    | 说明                           |
-| ---------- | ------------------------------------------------------------ | --------- | ------------------------------ |
-| `variant`  | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'glass'` | `'glass'` | 按钮变体                       |
-| `disabled` | `boolean`                                                    | `false`   | 禁用状态                       |
-| `loading`  | `boolean`                                                    | `false`   | 加载旋转动画                   |
-| `full`     | `boolean`                                                    | `false`   | 全宽                           |
-| `icon`     | `boolean`                                                    | `false`   | 纯图标模式                     |
-| `size`     | `string`                                                     | `''`      | 尺寸格式 `高度` 或 `高度x宽度` |
+| 属性         | 类型                                                         | 默认值     | 说明                                |
+| ------------ | ------------------------------------------------------------ | ---------- | ----------------------------------- |
+| `variant`    | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'glass'` | `'glass'`  | 按钮变体                            |
+| `type`       | `'button' \| 'submit' \| 'reset'`                            | `'button'` | 内部按钮类型；非法值回退为 `button` |
+| `disabled`   | `boolean`                                                    | `false`    | 禁用状态                            |
+| `loading`    | `boolean`                                                    | `false`    | 加载旋转动画                        |
+| `full`       | `boolean`                                                    | `false`    | 全宽                                |
+| `icon`       | `boolean`                                                    | `false`    | 纯图标模式                          |
+| `size`       | `string`                                                     | `''`       | 尺寸格式 `高度` 或 `高度x宽度`      |
+| `aria-label` | `string`                                                     | —          | 无障碍标签（委托给内部按钮）        |
 
 **事件：** 标准 `click`
 
 **插槽：** `prefix`, `default`, `suffix`
 
+`submit` 和 `reset` 不会提交或重置组件 Shadow DOM 外祖先 `<form>`。如需外部表单行为，请使用 form-associated 控件。
+
 禁用和加载状态阻止 `click` 事件。
 
 #### `<web-ui-button-group>`
@@ -598,16 +652,16 @@ Hover 模式使用 `pointerenter`/`pointerleave` 加延迟控制。Click 模式
 
 徽标 / 通知计数。
 
-| 属性        | 类型                                                           | 默认值        | 说明                   |
-| ----------- | -------------------------------------------------------------- | ------------- | ---------------------- |
-| `count`     | `number`                                                       | `0`           | 显示数字               |
-| `max`       | `number`                                                       | `99`          | 最大值（超过显示 99+） |
-| `dot`       | `boolean`                                                      | `false`       | 点模式（不显示数字）   |
-| `show-zero` | `boolean`                                                      | `false`       | count 为 0 时也显示    |
-| `hidden`    | `boolean`                                                      | `false`       | 完全隐藏               |
-| `offset-x`  | `number`                                                       | `0`           | 水平偏移               |
-| `offset-y`  | `number`                                                       | `0`           | 垂直偏移               |
-| `placement` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'top-right'` | 徽标位置               |
+| 属性           | 类型                                                           | 默认值        | 说明                   |
+| -------------- | -------------------------------------------------------------- | ------------- | ---------------------- |
+| `count`        | `number`                                                       | `0`           | 显示数字               |
+| `max`          | `number`                                                       | `99`          | 最大值（超过显示 99+） |
+| `dot`          | `boolean`                                                      | `false`       | 点模式（不显示数字）   |
+| `show-zero`    | `boolean`                                                      | `false`       | count 为 0 时也显示    |
+| `badge-hidden` | `boolean`                                                      | `false`       | 完全隐藏               |
+| `offset-x`     | `number`                                                       | `0`           | 水平偏移               |
+| `offset-y`     | `number`                                                       | `0`           | 垂直偏移               |
+| `placement`    | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'top-right'` | 徽标位置               |
 
 #### `<web-ui-empty>`
 

package/README.md

@@ -33,7 +33,7 @@ import '@greypan/web-ui'
 
 ### React
 
-Requires `@types/react >= 16` as optional peer dependency.
+Requires `@types/react >= 19` as optional peer dependency.
 
 ```ts
 // vite.config.ts
@@ -56,7 +56,7 @@ function App() {
       <web-ui-button variant="primary" onClick={() => alert('clicked')}>
         Click
       </web-ui-button>
-      <web-ui-input onInput={e => console.log((e.target as any).value)} />
+      <web-ui-input onInput={e => console.log(e.currentTarget.value)} />
     </>
   )
 }
@@ -65,9 +65,12 @@ function App() {
 #### React custom-element events and boolean properties
 
 React 19 registers Custom Element events using the suffix of the JSX `on` key unchanged. Event names are
-case-sensitive: bind `open-change` as `onopen-change`, not `onOpenChange`. Standard `input` and `change`
-events continue to use React's conventional `onInput` and `onChange`. Boolean properties follow native HTML
-semantics: absence is `false` and presence is `true`.
+case-sensitive: bind `open-change` as `onopen-change`, not `onOpenChange`. Standard `input`, `change`, `focus`,
+and `blur` events use React's conventional `onInput`, `onChange`, `onFocus`, and `onBlur` handlers — their
+`currentTarget` is typed as the component instance, so `value` and `checked` are read cast-free. The `target`
+follows React SyntheticEvent semantics (`EventTarget`) and is not narrowed. Kebab-case custom events carry their
+`CustomEvent` detail typed. Boolean properties follow native HTML semantics: absence is `false` and presence is
+`true`.
 
 ```tsx
 <web-ui-dialog
@@ -98,7 +101,7 @@ useEffect(() => {
 
 ### Vue
 
-Requires `vue >= 3` as optional peer dependency.
+Requires `vue >= 3.5` as optional peer dependency.
 
 ```ts
 // vite.config.ts
@@ -122,9 +125,28 @@ import '@greypan/web-ui/types/vue'
 <template>
   <web-ui-button variant="primary" @click="handleClick">Click</web-ui-button>
   <web-ui-input v-model="value" />
+  <web-ui-select :value="framework" @change="framework = $event.target.value" />
 </template>
 ```
 
+Vue events are typed cast-free: `@input`/`@change` on value-bearing components resolve to the component emit, so
+`$event.target` is the component instance and `value`/`checked` are read directly. `$event.detail` keeps the
+`CustomEvent` payload type for kebab-case events like `open-change`. Named handlers annotate with
+`WebUiEvent<WebUiXxx, 'change'>`. `@click`/`@focus` and other native events not declared as emits remain
+bindable on any `web-ui-*` element.
+
+### Attribute and event boundaries
+
+`web-ui-*` elements are the public DOM boundary. `id`, `class`, `style`, global HTML attributes, and `data-*` stay on
+the custom-element host; they are not copied into its Shadow DOM. Components expose native-element attributes only when
+they document an explicit semantic mapping. For example, `web-ui-button` maps `type` to its inner button and accepts
+only `button`, `submit`, or `reset` (invalid values become `button`).
+
+ARIA attributes are explicit: use the component's documented naming attributes, not a blanket `aria-*` pass-through.
+Components own their role and interaction state. Browser-native composed events such as `click`, `input`, and `change`
+remain the primary interaction API. Kebab-case custom events such as `open-change` describe user-originated component
+state changes; assigning a property programmatically does not emit them.
+
 ## All Components
 
 | Category             | Component                                                 |
@@ -133,6 +155,7 @@ import '@greypan/web-ui/types/vue'
 |                      | [`<web-ui-textarea>`](#web-ui-textarea)                   |
 |                      | [`<web-ui-input-number>`](#web-ui-input-number)           |
 |                      | [`<web-ui-select>`](#web-ui-select)                       |
+|                      | [`<web-ui-autocomplete>`](#web-ui-autocomplete)           |
 |                      | [`<web-ui-slider>`](#web-ui-slider)                       |
 |                      | [`<web-ui-checkbox>`](#web-ui-checkbox)                   |
 |                      | [`<web-ui-radio>`](#web-ui-radio)                         |
@@ -181,10 +204,12 @@ Text input with clearable, prefix/suffix slots.
 | `placeholder` | `string`  | `''`     | Placeholder text    |
 | `name`        | `string`  | `''`     | Form field name     |
 | `disabled`    | `boolean` | `false`  | Disabled state      |
+| `readonly`    | `boolean` | `false`  | Read-only state     |
 | `required`    | `boolean` | `false`  | Required validation |
 | `clearable`   | `boolean` | `false`  | Show clear button   |
 | `full`        | `boolean` | `false`  | Full width          |
 | `borderless`  | `boolean` | `false`  | No border           |
+| `aria-label`  | `string`  | —        | Accessible label    |
 
 **Events:** `input`, `change`, `focus`, `blur`
 
@@ -194,23 +219,24 @@ Text input with clearable, prefix/suffix slots.
 
 Multi-line text input with auto-resize.
 
-| Attribute         | Type      | Default | Description                |
-| ----------------- | --------- | ------- | -------------------------- |
-| `value`           | `string`  | `''`    | Textarea value             |
-| `placeholder`     | `string`  | `''`    | Placeholder text           |
-| `rows`            | `number`  | `3`     | Visible rows               |
-| `name`            | `string`  | `''`    | Form field name            |
-| `disabled`        | `boolean` | `false` | Disabled state             |
-| `readonly`        | `boolean` | `false` | Read-only state            |
-| `required`        | `boolean` | `false` | Required validation        |
-| `clearable`       | `boolean` | `false` | Show clear button          |
-| `full`            | `boolean` | `false` | Full width                 |
-| `borderless`      | `boolean` | `false` | No border                  |
-| `autosize`        | `boolean` | `false` | Auto-resize height         |
-| `minlength`       | `number`  | —       | Minimum length validation  |
-| `maxlength`       | `number`  | —       | Maximum length validation  |
-| `aria-label`      | `string`  | —       | Accessible label           |
-| `aria-labelledby` | `string`  | —       | Accessible label reference |
+| Attribute         | Type      | Default | Description                               |
+| ----------------- | --------- | ------- | ----------------------------------------- |
+| `value`           | `string`  | `''`    | Textarea value                            |
+| `placeholder`     | `string`  | `''`    | Placeholder text                          |
+| `rows`            | `number`  | `3`     | Visible rows                              |
+| `name`            | `string`  | `''`    | Form field name                           |
+| `disabled`        | `boolean` | `false` | Disabled state                            |
+| `readonly`        | `boolean` | `false` | Read-only state                           |
+| `required`        | `boolean` | `false` | Required validation                       |
+| `clearable`       | `boolean` | `false` | Show clear button                         |
+| `full`            | `boolean` | `false` | Full width                                |
+| `borderless`      | `boolean` | `false` | No border                                 |
+| `autosize`        | `boolean` | `false` | Auto-resize height                        |
+| `max-height`      | `number`  | `0`     | Autosize max height (px); `0` = unlimited |
+| `minlength`       | `number`  | —       | Minimum length validation                 |
+| `maxlength`       | `number`  | —       | Maximum length validation                 |
+| `aria-label`      | `string`  | —       | Accessible label                          |
+| `aria-labelledby` | `string`  | —       | Accessible label reference                |
 
 **Events:** `input`, `change`, `focus`, `blur`
 
@@ -232,11 +258,12 @@ Numeric input with step buttons and keyboard control.
 | `placeholder` | `string`  | `''`       | Placeholder text    |
 | `name`        | `string`  | `''`       | Form field name     |
 | `disabled`    | `boolean` | `false`    | Disabled state      |
+| `readonly`    | `boolean` | `false`    | Read-only state     |
 | `required`    | `boolean` | `false`    | Required validation |
 
 **Events:** `input`, `change`
 
-ArrowUp/ArrowDown keyboard increments and decrements the value.
+ArrowUp/ArrowDown keyboard increments and decrements the value. Empty or `-` input is ignored on commit; the value stays at the last valid number.
 
 #### `<web-ui-select>`
 
@@ -261,6 +288,32 @@ Select dropdown with option items, keyboard navigation, and portal support.
 
 Child `<web-ui-option>` elements register via `option-register` / `option-unregister` events. Supports ArrowDown/ArrowUp/Enter/Escape keyboard navigation.
 
+#### `<web-ui-autocomplete>`
+
+Editable combobox with input filtering and single option selection.
+
+| Attribute          | Type                               | Default      | Description                                                               |
+| ------------------ | ---------------------------------- | ------------ | ------------------------------------------------------------------------- |
+| `value`            | `string`                           | `''`         | Current input text (form value)                                           |
+| `selected-value`   | `string`                           | `''`         | Value of the option exactly matching the input label (derived, read-only) |
+| `placeholder`      | `string`                           | `''`         | Placeholder text                                                          |
+| `filter`           | `'none' \| 'prefix' \| 'contains'` | `'contains'` | Candidate filtering mode (matched against option label)                   |
+| `name`             | `string`                           | `''`         | Form field name                                                           |
+| `disabled`         | `boolean`                          | `false`      | Disabled state                                                            |
+| `readonly`         | `boolean`                          | `false`      | Read-only state (no typing, no dropdown)                                  |
+| `required`         | `boolean`                          | `false`      | Required validation                                                       |
+| `portal`           | `boolean`                          | `false`      | Render dropdown in theme overlay                                          |
+| `no-scroll-lock`   | `boolean`                          | `false`      | Do not lock body scroll when open                                         |
+| `overlayContainer` | `HTMLElement \| () => HTMLElement` | —            | Explicit portal container                                                 |
+| `aria-label`       | `string`                           | —            | Accessible name                                                           |
+| `aria-labelledby`  | `string`                           | —            | Accessible name references                                                |
+
+**Events:** `input`, `change`, `focus`, `blur`, `open-change` (`CustomEvent<{ open: boolean }>`)
+
+**Slots:** `default` (project `<web-ui-option>` elements)
+
+Typing filters the option list by label (`contains` or `prefix`, or `none` to disable filtering). Selecting an option fills the input with its label and exposes the option's value via `selected-value`; `change` fires on selection commit. Supports ArrowDown/ArrowUp/Enter/Escape keyboard navigation.
+
 #### `<web-ui-slider>`
 
 Range slider with marks and vertical orientation.
@@ -397,19 +450,24 @@ Radio group managing single selection.
 
 Styled button with variants and loading state.
 
-| Attribute  | Type                                                         | Default   | Description                            |
-| ---------- | ------------------------------------------------------------ | --------- | -------------------------------------- |
-| `variant`  | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'glass'` | `'glass'` | Button variant                         |
-| `disabled` | `boolean`                                                    | `false`   | Disabled state                         |
-| `loading`  | `boolean`                                                    | `false`   | Loading spinner                        |
-| `full`     | `boolean`                                                    | `false`   | Full width                             |
-| `icon`     | `boolean`                                                    | `false`   | Icon-only mode                         |
-| `size`     | `string`                                                     | `''`      | Size format `height` or `heightxwidth` |
+| Attribute    | Type                                                         | Default    | Description                                       |
+| ------------ | ------------------------------------------------------------ | ---------- | ------------------------------------------------- |
+| `variant`    | `'primary' \| 'secondary' \| 'ghost' \| 'danger' \| 'glass'` | `'glass'`  | Button variant                                    |
+| `type`       | `'button' \| 'submit' \| 'reset'`                            | `'button'` | Inner-button type; invalid values become `button` |
+| `disabled`   | `boolean`                                                    | `false`    | Disabled state                                    |
+| `loading`    | `boolean`                                                    | `false`    | Loading spinner                                   |
+| `full`       | `boolean`                                                    | `false`    | Full width                                        |
+| `icon`       | `boolean`                                                    | `false`    | Icon-only mode                                    |
+| `size`       | `string`                                                     | `''`       | Size format `height` or `heightxwidth`            |
+| `aria-label` | `string`                                                     | —          | Accessible label (delegated to inner button)      |
 
 **Events:** standard `click`
 
 **Slots:** `prefix`, `default`, `suffix`
 
+`submit` and `reset` do not submit or reset an ancestor form outside the component's Shadow DOM. Use a
+form-associated control when external form submission behavior is required.
+
 Disabled and loading states prevent `click` events.
 
 #### `<web-ui-button-group>`
@@ -604,16 +662,16 @@ Avatar display with image fallback.
 
 Badge / notification count.
 
-| Attribute   | Type                                                           | Default       | Description               |
-| ----------- | -------------------------------------------------------------- | ------------- | ------------------------- |
-| `count`     | `number`                                                       | `0`           | Display count             |
-| `max`       | `number`                                                       | `99`          | Maximum count (shows 99+) |
-| `dot`       | `boolean`                                                      | `false`       | Dot mode (no count)       |
-| `show-zero` | `boolean`                                                      | `false`       | Show when count is 0      |
-| `hidden`    | `boolean`                                                      | `false`       | Hide completely           |
-| `offset-x`  | `number`                                                       | `0`           | Horizontal offset         |
-| `offset-y`  | `number`                                                       | `0`           | Vertical offset           |
-| `placement` | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'top-right'` | Badge position            |
+| Attribute      | Type                                                           | Default       | Description               |
+| -------------- | -------------------------------------------------------------- | ------------- | ------------------------- |
+| `count`        | `number`                                                       | `0`           | Display count             |
+| `max`          | `number`                                                       | `99`          | Maximum count (shows 99+) |
+| `dot`          | `boolean`                                                      | `false`       | Dot mode (no count)       |
+| `show-zero`    | `boolean`                                                      | `false`       | Show when count is 0      |
+| `badge-hidden` | `boolean`                                                      | `false`       | Hide completely           |
+| `offset-x`     | `number`                                                       | `0`           | Horizontal offset         |
+| `offset-y`     | `number`                                                       | `0`           | Vertical offset           |
+| `placement`    | `'top-right' \| 'top-left' \| 'bottom-right' \| 'bottom-left'` | `'top-right'` | Badge position            |
 
 #### `<web-ui-empty>`
 

package/dist/assets/glass.js.map

@@ -1 +1 @@
-{"version":3,"file":"glass.js","names":[],"sources":["../../src/assets/glass.css?inline"],"sourcesContent":["/*\n * 玻璃公共样式\n */\n\n.wui-glass {\n  position: relative;\n  border: 0.5px double var(--wui-color-glass-border, rgb(51 51 51 / 0.08));\n  backdrop-filter: blur(2px);\n  box-shadow:\n    inset -1px -1px 0.5px -0.5px var(--wui-color-glass-highlight, rgb(255 255 255 / 0.9)),\n    inset 1px 1px 0.5px -0.5px var(--wui-color-glass-highlight, rgb(255 255 255 / 0.9)),\n    inset -3px -3px 0.5px -3px\n      color-mix(in srgb, var(--wui-color-glass-highlight, rgb(255 255 255 / 0.9)) 60%, transparent),\n    inset 3px 3px 0.5px -3px\n      color-mix(in srgb, var(--wui-color-glass-highlight, rgb(255 255 255 / 0.9)) 60%, transparent),\n    inset 0 0 1px rgb(0 0 0 / 0.8),\n    var(--wui-glass-shadow, var(--wui-shadow-glass, 0 2px 16px rgb(0 0 0 / 0.06)));\n}\n"],"mappings":""}
+{"version":3,"file":"glass.js","names":[],"sources":["../../src/assets/glass.css?inline"],"sourcesContent":["/*\n * 玻璃公共样式\n */\n\n.wui-glass {\n  position: relative;\n\n  border: 0.5px double var(--wui-color-glass-border, rgb(51 51 51 / 0.08));\n\n  /* Safari 16.4 只支持带 -webkit- 前缀的 backdrop-filter（无前缀 18 才支持），\n     lightningcss 对 ?inline 导入不做自动前缀，需手动写前缀版本 */\n  /* stylelint-disable-next-line property-no-vendor-prefix */\n  -webkit-backdrop-filter: blur(2px);\n  backdrop-filter: blur(2px);\n  box-shadow:\n    inset -1px -1px 0.5px -0.5px var(--wui-color-glass-highlight, rgb(255 255 255 / 0.9)),\n    inset 1px 1px 0.5px -0.5px var(--wui-color-glass-highlight, rgb(255 255 255 / 0.9)),\n    inset -3px -3px 0.5px -3px\n      color-mix(in srgb, var(--wui-color-glass-highlight, rgb(255 255 255 / 0.9)) 60%, transparent),\n    inset 3px 3px 0.5px -3px\n      color-mix(in srgb, var(--wui-color-glass-highlight, rgb(255 255 255 / 0.9)) 60%, transparent),\n    inset 0 0 1px rgb(0 0 0 / 0.8),\n    var(--wui-glass-shadow, var(--wui-shadow-glass, 0 2px 16px rgb(0 0 0 / 0.06)));\n}\n"],"mappings":""}

package/dist/assets/menu-portal.js

@@ -1,5 +1,5 @@
 //#region src/assets/menu-portal.css?inline
-var e = ".wui-menu-portal-overlay{--wui-glass-shadow:var(--wui-shadow-pop,0 3px 9px #00000045);--wui-duration-overlay-enter:var(--wui-duration-menu-enter,.14s);--wui-duration-overlay-exit:var(--wui-duration-menu-exit,.1s);-webkit-user-select:none;user-select:none;z-index:var(--wui-layer-menu,100);box-sizing:border-box;min-width:200px;max-width:90vw;max-height:80vh;color:var(--wui-color-text,#1b1b1b);background-color:var(--wui-color-surface-overlay,#f6f6f6e0);border-radius:20px;position:fixed;overflow:hidden}.wui-menu-portal-overlay .wui-menu-scroll{max-height:80vh;overflow-y:auto}.wui-menu-portal-overlay .wui-menu-content{padding:4px}.wui-menu-portal-overlay.dropdown-overlay .wui-menu-scroll{max-height:320px}.wui-menu-portal-overlay.dropdown-overlay[data-level]:not([data-level=\"0\"]),.wui-menu-portal-overlay.context-submenu{z-index:var(--wui-layer-menu-submenu,110)}";
+var e = ".wui-menu-portal-overlay{--wui-glass-shadow:var(--wui-shadow-pop,0 3px 9px #00000045);--wui-duration-overlay-enter:var(--wui-duration-menu-enter,.14s);--wui-duration-overlay-exit:var(--wui-duration-menu-exit,.1s);--wui-overlay-min-width:200px;-webkit-user-select:none;user-select:none;z-index:var(--wui-layer-menu,100);box-sizing:border-box;min-width:var(--wui-overlay-min-width,120px);max-width:90vw;max-height:80vh;color:var(--wui-color-text,#1b1b1b);background-color:var(--wui-color-surface-overlay,#f6f6f6e0);border-radius:20px;position:fixed;overflow:hidden}.wui-menu-portal-overlay .wui-menu-scroll{max-height:80vh;overflow-y:auto}.wui-menu-portal-overlay .wui-menu-content{padding:4px}.wui-menu-portal-overlay.dropdown-overlay .wui-menu-scroll{max-height:320px}.wui-menu-portal-overlay.dropdown-overlay[data-level]:not([data-level=\"0\"]),.wui-menu-portal-overlay.context-submenu{z-index:var(--wui-layer-menu-submenu,110)}";
 //#endregion
 export { e as default };
 

package/dist/assets/menu-portal.js.map

@@ -1 +1 @@
-{"version":3,"file":"menu-portal.js","names":[],"sources":["../../src/assets/menu-portal.css?inline"],"sourcesContent":[".wui-menu-portal-overlay {\n  --wui-glass-shadow: var(--wui-shadow-pop, 0 3px 9px rgb(0 0 0 / 0.27));\n  --wui-duration-overlay-enter: var(--wui-duration-menu-enter, 140ms);\n  --wui-duration-overlay-exit: var(--wui-duration-menu-exit, 100ms);\n  user-select: none;\n\n  position: fixed;\n  z-index: var(--wui-layer-menu, 100);\n\n  overflow: hidden;\n\n  box-sizing: border-box;\n  min-width: 200px;\n  max-width: 90vw;\n  max-height: 80vh;\n  border-radius: 20px;\n\n  color: var(--wui-color-text, #1b1b1b);\n\n  background-color: var(--wui-color-surface-overlay, rgb(246 246 246 / 0.88));\n\n  & .wui-menu-scroll {\n    overflow-y: auto;\n    max-height: 80vh;\n  }\n\n  & .wui-menu-content {\n    padding: 4px;\n  }\n\n  &.dropdown-overlay {\n    & .wui-menu-scroll {\n      max-height: 320px;\n    }\n\n    &[data-level]:not([data-level='0']) {\n      z-index: var(--wui-layer-menu-submenu, 110);\n    }\n  }\n\n  &.context-submenu {\n    z-index: var(--wui-layer-menu-submenu, 110);\n  }\n}\n"],"mappings":""}
+{"version":3,"file":"menu-portal.js","names":[],"sources":["../../src/assets/menu-portal.css?inline"],"sourcesContent":[".wui-menu-portal-overlay {\n  --wui-glass-shadow: var(--wui-shadow-pop, 0 3px 9px rgb(0 0 0 / 0.27));\n  --wui-duration-overlay-enter: var(--wui-duration-menu-enter, 140ms);\n  --wui-duration-overlay-exit: var(--wui-duration-menu-exit, 100ms);\n  --wui-overlay-min-width: 200px;\n  user-select: none;\n\n  position: fixed;\n  z-index: var(--wui-layer-menu, 100);\n\n  overflow: hidden;\n\n  box-sizing: border-box;\n  min-width: var(--wui-overlay-min-width, 120px);\n  max-width: 90vw;\n  max-height: 80vh;\n  border-radius: 20px;\n\n  color: var(--wui-color-text, #1b1b1b);\n\n  background-color: var(--wui-color-surface-overlay, rgb(246 246 246 / 0.88));\n\n  & .wui-menu-scroll {\n    overflow-y: auto;\n    max-height: 80vh;\n  }\n\n  & .wui-menu-content {\n    padding: 4px;\n  }\n\n  &.dropdown-overlay {\n    & .wui-menu-scroll {\n      max-height: 320px;\n    }\n\n    &[data-level]:not([data-level='0']) {\n      z-index: var(--wui-layer-menu-submenu, 110);\n    }\n  }\n\n  &.context-submenu {\n    z-index: var(--wui-layer-menu-submenu, 110);\n  }\n}\n"],"mappings":""}

package/dist/components/autocomplete/index.d.ts

@@ -0,0 +1,121 @@
+import { LitElement, PropertyValues } from 'lit';
+import { OverlayContainer } from '../../shared/overlay/portal';
+declare const FILTER_MODES: readonly ["none", "prefix", "contains"];
+type FilterMode = (typeof FILTER_MODES)[number];
+/**
+ * `web-ui-autocomplete`：可输入并过滤候选的单值选择器。
+ *
+ * 与 `web-ui-select` 共用 `<web-ui-option>` 子项注册协议与浮层能力，但触发区是
+ * 可编辑输入框：`value` 即当前输入文本（表单值），键入时按 `filter` 模式过滤候选，
+ * 选择 option 时文本回填为该项 label，`selected-value` 暴露该项的 value。
+ */
+export declare class WebUiAutocomplete extends LitElement {
+    static styles: import('lit').CSSResult[];
+    static formAssociated: boolean;
+    private _internals?;
+    private _formDisabled;
+    placeholder: string;
+    disabled: boolean;
+    readonly: boolean;
+    required: boolean;
+    portal: boolean;
+    noScrollLock: boolean;
+    overlayContainer?: OverlayContainer;
+    name: string;
+    ariaLabel: string | null;
+    ariaLabelledby: string | undefined;
+    private _filter;
+    get filter(): FilterMode;
+    set filter(v: string);
+    private _value;
+    get value(): string;
+    set value(v: string);
+    private _selectedValue;
+    get selectedValue(): string;
+    private _setSelectedValue;
+    private get _isDisabled();
+    private _isOpen;
+    private _activeIndex;
+    private _focused;
+    private static _nextInstanceId;
+    private readonly _idPrefix;
+    private readonly _optionIds;
+    private readonly _a11yOptionIds;
+    private _nextOptionId;
+    private _nextA11yOptionId;
+    private _options;
+    private _portal?;
+    private _portalContent?;
+    private readonly _pendingUnregisteredOptions;
+    private readonly _scrollLock;
+    private readonly _panel;
+    get isOpen(): boolean;
+    get open(): boolean;
+    private _onClickOutside;
+    private _onFocusOut;
+    private _handlePanelPointerDown;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    disconnectedCallback(): void;
+    firstUpdated(): void;
+    private _queryOptions;
+    willUpdate(): void;
+    updated(changed: PropertyValues): void;
+    formResetCallback(): void;
+    formDisabledCallback(disabled: boolean): void;
+    formStateRestoreCallback(state: string | File | FormData | null): void;
+    private _syncValidity;
+    private _syncOpenAttribute;
+    private _syncSelectedValue;
+    private _syncOptionA11y;
+    private _ensureOptionIds;
+    private _getA11yOptionId;
+    private _applyFilter;
+    private _syncEmptyState;
+    private _bindOption;
+    private _unbindOption;
+    private _refreshOptions;
+    private _syncPortalContent;
+    private _scheduleOptionsRefresh;
+    private _onOptionRegister;
+    private _onOptionUnregister;
+    private _onSlotChange;
+    private _handleOptionClick;
+    private _onOptionUpdate;
+    private _handleOptionPointerOver;
+    private _handleOptionPointerDown;
+    private _onKeydown;
+    private _navigateActive;
+    private _setInitialActiveOption;
+    private _syncActiveOption;
+    private _selectOption;
+    private _onInput;
+    private _onInnerChange;
+    private _onFocus;
+    private _onBlur;
+    private _open;
+    private _close;
+    private _dispatchOpenChange;
+    private _openOverlay;
+    private _closeOverlay;
+    private _reconfigureOverlay;
+    private _syncScrollLock;
+    private _createPortal;
+    private _getLabelledbyText;
+    render(): import('lit').TemplateResult<1>;
+    readonly $events: {
+        input: Event;
+        change: Event;
+        focus: FocusEvent;
+        blur: FocusEvent;
+        'open-change': CustomEvent<{
+            open: boolean;
+        }>;
+    };
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'web-ui-autocomplete': WebUiAutocomplete;
+    }
+}
+export {};