@greypan/web-ui 2.1.8 → 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,15 @@ 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 宿主上，
@@ -141,6 +150,7 @@ ARIA 属性同样必须显式支持：使用组件文档化的命名属性，而
 |                 | [`<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)                         |
@@ -189,6 +199,7 @@ ARIA 属性同样必须显式支持：使用组件文档化的命名属性，而
 | `placeholder` | `string`  | `''`     | 占位文本        |
 | `name`        | `string`  | `''`     | 表单字段名      |
 | `disabled`    | `boolean` | `false`  | 禁用状态        |
+| `readonly`    | `boolean` | `false`  | 只读状态        |
 | `required`    | `boolean` | `false`  | 必填校验        |
 | `clearable`   | `boolean` | `false`  | 显示清除按钮    |
 | `full`        | `boolean` | `false`  | 全宽            |
@@ -242,11 +253,12 @@ ARIA 属性同样必须显式支持：使用组件文档化的命名属性，而
 | `placeholder` | `string`  | `''`       | 占位文本   |
 | `name`        | `string`  | `''`       | 表单字段名 |
 | `disabled`    | `boolean` | `false`    | 禁用状态   |
+| `readonly`    | `boolean` | `false`    | 只读状态   |
 | `required`    | `boolean` | `false`    | 必填校验   |
 
 **事件：** `input`, `change`
 
-ArrowUp/ArrowDown 键增减数值。
+ArrowUp/ArrowDown 键增减数值。空输入或 `-` 在提交时被忽略，值保持在最后一个有效数字。
 
 #### `<web-ui-select>`
 
@@ -269,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>`
 
 范围滑块，支持刻度标记和垂直方向。

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,16 @@ 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
@@ -145,6 +155,7 @@ state changes; assigning a property programmatically does not emit them.
 |                      | [`<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)                         |
@@ -193,6 +204,7 @@ 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          |
@@ -246,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>`
 
@@ -275,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.

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 {};