@haiyue/ui 0.1.2 → 0.2.1

package/CHANGELOG.md

@@ -1,6 +1,33 @@
 # Changelog
 
-## Unreleased
+## 0.2.1 - 2026-10-20
+
+- 新增可按需导入的 `HYTag` / `<hy-tag>` 标签组件，支持语义与自定义配色、三种尺寸、文字或 icon 插槽、可取消的关闭事件、可选择状态、键盘操作和禁用状态；新增 `HYToast` / `<hy-toast>` 轻提示组件，支持五种状态、上/中/下位置、自动或持久显示、最大数量、手动关闭/清空、生命周期事件与完整计时器清理。
+- M24 G05 新增独立 `adapters/web` 子路径：18 种共享语义映射、显式注册、受控输入/选择/弹窗、主题/安全区、预览资源生命周期与基础组件示例。新增可选 `controlled` 属性（Tabs/Range/Dialog）和 Input `password` 类型；旧默认 API 保留。修复关闭后立即重开的过期回调，以及共享页面把隐藏标签页误判为可聚焦的问题。Chromium/WebKit 自动化已通过，物理输入与读屏验收范围单独记录。
+- M24 G03 新增独立 `core` / `portable` 子路径：18 种组件语义、交互 controller、受限页面组合、selector 订阅、稳定节点差异、事务、生命周期与主题数据；无 DOM/NativeScript/Engine 依赖。仅完成核心及记录型后端验证，真实平台适配分别由 G05/G06/G08 交付，旧 Web API 保持不变。
+- 扩展 `HYVirtualKeyboard` / `<hy-virtual-keyboard>`：默认 QWERTY 布局补齐上、下方向键及多行文本纵向光标移动；新增 `qwerty` / `numeric` 模式切换和可复用的 `HY_VIRTUAL_KEYBOARD_NUMERIC_LAYOUT` 内置数字键盘。
+- 扩展 `HYButton` / `<hy-button>`：支持 `icon` 属性或 `icon` 插槽、`icon-position` 前后位置、会阻止重复点击并带无障碍忙碌状态的 `loading` 旋转图标；新增可按需导入的 `HYButtonGroup` / `<hy-button-group>`，支持横向和纵向组合按钮。
+- 示例页外壳改为使用 Haiyue UI 自身搭建：主题按钮、组件搜索、命令面板、状态徽标和演示操作均复用公开 Web Components；导航/内容和演示/参数区域使用 `HYSplit` 调节尺寸，用法代码通过只读 CodeMirror 提供 HTML、JavaScript 与 CSS 语法高亮，并为 `HYButton` 暴露 `button` part 与 pressed 状态转发。
+- 新增可按需导入的 `HYResizable` / `<hy-resizable>` 调整框组件，支持四个角点与四条边缩放、内容拖动、位置尺寸 API、父容器/视口/元素边界、网格吸附、宽高比、尺寸限制、键盘控制和生命周期事件。
+- 扩展 `HYInput` / `<hy-input>`：新增 prefix/suffix 属性与同名插槽、`search` 输入类型、可访问的搜索按钮、回车/API 搜索和组合 `search` 事件。
+- 新增可按需导入的 `HYDraggable` / `<hy-draggable>` 拖拽容器，支持手柄与排除选择器、双轴/单轴移动、父容器/视口/元素边界、网格吸附、键盘控制、位置 API、生命周期事件与主题样式钩子。
+- 新增可按需导入的 `HYVirtualKeyboard` / `<hy-virtual-keyboard>` 虚拟键盘，提供默认 QWERTY 与自定义布局、输入目标绑定、Shift/Caps、编辑和光标按键、物理键盘同步、按键播放 API、组合事件与主题样式钩子。
+- 新增可按需导入的 `HYCollapse` / `<hy-collapse>` 折叠面板组件，支持多项或手风琴展开、默认/当前展开项、禁用面板、图标位置、触发区域、边框/幽灵样式、隐藏内容销毁和无障碍键盘操作。
+- 新增可按需导入的 `HYBadge` / `<hy-badge>` 徽标组件，支持计数上限、零值显隐、圆点、小尺寸、语义状态、自定义颜色、偏移、标题和无障碍状态播报。
+- 新增可按需导入的 `HYAffix` / `<hy-affix>` 固钉组件，支持窗口或自定义滚动容器、顶部/底部偏移、布局占位、禁用、层级和吸附状态事件。
+- 新增可按需导入的 `HYTour` / `<hy-tour>` 漫游式引导组件，支持目标定位、四向或居中浮层、聚光遮罩、自动滚动、键盘/遮罩关闭、步骤控制和生命周期事件。
+- 新增可按需导入的 `HYSteps` / `<hy-steps>` 步骤条组件，支持横向/纵向、当前步骤、自动及显式状态、自定义图标、描述、副标题、紧凑尺寸、点击导航与禁用步骤。
+- 新增可按需导入的 `HYDivider` / `<hy-divider>` 分割线组件，支持横向/纵向、实线/虚线/点线/双线、粗细、颜色、间距，以及插槽或属性文字和三种文字位置。
+- 新增可按需导入的 `HYRate` / `<hy-rate>` 星级评分组件，支持通过 `allow-half` 属性选择半星，并提供星数、清空、自定义字符、提示、只读/禁用、键盘控制及组合事件。
+- 新增可按需导入的 `HYTimeline` / `<hy-timeline>` 时间轴组件，支持状态与自定义颜色/节点、左右和交替布局、倒序、Pending、响应式单列及内容渲染钩子。
+- 新增可按需导入的 `HYWatermark` / `<hy-watermark>` 水印组件，支持单行或多行文字、图片、旋转、间距、偏移、尺寸、字体、颜色、透明度与层级配置，并保持底层内容可交互。
+- 新增可按需导入的 `HYSkeleton` / `<hy-skeleton>` 骨架屏，支持内容自动切换、头像、标题、段落行数与宽度、尺寸、圆角、加载动画、无障碍状态及减少动态效果偏好。
+- 新增可按需导入的 `HYDatePicker` / `<hy-date-picker>` 日期选择器，支持 ISO 日期、范围限制、周起始日、Today、清空、月历键盘导航与组合事件。
+- 新增可按需导入的 `HYTimePicker` / `<hy-time-picker>` 时间选择器，支持时分秒、分秒步长、时间范围、Now、确认、清空、列键盘导航与组合事件。
+- 新增可按需导入的 `HYCascader` / `<hy-cascader>` 级联下拉，支持树形选项、受控路径、父级选择、禁用与清空、点击外部或 Esc 关闭、方向键导航及组合事件。
+- 新增可按需导入的 `HYBreadcrumb` / `<hy-breadcrumb>` 面包屑导航，兼容 `title` / `label` 项文本，支持链接、动作项、禁用项、当前页语义、自定义分隔符与内容渲染，以及可取消的 `breadcrumb-click` 事件。
+- 新增可按需导入的 `HYTable` / `<hy-table>` 数据表格，支持本地分页、标题旁漏斗过滤菜单、全局与列级过滤入口显隐、稳定排序、自定义单元格渲染，以及 `table-change` / `row-click` 组合事件。
+- 新增可按需导入的 `HYVirtualMouse` / `<hy-virtual-mouse>` 固定定位虚拟鼠标，支持状态图片与 CSS 定制、动画移动、按下/抬起、左中右键点击 API，以及组合事件和生命周期清理。
 
 ## 0.1.2 - 2026-09-03
 

package/README.md

@@ -23,10 +23,12 @@ helpers, and registration stays explicit:
 
 ```ts
 import { defineButtonComponents } from '@haiyue/ui/button';
+import { defineButtonGroupComponents } from '@haiyue/ui/button-group';
 import { defineTreeComponents } from '@haiyue/ui/tree';
 import { defineVirtualListComponents } from '@haiyue/ui/virtual-list';
 
 defineButtonComponents();
+defineButtonGroupComponents();
 defineTreeComponents();
 defineVirtualListComponents();
 ```
@@ -46,6 +48,113 @@ defineHaiyueUI();
 Because `defineHaiyueUI()` references the complete component set, prefer focused subpaths in bundle-sensitive
 product entry points.
 
+## Tag and toast
+
+Tags provide compact semantic labels with optional checked and close interactions. Toasts are an imperative,
+lightweight feedback surface for short-lived messages; use Notification when a message also needs a description
+or richer stacked content.
+
+```ts
+import { defineTagComponents } from '@haiyue/ui/tag';
+import { defineToastComponents } from '@haiyue/ui/toast';
+
+defineTagComponents();
+defineToastComponents();
+```
+
+```html
+<hy-tag variant="success" icon="✓" closable>Synced</hy-tag>
+<hy-tag variant="primary" checkable value="featured">Featured</hy-tag>
+<hy-toast id="feedback" placement="top" duration="3" closable></hy-toast>
+<script type="module">
+  feedback.success('Saved successfully');
+  const key = feedback.loading('Exporting…');
+  // Reusing a key replaces the persistent loading toast.
+  feedback.success({ key, message: 'Export complete' });
+</script>
+```
+
+## Button icons, loading, and groups
+
+Buttons accept a text `icon` or a richer `icon` slot. Set `icon-position="end"` to place it after the label.
+The boolean `loading` attribute replaces the configured icon with a spinner, marks the native button busy, and
+temporarily disables activation so an asynchronous request cannot be submitted twice.
+
+```html
+<hy-button label="Publish" icon="↥"></hy-button>
+<hy-button label="Continue" icon="→" icon-position="end"></hy-button>
+<hy-button loading label="Syncing"></hy-button>
+<hy-button label="Upload"><svg slot="icon" aria-hidden="true">…</svg></hy-button>
+
+<hy-button-group aria-label="History actions">
+  <hy-button label="Undo" icon="↶"></hy-button>
+  <hy-button label="Redo" icon="↷"></hy-button>
+</hy-button-group>
+```
+
+Use `orientation="vertical"` for a stacked group. Button styling is exposed through the `button`, `content`,
+`icon`, and `spinner` parts; the group exposes its container as the `group` part.
+
+## Input and search
+
+`HYInput` supports plain-text `prefix` and `suffix` attributes as well as named slots for icons or richer
+content. Use `type="search"` to add an accessible search action button:
+
+```html
+<hy-input type="search" prefix="⌕" suffix="assets"
+  placeholder="Search…" search-label="Search assets"></hy-input>
+
+<hy-input placeholder="Amount">
+  <span slot="prefix">¥</span>
+  <span slot="suffix">CNY</span>
+</hy-input>
+```
+
+Search inputs emit a composed, cancelable `search` event when the user presses Enter, activates the search
+button, or the application calls `search()`. Its detail contains `{ value, valid, source }`, where `source` is
+`enter`, `button`, or `api`. Existing `value-change`, validation, number, and color input behavior remains
+available. Style the `control`, `input`, `prefix`, `suffix`, and `search-button` parts or the
+`--hy-input-affix-*` and `--hy-input-search-*` tokens.
+
+## Portable component semantics (M24 G03/G05, unreleased)
+
+`@haiyue/ui/core` provides platform-independent component types, validation, selection/input/action
+controllers and the `PlatformView` lifetime contract. `@haiyue/ui/portable` provides `HYPage`, selector
+bindings, keyed updates, transactions, focus/modal policy and semantic theme conversion. Both entries
+can be imported without DOM, NativeScript or Engine. They do not register existing Web Components.
+
+```ts
+import { hyNode, hyKey, type HYRenderer } from '@haiyue/ui/core';
+import { HYPage } from '@haiyue/ui/portable';
+
+export function mountPage(renderer: HYRenderer) {
+  const page = new HYPage(renderer);
+  page.mount(hyNode('Column', 'settings', { layout: { gap: 8 } }, {
+    children: [hyNode('Text', 'title', { text: 'Settings' })],
+  }));
+  page.setProps(hyKey('settings', 'title'), 'Text', { text: 'Preview settings' });
+  return page; // The shell forwards suspend/resume and calls dispose on exit.
+}
+```
+
+Author keys are stable and unique within each parent, including its named slots. `hyKey()` builds
+scoped keys for bindings, events and focus. `setProps()` completely replaces a node's props; use
+`transaction()` for one synchronous batch. Group all selectors for a given store in one `bind(store,
+bindings)` call so an application transaction produces one renderer commit. Identical props produce
+no writes; reordering preserves instances. Applications persist values on `commit`, not `valueChange`.
+
+The Web backend is available from `@haiyue/ui/adapters/web`: explicitly call
+`definePortableWebComponents()`, construct `new HYWebRenderer(connectedElement, options)`, then pass it
+to `HYPage`. It reuses seven existing Web Components and maps the other semantic kinds to browser
+elements. It introduces no runtime package dependencies or automatic registration. See the
+[Web adapter guide](docs/web-adapter.md) and [interactive example](examples/portable-ui/index.html).
+Run `npm run test:web-adapter` for Chromium/WebKit regression coverage.
+
+These APIs are under development and have not been published. Mobile mapping is G06, desktop mapping
+G08, and ShaderLab shared-page migration G07. Existing Web component APIs below remain independent. See the
+[portable UI guide](docs/portable-ui.md) and [typed composition example](test/portable/fixtures/settings-page.ts).
+Run `npm run verify:portable` for semantics, no-DOM types, and an isolated offline tarball consumer.
+
 ## Tabs
 
 `@haiyue/ui/tabs` retains its existing `HYTabs`, `HYTabOption`, `HYTabChangeDetail`, and
@@ -82,6 +191,220 @@ Use the `height` property (or `height` attribute) for the internal viewport. `vi
 exclusive `endIndex` / `visibleEndIndex` values, and `item-click` reports the source item and absolute index.
 The scrollbar can be themed with inherited semantic tokens and `--hy-virtual-list-scrollbar-size`.
 
+## Breadcrumb
+
+Import and register breadcrumb navigation independently:
+
+```ts
+import { defineBreadcrumbComponents } from '@haiyue/ui/breadcrumb';
+
+defineBreadcrumbComponents();
+const breadcrumb = document.querySelector('hy-breadcrumb');
+breadcrumb.items = [
+  { key: 'projects', title: 'Projects', href: '/projects' },
+  { key: 'scene', title: 'Ocean World' },
+  { key: 'lighting', title: 'Lighting' },
+];
+breadcrumb.separator = '›';
+```
+
+Item text may use the Ant Design-compatible `title` field or its `label` alias. The final item is exposed as
+the current page with `aria-current="page"`. Earlier items render as links when
+they provide `href`, or as action buttons otherwise; disabled items remain readable but cannot be activated.
+Listen for the composed, cancelable `breadcrumb-click` event to handle actions or prevent link navigation.
+Use `renderItem` for custom item content, and `ariaLabel` when rendered content needs an explicit accessible
+name. Styling hooks include the `nav`, `list`, `item`, `link`, `button`, `current`, `disabled`, and `separator`
+shadow parts plus the `--hy-breadcrumb-*` CSS variables.
+
+## Cascader
+
+Use the focused `@haiyue/ui/cascader` entry for hierarchical selection:
+
+```ts
+import { defineCascaderComponents } from '@haiyue/ui/cascader';
+
+defineCascaderComponents();
+const cascader = document.querySelector('hy-cascader');
+cascader.options = [
+  { label: 'Project', value: 'project', children: [
+    { label: 'Scenes', value: 'scenes', children: [
+      { label: 'Moon Temple', value: 'temple' },
+    ] },
+  ] },
+];
+cascader.value = ['project', 'scenes', 'temple'];
+```
+
+Selecting a leaf commits the complete value path and emits `value-change` with both values and resolved option
+objects. Enable `changeOnSelect` (or `change-on-select`) when parent paths should also be committed. The component
+supports string and number values, disabled options, clearing, a custom `displaySeparator`, controlled `open`
+state, outside-pointer and Escape closing, and arrow/Home/End keyboard navigation. `open-change` reports panel
+visibility. Shadow parts expose `control`, `trigger`, `label`, `arrow`, `clear`, `panel`, `column`, `option`,
+`option-item`, and `empty` for product-specific styling.
+
+## Date and time pickers
+
+Date and time selection remain independently importable, so an application only ships the picker it uses:
+
+```ts
+import { defineDatePickerComponents } from '@haiyue/ui/date-picker';
+import { defineTimePickerComponents } from '@haiyue/ui/time-picker';
+
+defineDatePickerComponents();
+defineTimePickerComponents();
+```
+
+`<hy-date-picker>` emits ISO `YYYY-MM-DD` values and provides a locale-aware month calendar, `min` / `max`
+constraints, Monday or Sunday `weekStart`, Today, clearing, outside-pointer and Escape closing, and arrow,
+Home/End, and PageUp/PageDown keyboard navigation.
+
+`<hy-time-picker>` emits 24-hour `HH:mm` or `HH:mm:ss` values. Enable `showSeconds`, configure
+`minuteStep` / `secondStep`, and constrain selection with `min` / `max`. Its scrollable hour, minute, and second
+columns support keyboard traversal, Now, explicit confirmation, clearing, and controlled `open` state. Both
+components emit composed `value-change` and `open-change` events and expose their controls through shadow parts.
+
+## Skeleton
+
+Import the loading placeholder independently and place the real content in its default slot:
+
+```ts
+import { defineSkeletonComponents } from '@haiyue/ui/skeleton';
+
+defineSkeletonComponents();
+```
+
+`<hy-skeleton>` defaults to a title and three paragraph rows. Enable `active` for the shimmer animation, add
+`avatar`, choose `avatarShape`, `avatarSize`, `size`, and `round`, or tune `rows`, `titleWidth`, and the
+`paragraphWidths` property. Set `loading = false` to remove placeholder DOM and reveal the slotted content.
+The host exposes `aria-busy`, honors reduced-motion preferences, inherits both Haiyue themes, and provides
+`placeholder`, `content`, `avatar`, `body`, `title`, `paragraph`, and `row` shadow parts.
+
+## Steps
+
+Use `@haiyue/ui/steps` to show task, form, or publishing progress. Assign `items` with a required `title` and
+optional `description`, `subtitle`, `icon`, `status`, and `disabled` state. `current` is zero-based and derives
+`finish`, `process`, and `wait` states automatically unless an item provides an explicit status. Set
+`direction` to `horizontal` or `vertical`, use `size="small"` for compact layouts, and enable `clickable` when
+users may navigate between steps. Click navigation updates `current` and emits the composed `step-change` event.
+The ordered list exposes `aria-current="step"` and shadow parts for every structural and status element.
+
+## Badge
+
+Import `@haiyue/ui/badge` to decorate slotted content with a count or notification dot, or to render a standalone
+semantic status. Numeric counts are capped by `overflowCount` (99 by default); use `showZero`, `dot`, `size`,
+`color`, `title`, and the `[x, y]` `offset` property for display control. The `default`, `success`, `processing`,
+`warning`, and `error` statuses accept accompanying `text`, expose status semantics, and honor reduced-motion
+preferences. Structural styling hooks include `wrapper`, `badge`, `badge-content`, `status`, `status-dot`, and
+`status-text` shadow parts.
+
+## Collapse
+
+Import `@haiyue/ui/collapse` and assign typed `items` containing `key`, `title`, optional `content`, `extra`,
+`disabled`, and `showArrow` values. `activeKeys` supports multiple open panels, while `accordion` limits the
+group to one. Configure `iconPosition`, `collapsible`, `bordered`, `ghost`, and `destroyOnHidden`; call
+`toggle(key, expanded?)` for imperative control. Each header is a native keyboard-accessible button connected
+to a labelled region, and user changes emit the composed `collapse-change` event with the active keys and
+changed panel. The component exposes structural shadow parts from `collapse` and `panel` through `body`.
+
+## Affix
+
+Import `@haiyue/ui/affix` to pin actions, navigation, or status content after it crosses a viewport threshold.
+Use the `offset-top` or `offset-bottom` attributes, or the `topOffset` / `bottomOffset` properties, and assign an
+element to `target` when the scroll container is not the browser window. The component preserves the original
+layout with an internal placeholder, exposes the read-only `affixed` state, and emits the composed
+`affix-change` event. Call `refresh()` after layout changes that do not trigger resize observation.
+
+## Tour
+
+Import `@haiyue/ui/tour` for step-by-step product guidance. Assign `steps` with a title, optional description,
+target selector, element, or resolver function, and an optional `top`, `right`, `bottom`, `left`, or `center`
+placement. The component can render a spotlight mask, scroll targets into view, close from Escape or mask
+interaction, and is controlled through `open` and zero-based `current`. Use `start()`, `next()`, `previous()`,
+and `close()` from application code; observe `tour-change`, `tour-close`, `tour-finish`, and `tour-open-change`
+for lifecycle state. Focus returns to the launch control when the tour ends.
+
+## Divider
+
+Import `@haiyue/ui/divider` for semantic horizontal or vertical separators. Text can be supplied through the
+default slot or the `label` property. Choose `solid`, `dashed`, `dotted`, or `double` with `lineStyle`, and place
+text at `start`, `center`, or `end` with `textPlacement`. `thickness`, `color`, and `spacing` provide direct
+appearance controls, while the `divider`, `line`, `line-before`, `line-after`, `text`, and `fallback` shadow
+parts support product-specific styling. The internal separator exposes the correct `aria-orientation`.
+
+## Timeline
+
+Use `@haiyue/ui/timeline` for ordered activity, history, and process displays. Assign typed `items` containing
+`title`, optional `label` and `description`, semantic `status`, custom `color` or `dot`, and an optional per-item
+`position`. The `left`, `right`, and `alternate` modes control placement; `reverse` flips the order and moves an
+optional `pending` node to the leading edge. `renderItem` and `renderDot` provide DOM customization without
+changing the data contract. The ordered list automatically collapses to a readable single-column layout on
+narrow screens and its pending animation honors reduced-motion preferences.
+
+## Rate
+
+Import and register the star rating independently:
+
+```ts
+import { defineRateComponents } from '@haiyue/ui/rate';
+
+defineRateComponents();
+```
+
+`<hy-rate>` exposes a controlled numeric `value` and defaults to five stars. Add `allow-half` (or set
+`allowHalf = true`) for 0.5 increments. Configure `count`, `allowClear`, `character`, and `tooltips`, or set
+`disabled` / `readOnly` for non-editable states. The component exposes slider semantics, arrow/Home/End keyboard
+control, `value-change` and `hover-change` composed events, plus `group`, `star`, and `fill` shadow parts.
+
+## Watermark
+
+Wrap any content and render a non-interactive repeated text or image mark above it:
+
+```ts
+import { defineWatermarkComponents } from '@haiyue/ui/watermark';
+
+defineWatermarkComponents();
+const watermark = document.querySelector('hy-watermark');
+watermark.content = ['HAIYUE', 'INTERNAL'];
+```
+
+Use `content` for one or more text lines, or set `image` to prefer an image mark. Geometry is controlled by
+`rotate`, `gapX`, `gapY`, `offsetX`, `offsetY`, `markWidth`, and `markHeight`; typography and appearance use
+`fontSize`, `fontFamily`, `fontWeight`, `color`, `opacity`, and `zIndex`. The SVG pattern lives inside the
+component shadow root, is hidden from assistive technology, and uses `pointer-events: none`, so links, buttons,
+and other slotted content remain interactive. Shadow parts expose `content`, `overlay`, `mark`, `text`, and
+`image` for targeted styling.
+
+## Table
+
+Import the data table from its focused entry. It applies local filters first, then stable sorting, and finally
+pagination, so only the current page is rendered as rows:
+
+```ts
+import { defineTableComponents } from '@haiyue/ui/table';
+
+defineTableComponents();
+const table = document.querySelector('hy-table');
+table.columns = [
+  { key: 'name', title: 'Name', sortable: true, filterable: true },
+  { key: 'role', title: 'Role', filterOptions: roles },
+  { key: 'score', title: 'Score', sortable: true, align: 'right' },
+];
+table.dataSource = records;
+table.pageSize = 20;
+```
+
+Use `page`, `pageSize`, `pageSizeOptions`, and `pagination` for paging; `filters`, `setFilter()`, and
+`clearFilters()` for filtering; and `sort`, `sortBy()`, and `clearSort()` for ordering. Columns may provide a
+custom `filter`, `sorter`, or `render` function. `table-change` reports the complete processed state after a
+user or API change, while `row-click` returns the source record and its original absolute index. The `empty`
+slot, semantic theme tokens, and exported shadow parts support content and visual customization.
+
+Filterable columns show a funnel control beside the title. Set `table.showFilters = false` or
+`show-filters="false"` to hide all filter controls while keeping programmatic filtering active. Set
+`showFilter: false` on an individual column to hide only that column's funnel. The filter menu, trigger, panel,
+input, and clear action are exposed through the `filter-menu`, `filter-trigger`, `filter-panel`, `filter`, and
+`filter-clear` shadow parts.
+
 ## Drawer
 
 Import and register the drawer independently when a product needs an off-canvas panel:
@@ -156,6 +479,104 @@ Single-value mode uses `value`; interval mode exposes `lowerValue`, `upperValue`
 `rail`, `track`, `handle`, `handle-lower`, and `handle-upper` shadow parts. `value-input` reports live movement and
 `value-change` reports a committed pointer or keyboard change.
 
+## Virtual keyboard
+
+Import the on-screen keyboard independently and bind it to a text input or textarea:
+
+```ts
+import { defineVirtualKeyboardComponents } from '@haiyue/ui/virtual-keyboard';
+
+defineVirtualKeyboardComponents();
+const keyboard = document.querySelector('hy-virtual-keyboard');
+keyboard.target = document.querySelector('textarea');
+keyboard.physicalSync = true;
+keyboard.mode = 'numeric'; // switch back with 'qwerty'
+await keyboard.type('Haiyue UI', { interval: 45 });
+```
+
+The default exported `HY_VIRTUAL_KEYBOARD_QWERTY_LAYOUT` includes digits, letters, Shift, Caps Lock, editing,
+all four arrow directions, caret, and navigation keys. Set `mode` to `qwerty` or `numeric`; the numeric mode uses
+the exported `HY_VIRTUAL_KEYBOARD_NUMERIC_LAYOUT` with digits, decimal, minus, deletion, and Enter keys. Assign
+`layout` with rows of typed key descriptors for shortcut or product-specific keyboards. Pointer and native keyboard activation edit the bound target and emit its normal
+`input` event; `physicalSync` mirrors real key state without duplicating native input. `press()`, `release()`,
+`tap()`, `type()`, and `clear()` support guided playback. Observe `virtual-keyboard-down`,
+`virtual-keyboard-up`, and `virtual-keyboard-input`, or style `keyboard`, `row`, `key`, and per-code key parts
+with the `--hy-virtual-keyboard-*` tokens.
+
+## Draggable container
+
+Import the transform-based container independently, then use any slotted element as its handle:
+
+```ts
+import { defineDraggableComponents } from '@haiyue/ui/draggable';
+
+defineDraggableComponents();
+const panel = document.querySelector('hy-draggable');
+panel.bounds = 'parent';
+panel.axis = 'both';
+panel.grid = 8;
+panel.moveTo(24, 24);
+```
+
+`bounds` accepts `none`, `parent`, `viewport`, or an `HTMLElement`; `axis` accepts `both`, `x`, or `y`.
+Use `handle` to restrict pointer starts to a selector and `cancel` to exclude interactive content. The default
+cancel selector protects inputs, buttons, links, editable content, and `[data-no-drag]`. Arrow keys move by one
+grid step, Shift multiplies that step by ten, and Home resets the position. `moveTo()`, `moveBy()`, `reset()`,
+and `refresh()` provide imperative control. Observe cancelable `drag-start`, followed by `drag-move` and
+`drag-end`; style the exported `surface` part and `--hy-draggable-*` tokens.
+
+## Resizable container
+
+Import the eight-handle transform frame independently. Its four corner points and four edge-midpoint handles
+resize the rectangle; dragging the content surface moves it:
+
+```ts
+import { defineResizableComponents } from '@haiyue/ui/resizable';
+
+defineResizableComponents();
+const frame = document.querySelector('hy-resizable');
+frame.bounds = 'parent';
+frame.grid = 8;
+frame.aspectRatio = 16 / 9;
+frame.setRect({ x: 48, y: 48, width: 240, height: 135 });
+```
+
+Configure `minWidth`, `minHeight`, `maxWidth`, and `maxHeight`, or use the matching kebab-case attributes.
+`bounds` accepts `none`, `parent`, `viewport`, or an `HTMLElement`; `movable="false"` keeps content stationary
+while preserving resize handles. The focused frame and handles support arrows, Shift acceleration, and Home
+reset. Imperative APIs include `setRect()`, `moveTo()`, `moveBy()`, `resizeTo()`, `reset()`, and `refresh()`.
+Observe cancelable `resize-start`, continuous `resize`, and `resize-end` events. Shadow parts expose `frame`,
+`content`, `handle`, and every directional handle such as `handle-nw`; appearance uses `--hy-resizable-*` tokens.
+
+## Virtual mouse
+
+Import the fixed-position cursor visual independently. It never intercepts pointer input or synthesizes clicks on
+page elements; host applications receive composed events and decide how actions map to product behavior:
+
+```ts
+import { defineVirtualMouseComponents } from '@haiyue/ui/virtual-mouse';
+
+defineVirtualMouseComponents();
+const mouse = document.querySelector('hy-virtual-mouse');
+mouse.images = {
+  idle: '/cursor-idle.png',
+  'left-down': '/cursor-left.png',
+  'right-down': '/cursor-right.png',
+};
+mouse.show();
+await mouse.moveTo(420, 280, { animate: true, duration: 600 });
+await mouse.leftClick();
+await mouse.rightClick();
+```
+
+Use `moveTo()` / `moveBy()` for coordinates, `press()` / `release()` for held-button states, and
+`leftClick()` / `middleClick()` / `rightClick()` for timed click feedback. `animated`, `duration`, and `easing`
+provide host defaults; every move may override them. State images may also be supplied through `idle-image`,
+`left-down-image`, `middle-down-image`, and `right-down-image`. Style the exported `cursor`, `shape`, `image`,
+and `indicator` parts or the `--hy-virtual-mouse-*` CSS variables. Events include `virtual-mouse-move-start`,
+`virtual-mouse-move`, `virtual-mouse-move-end`, `virtual-mouse-down`, `virtual-mouse-up`, and
+`virtual-mouse-click`.
+
 ## Themes
 
 Two optional CSS theme entries are provided. Import only the skin a product needs, or import both when the
@@ -189,7 +610,11 @@ npm run examples
 ```
 
 Then open <http://localhost:4173/>. The gallery provides a left-side component index and live examples for
-every exported component, including editable parameters and event output.
+every exported component, including editable parameters and event output. The gallery shell itself dogfoods
+Haiyue UI: theme actions, component search, command results, status, and example action controls use the
+published Web Components rather than parallel page-only widgets. The navigation/content shell and eligible
+preview/control cards use `hy-split` for keyboard- and pointer-adjustable sizing. Usage blocks are rendered as
+read-only CodeMirror editors with HTML, JavaScript, and CSS syntax highlighting.
 
 ## Expandable container
 
@@ -231,3 +656,21 @@ npm run release:check
 
 Candidates: `.artifacts/packages/`. Review API changes before `npm run api:update`.
 See [release review](review/release-0.1.2.md).
+
+### 共享组件目录（开发中）
+
+`@haiyue/ui/core` 的 `HYComponentProps` 增加五种节点，Web 适配复用对应组件子模块，Native 适配使用原生控件；不新增根导出，也不自动注册全部组件。现有 18 种节点保持兼容，支持范围由 renderer 的 `capabilities.components` 声明。
+
+| 节点 | 对应 WebComponent | 当前共享属性 |
+| --- | --- | --- |
+| `Checkbox` | `hy-checkbox` | `text`, `checked`, `disabled`；区别于原生开关 `Toggle` |
+| `RadioGroup` | 一组 `hy-radio` | `value`, `options`, `disabled`；值必须出现在选项中 |
+| `Rate` | `hy-rate` | `value`（0 到 count 的整数）, `count`（1–10）, `disabled`, `readOnly` |
+| `Badge` | `hy-badge` | 独立文本 `text`，计数截断由应用决定 |
+| `Divider` | `hy-divider` | 水平分隔线，可选 `text` |
+
+交互节点受应用状态控制，通过同一 transaction 的 `valueChange` / `commit` 提议变更；应用拒绝时保留已接受值。评分的半星、悬浮效果，徽标的圆点、动画、悬挂计数，分隔线的垂直/虚线模式尚未纳入共享协议。请勿把 WebComponent 的所有属性直接传入通用节点。
+
+Native 仓库的 `examples/ui-validation/mobile` 提供独立「Haiyue UI」组件实验室；折叠内容、步骤导航与按钮组是基础节点组合示例，不是新增协议节点。
+
+Web 的 `hy-badge` 新增可选 `literal` 属性（默认为 false）：启用后 `count` 按原始文字显示，保留 0、前导零和大数字。普通计数的隐藏零值、截断，以及 status/text 模式保持原行为；共享 Badge 适配显式启用此模式。

package/dist/adapters/web/controls.d.ts

@@ -0,0 +1,19 @@
+import type { HYNode } from '../../core/types.js';
+import type { HYWebControl, HYWebControlContext } from './types.js';
+/** Registration is explicit and limited to the reused components. */
+export declare function definePortableWebComponents(): void;
+export declare const componentTags: Readonly<{
+    Checkbox: "hy-checkbox";
+    RadioGroup: "div";
+    Rate: "hy-rate";
+    Badge: "hy-badge";
+    Divider: "hy-divider";
+    Button: "hy-button";
+    Toggle: "hy-checkbox";
+    Select: "hy-select";
+    Tabs: "hy-tabs";
+    TextInput: "hy-input";
+    Slider: "hy-range";
+    Dialog: "hy-dialog";
+}>;
+export declare function createControl(node: HYNode, context: HYWebControlContext, revision: number): HYWebControl | undefined;