@haiyue/ui 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.2 - 2026-09-03
+
+- 修复 `<hy-virtual-list>` 快速滚动时 light DOM slot 异步分发旧行的问题；虚拟窗口现在完全在 Shadow DOM 内同步替换，避免上一范围的条目再次闪现。
+- 新增 `HYExpandable` / `<hy-expandable>`：保持内容挂载的非模态展开容器，提供独立子入口、尺寸与按钮位置配置、自定义图标、事件和主题变量。
+- 修复展开容器位于嵌套 Shadow DOM 时 Escape 无法恢复的问题；内部菜单可优先消费 Escape，嵌套展开容器每次只关闭内层。
+- Tabs 支持横向溢出滚动，并保持标签文字不换行。
+- 补充展开容器示例和浏览器交互回归，覆盖键盘、焦点、事件、内容保留及断开重连。
+- API 基线、包体积与消费者验证由 UI 仓库独立维护，不再由 Engine 发布门禁管理。
+
+## 0.1.1 - 2026-08-22
+
+- 新增可按需导入的 `HYRange` / `<hy-range>` 数值滑块，支持单值和双拖拽点区间、步进与键盘操作、实时/提交事件，以及拖拽点和轨道样式定制。
+- 新增可按需导入的 `HYBorderBeam` / `<hy-border-beam>` 响应式边框流光组件，支持粗细、速度倍率、颜色和多流光错相配置。
+- 新增可按需导入的 `HYNotification` / `<hy-notification>` 通知中心，提供 success/info/warning/error 语义配色和图标、六向 placement、自动关闭、Z 轴堆叠及可选倒计时进度条。
+- 新增可按需导入的 `HYDrawer` / `<hy-drawer>` 抽屉组件，支持四向 placement、可选蒙层、Esc/蒙层关闭、焦点管理及 `destroyOnHidden` 内容卸载。
+- 新增可按需导入的 `HYVirtualList` / `<hy-virtual-list>` 固定行高虚拟列表，仅渲染可视区与 overscan 缓冲项，并提供内部滚动条、范围事件、点击事件和 `scrollToIndex()`。
+- 组件品牌前缀从 `GE/ge` 统一迁移为 `HY/hy`，不保留旧标签、类名或 CSS token alias；新增可独立导入的 Moonlight 淡蓝亮色和 Nightfall 深蓝紫暗色皮肤。
+- 独立 UI 仓库移除重复的 `ui/` workspace 层级，并为全部组件新增 `@haiyue/ui/<component>` 独立、无副作用的公开入口；根入口继续提供显式全量注册。
+
+## 0.1.0 - 2026-07-13
+
+- 建立海月 3D 优先的稳定包边界、生命周期、编辑器工作流、可观测性、资产管线和脚本 runtime。
+- 用 `simple` / `batched` / `gpu-driven` / `diagnostic` RenderProfile 替换公开渲染布尔开关，并加入显式设备降级报告。
+- 加入原生 glTF metallic-roughness PBR、directional shadow map、environment IBL、material variants 和可扩展材质 shader contract。
+- examples/games 改为 manifest 驱动，统一 build policy、能力覆盖矩阵、真实 WebGPU 像素基线和 release gate。

package/README.md

@@ -3,6 +3,8 @@
 Dependency-free Web Components for HaiyueStudio products. Components own presentation and local interaction;
 they do not depend on Engine, Editor, Games, or AIStudio state.
 
+**Online component gallery:** <https://haiyuestudio.github.io/UI/>
+
 Public classes use the `HY` prefix and custom-element tags use `hy-`:
 
 ```html
@@ -44,6 +46,21 @@ defineHaiyueUI();
 Because `defineHaiyueUI()` references the complete component set, prefer focused subpaths in bundle-sensitive
 product entry points.
 
+## Tabs
+
+`@haiyue/ui/tabs` retains its existing `HYTabs`, `HYTabOption`, `HYTabChangeDetail`, and
+`defineTabsComponents` exports; the 0.1.3 fix adds no new public exports. Assign `options`
+and `value`, provide children with matching `slot` names, and listen for `tab-change`.
+Property-assigned options and the selected value survive reconnection. Set `aria-label`
+to name the tablist. Arrow keys, Home and End both move focus and activate the next
+enabled tab with roving focus; the active tab labels its panel within the component's
+shadow tree. The generated `aria-controls` and tabpanel ids are per-instance opaque
+values and should not be treated as stable application selectors.
+
+The existing `@haiyue/ui/border-beam` exports are also unchanged. Its constructor only
+builds shadow content; host appearance is applied after creation, avoiding browser
+custom-element construction errors during repeated `document.createElement` calls.
+
 ## Virtual list
 
 `<hy-virtual-list>` renders only the visible fixed-height rows plus a configurable overscan buffer. The full
@@ -163,6 +180,8 @@ All theme tokens use the `--hy-` prefix and may be overridden by consuming produ
 
 ## Component examples
 
+Browse the published gallery at <https://haiyuestudio.github.io/UI/>.
+
 Run the interactive component gallery locally:
 
 ```bash
@@ -171,3 +190,44 @@ 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.
+
+## Expandable container
+
+Explicit export: `@haiyue/ui/expandable` → `HYExpandable`, `defineExpandableComponents`,
+`HYExpandableButtonPosition`, `HYExpandableChangeDetail`. Also included in `defineHaiyueUI()`.
+
+```html
+<hy-expandable expanded-width="1200px" expanded-height="90dvh"
+  button-position="top-right" expand-label="放大" restore-label="还原">
+  <div>Your graph, editor, or other stateful content</div>
+  <!-- Optional SVG elements: slot="expand-icon" / slot="restore-icon" -->
+</hy-expandable>
+```
+
+`expanded` is a reflected boolean attribute/property; `toggle()` switches it.
+`expandedWidth` / `expandedHeight` accept CSS lengths (defaults `90vw` / `90dvh`).
+Sizes are clamped to the viewport with a margin; the normal size belongs to the host's layout/CSS.
+`buttonPosition` supports `top-right`, `top-left`, `bottom-right`, `bottom-left`.
+`expanded-change` bubbles with `{ expanded: boolean }`. `expand-icon` / `restore-icon` slots
+replace the built-in SVG icons without accepting HTML strings. Labels also become tooltips.
+Style through inherited `--hy-surface-color`, `--hy-border-color`, `--hy-text-color`,
+`--hy-accent-color` and `--hy-expandable-{margin,padding,radius,shadow,button-size,button-offset}`;
+`panel` and `toggle` are CSS parts.
+
+Requires a browser supporting the Popover API. Expansion is non-modal and uses a fixed top-layer
+panel so transformed/overflow ancestors cannot clip it. The same slotted DOM stays mounted;
+normal-flow height is preserved while expanded. Keyboard activation uses the native button;
+Escape restores the focused container. Disconnect closes the panel and releases event listeners.
+
+## Independent release checks
+
+UI releases independently of Engine.
+
+```bash
+npm ci
+npx playwright install chromium
+npm run release:check
+```
+
+Candidates: `.artifacts/packages/`. Review API changes before `npm run api:update`.
+See [release review](review/release-0.1.2.md).

package/dist/border-beam.js

@@ -73,6 +73,7 @@ export class HYBorderBeam extends HTMLElement {
         if (this._connected)
             return;
         this._connected = true;
+        this._updateAppearance();
         if (typeof ResizeObserver !== 'undefined') {
             this._resizeObserver = new ResizeObserver(() => this.refresh());
             this._resizeObserver.observe(this);
@@ -145,7 +146,8 @@ export class HYBorderBeam extends HTMLElement {
             beams.push(beam);
         }
         this._beamLayer.replaceChildren(...beams);
-        this._updateAppearance();
+        // Construction may populate the shadow tree, but must not add host attributes.
+        // Host styles are applied by the connection/attribute lifecycle instead.
     }
     _updateAppearance() {
         const duration = BASE_DURATION_SECONDS / this.speed;

package/dist/expandable.d.ts

@@ -0,0 +1,32 @@
+export type HYExpandableButtonPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+export interface HYExpandableChangeDetail {
+    expanded: boolean;
+}
+/** A non-modal, top-layer expansion of the same slotted content; no cloning or reparenting. */
+export declare class HYExpandable extends HTMLElement {
+    static get observedAttributes(): string[];
+    private readonly panel;
+    private readonly placeholder;
+    private readonly button;
+    private readonly expandIcon;
+    private readonly restoreIcon;
+    private lifetime;
+    private active;
+    constructor();
+    get expanded(): boolean;
+    set expanded(value: boolean);
+    get expandedWidth(): string;
+    set expandedWidth(value: string);
+    get expandedHeight(): string;
+    set expandedHeight(value: string);
+    get buttonPosition(): HYExpandableButtonPosition;
+    set buttonPosition(value: HYExpandableButtonPosition);
+    toggle(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    private render;
+    private sync;
+    private closePanel;
+}
+export declare function defineExpandableComponents(): void;

package/dist/expandable.js

@@ -0,0 +1,136 @@
+/** A non-modal, top-layer expansion of the same slotted content; no cloning or reparenting. */
+export class HYExpandable extends HTMLElement {
+    static get observedAttributes() { return ['expanded', 'expanded-width', 'expanded-height', 'button-position', 'expand-label', 'restore-label']; }
+    panel;
+    placeholder;
+    button;
+    expandIcon;
+    restoreIcon;
+    lifetime;
+    active = false;
+    constructor() {
+        super();
+        const root = this.attachShadow({ mode: 'open' });
+        const style = document.createElement('style');
+        style.textContent = `
+      :host { display:block; position:relative; min-width:0; min-height:0; }
+      .placeholder { display:none; pointer-events:none; }
+      .panel { position:relative; display:grid; grid-template-columns:minmax(0,1fr); grid-template-rows:minmax(0,1fr); width:100%; height:100%; min-width:0; min-height:0; box-sizing:border-box; color:inherit; font:inherit; }
+      .panel:popover-open { position:fixed; inset:0; margin:auto; width:var(--_width,90vw); height:var(--_height,90dvh); max-width:calc(100vw - 2 * var(--hy-expandable-margin,16px)); max-height:calc(100dvh - 2 * var(--hy-expandable-margin,16px)); padding:var(--hy-expandable-padding,16px); border:1px solid var(--hy-border-color,#536074); border-radius:var(--hy-expandable-radius,10px); background:var(--hy-surface-color,#18202e); box-shadow:var(--hy-expandable-shadow,0 16px 64px #0006); }
+      .panel::backdrop { background:transparent; pointer-events:none; }
+      button { position:absolute; z-index:2; top:var(--hy-expandable-button-offset,8px); right:var(--hy-expandable-button-offset,8px); display:grid; place-items:center; width:var(--hy-expandable-button-size,32px); height:var(--hy-expandable-button-size,32px); padding:6px; border:1px solid var(--hy-border-color,#536074); border-radius:6px; color:var(--hy-text-color,inherit); background:var(--hy-surface-color,#18202e); cursor:pointer; }
+      button:hover { color:var(--hy-accent-color,#7dd3fc); }
+      button:focus-visible { outline:2px solid var(--hy-accent-color,#7dd3fc); outline-offset:2px; }
+      button[data-position$="left"] { left:var(--hy-expandable-button-offset,8px); right:auto; }
+      button[data-position^="bottom"] { bottom:var(--hy-expandable-button-offset,8px); top:auto; }
+      svg, ::slotted([slot="expand-icon"]), ::slotted([slot="restore-icon"]) { width:100%; height:100%; pointer-events:none; }
+      slot[hidden] { display:none; }
+    `;
+        this.placeholder = document.createElement('div');
+        this.placeholder.className = 'placeholder';
+        this.panel = document.createElement('div');
+        this.panel.className = 'panel';
+        this.panel.id = 'panel';
+        this.panel.part.add('panel');
+        this.button = document.createElement('button');
+        this.button.type = 'button';
+        this.button.part.add('toggle');
+        this.button.setAttribute('aria-controls', 'panel');
+        const icon = (name, path) => {
+            const slot = document.createElement('slot');
+            slot.name = name;
+            slot.setAttribute('aria-hidden', 'true');
+            const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+            svg.setAttribute('viewBox', '0 0 24 24');
+            svg.setAttribute('fill', 'none');
+            svg.setAttribute('stroke', 'currentColor');
+            svg.setAttribute('stroke-width', '1.8');
+            const shape = document.createElementNS(svg.namespaceURI, 'path');
+            shape.setAttribute('d', path);
+            svg.append(shape);
+            slot.append(svg);
+            return slot;
+        };
+        this.expandIcon = icon('expand-icon', 'M8 3H3v5m13-5h5v5M3 16v5h5m13-5v5h-5M3 3l6 6m12-6-6 6M3 21l6-6m12 6-6-6');
+        this.restoreIcon = icon('restore-icon', 'M3 9h6V3m6 0v6h6M9 21v-6H3m18 0h-6v6M3 3l6 6m12-6-6 6M3 21l6-6m12 6-6-6');
+        this.button.append(this.expandIcon, this.restoreIcon);
+        this.panel.append(document.createElement('slot'), this.button);
+        root.append(style, this.placeholder, this.panel);
+        this.button.addEventListener('click', () => this.toggle());
+        this.render();
+    }
+    get expanded() { return this.hasAttribute('expanded'); }
+    set expanded(value) { this.toggleAttribute('expanded', Boolean(value)); }
+    get expandedWidth() { return this.getAttribute('expanded-width') ?? '90vw'; }
+    set expandedWidth(value) { this.setAttribute('expanded-width', value); }
+    get expandedHeight() { return this.getAttribute('expanded-height') ?? '90dvh'; }
+    set expandedHeight(value) { this.setAttribute('expanded-height', value); }
+    get buttonPosition() {
+        const value = this.getAttribute('button-position');
+        return (['top-left', 'bottom-right', 'bottom-left'].includes(value ?? '') ? value : 'top-right');
+    }
+    set buttonPosition(value) { this.setAttribute('button-position', value); }
+    toggle() { this.expanded = !this.expanded; }
+    connectedCallback() {
+        this.lifetime?.abort();
+        this.lifetime = new AbortController();
+        this.addEventListener('keydown', event => {
+            // Bubbling follows the composed tree across shadow roots. Child menus and
+            // expanded containers consume Escape before it reaches their ancestors.
+            if (event.key === 'Escape' && !event.defaultPrevented && this.active) {
+                event.preventDefault();
+                this.expanded = false;
+                this.button.focus({ preventScroll: true });
+            }
+        }, { signal: this.lifetime.signal });
+        queueMicrotask(() => { if (this.isConnected)
+            this.sync(); });
+    }
+    disconnectedCallback() {
+        this.lifetime?.abort();
+        this.lifetime = undefined;
+        this.closePanel(); // Attribute remains available if the owner reconnects this element.
+    }
+    attributeChangedCallback() { this.render(); if (this.isConnected)
+        this.sync(); }
+    render() {
+        for (const [name, value] of [['width', this.expandedWidth], ['height', this.expandedHeight]]) {
+            this.panel.style.removeProperty(`--_${name}`);
+            if (CSS.supports(name, value))
+                this.panel.style.setProperty(`--_${name}`, value);
+        }
+        this.button.dataset.position = this.buttonPosition;
+        this.button.setAttribute('aria-expanded', String(this.expanded));
+        const label = this.getAttribute(this.expanded ? 'restore-label' : 'expand-label') ?? (this.expanded ? 'Restore size' : 'Expand');
+        this.button.setAttribute('aria-label', label);
+        this.button.title = label;
+        this.expandIcon.hidden = this.expanded;
+        this.restoreIcon.hidden = !this.expanded;
+    }
+    sync() {
+        if (this.expanded === this.active)
+            return;
+        if (this.expanded) {
+            this.placeholder.style.height = `${this.getBoundingClientRect().height}px`;
+            this.placeholder.style.display = 'block';
+            this.panel.setAttribute('popover', 'manual');
+            this.panel.showPopover();
+            this.active = true;
+        }
+        else
+            this.closePanel();
+        this.dispatchEvent(new CustomEvent('expanded-change', { detail: { expanded: this.active }, bubbles: true, composed: true }));
+    }
+    closePanel() {
+        if (this.panel.matches(':popover-open'))
+            this.panel.hidePopover();
+        this.panel.removeAttribute('popover');
+        this.placeholder.style.display = 'none';
+        this.active = false;
+    }
+}
+export function defineExpandableComponents() {
+    if (!customElements.get('hy-expandable'))
+        customElements.define('hy-expandable', HYExpandable);
+}
+//# sourceMappingURL=expandable.js.map

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { defineExpandableComponents, HYExpandable } from './expandable.js';
+export type { HYExpandableButtonPosition, HYExpandableChangeDetail } from './expandable.js';
 export { defineButtonComponents, HYButton, } from './button.js';
 export { defineBorderBeamComponents, HYBorderBeam, } from './border-beam.js';
 export { defineTreeComponents, HYTree, HYTreeNode, } from './tree.js';

package/dist/index.js

@@ -1,3 +1,5 @@
+import { defineExpandableComponents } from './expandable.js';
+export { defineExpandableComponents, HYExpandable } from './expandable.js';
 import { defineButtonComponents } from './button.js';
 import { defineBorderBeamComponents } from './border-beam.js';
 import { defineTreeComponents } from './tree.js';
@@ -35,6 +37,7 @@ export { defineNotificationComponents, HYNotification, } from './notification.js
 export { defineHistoryControlsComponents, HYHistoryControls, } from './history-controls.js';
 export { calculateVirtualListRange, defineVirtualListComponents, HYVirtualList, } from './virtual-list.js';
 export function defineHaiyueUI() {
+    defineExpandableComponents();
     defineBorderBeamComponents();
     defineButtonComponents();
     defineTreeComponents();

package/dist/tabs.d.ts

@@ -11,7 +11,9 @@ export declare class HYTabs extends HTMLElement {
     private readonly _style;
     private readonly _tabs;
     private readonly _panels;
+    private readonly _instanceId;
     private _options;
+    private _pendingFocusValue;
     static get observedAttributes(): string[];
     constructor();
     connectedCallback(): void;
@@ -23,6 +25,8 @@ export declare class HYTabs extends HTMLElement {
     private _syncFromAttributes;
     private _readOptionsAttribute;
     private _render;
+    private _focusTab;
+    private _resolveValue;
     private _select;
 }
 export declare function defineTabsComponents(): void;

package/dist/tabs.js

@@ -2,9 +2,11 @@ export class HYTabs extends HTMLElement {
     _style = document.createElement('style');
     _tabs = document.createElement('div');
     _panels = document.createElement('div');
+    _instanceId = `hy-tabs-${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
     _options = [];
+    _pendingFocusValue = null;
     static get observedAttributes() {
-        return ['options', 'value'];
+        return ['options', 'value', 'aria-label'];
     }
     constructor() {
         super();
@@ -27,6 +29,9 @@ export class HYTabs extends HTMLElement {
         align-items: end;
         gap: 2px;
         min-width: 0;
+        overflow-x: auto;
+        overflow-y: hidden;
+        scrollbar-width: none;
         padding: 4px 6px 0;
         border-bottom: 1px solid var(--hy-border-color, #303746);
         background: var(--hy-tabs-bar-bg-color, var(--hy-menu-bg-color, var(--hy-surface-elevated-color, #1b2230)));
@@ -34,6 +39,8 @@ export class HYTabs extends HTMLElement {
       button {
         height: 28px;
         min-width: 0;
+        flex-shrink: 0;
+        white-space: nowrap;
         padding: 0 10px;
         border: 1px solid transparent;
         border-bottom: 0;
@@ -66,6 +73,7 @@ export class HYTabs extends HTMLElement {
       }
     `;
         this._tabs.className = 'tabs';
+        this._tabs.setAttribute('role', 'tablist');
         this._panels.className = 'panels';
         root.append(this._style, this._tabs, this._panels);
     }
@@ -74,11 +82,16 @@ export class HYTabs extends HTMLElement {
         this._render();
     }
     attributeChangedCallback(name, _oldValue, newValue) {
+        if (_oldValue === newValue)
+            return;
         if (name === 'options')
             this._readOptionsAttribute();
-        if (name === 'value' && newValue === null && this._options[0]) {
-            this.setAttribute('value', this._options[0].value);
-            return;
+        if (name === 'value' && newValue === null) {
+            const value = this._resolveValue();
+            if (value) {
+                this.setAttribute('value', value);
+                return;
+            }
         }
         this._render();
     }
@@ -87,9 +100,9 @@ export class HYTabs extends HTMLElement {
     }
     set options(value) {
         this._options = Array.isArray(value) ? value : [];
-        if (!this._options.some(item => item.value === this.value)) {
-            this.value = this._options[0]?.value ?? '';
-        }
+        const resolved = this._resolveValue();
+        if (resolved !== this.value)
+            this.value = resolved;
         this._render();
     }
     get value() {
@@ -97,12 +110,13 @@ export class HYTabs extends HTMLElement {
     }
     set value(value) {
         this.setAttribute('value', value);
-        this._render();
     }
     _syncFromAttributes() {
-        this._readOptionsAttribute();
-        if (!this.value && this._options[0])
-            this.setAttribute('value', this._options[0].value);
+        if (this.hasAttribute('options'))
+            this._readOptionsAttribute();
+        const value = this._resolveValue();
+        if (value !== this.value)
+            this.setAttribute('value', value);
     }
     _readOptionsAttribute() {
         const raw = this.getAttribute('options');
@@ -125,25 +139,75 @@ export class HYTabs extends HTMLElement {
         }
     }
     _render() {
+        const focusedValue = this._pendingFocusValue
+            ?? [...this._tabs.querySelectorAll('button')].find(button => button === this.shadowRoot?.activeElement)?.dataset.value
+            ?? null;
+        this._pendingFocusValue = null;
         this._tabs.replaceChildren();
         this._panels.replaceChildren();
-        const value = this.value || this._options[0]?.value || '';
-        for (const option of this._options) {
+        this._tabs.setAttribute('aria-label', this.getAttribute('aria-label') ?? 'Tabs');
+        const enabled = this._options.filter(option => !option.disabled);
+        const value = this._resolveValue(enabled);
+        if (value !== this.value) {
+            this.setAttribute('value', value);
+            return;
+        }
+        const focusValue = enabled.some(option => option.value === value) ? value : enabled[0]?.value;
+        this._options.forEach((option, index) => {
             const button = document.createElement('button');
+            const panel = document.createElement('div');
             button.type = 'button';
+            button.id = `${this._instanceId}-tab-${index}`;
+            button.dataset.value = option.value;
+            button.setAttribute('role', 'tab');
+            button.setAttribute('aria-selected', String(option.value === value));
+            panel.id = `${this._instanceId}-panel-${index}`;
+            panel.hidden = option.value !== value;
+            panel.setAttribute('role', 'tabpanel');
+            panel.setAttribute('aria-labelledby', button.id);
+            button.setAttribute('aria-controls', panel.id);
+            button.tabIndex = option.value === focusValue && !option.disabled ? 0 : -1;
             button.textContent = option.label;
             button.disabled = Boolean(option.disabled);
             button.classList.toggle('active', option.value === value);
             button.addEventListener('click', () => this._select(option.value));
+            button.addEventListener('keydown', event => {
+                if (!['ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(event.key) || !enabled.length)
+                    return;
+                event.preventDefault();
+                const position = enabled.findIndex(item => item.value === option.value);
+                const next = event.key === 'Home' ? 0 : event.key === 'End' ? enabled.length - 1
+                    : (position + (event.key === 'ArrowLeft' ? -1 : 1) + enabled.length) % enabled.length;
+                this._pendingFocusValue = enabled[next].value;
+                this._select(enabled[next].value);
+            });
+            const slot = document.createElement('slot');
+            slot.name = option.value;
+            panel.append(slot);
             this._tabs.append(button);
+            this._panels.append(panel);
+        });
+        if (focusedValue) {
+            const restoreValue = enabled.some(option => option.value === focusedValue) ? focusedValue : focusValue;
+            if (restoreValue)
+                this._focusTab(restoreValue);
         }
-        const slot = document.createElement('slot');
-        slot.name = value;
-        this._panels.append(slot);
+    }
+    _focusTab(value) {
+        [...this._tabs.querySelectorAll('button')].find(button => button.dataset.value === value)?.focus();
+    }
+    _resolveValue(enabled = this._options.filter(option => !option.disabled)) {
+        if (enabled.some(option => option.value === this.value))
+            return this.value;
+        if (enabled[0])
+            return enabled[0].value;
+        return '';
     }
     _select(value) {
         if (value === this.value)
             return;
+        if (!this._options.some(option => option.value === value && !option.disabled))
+            return;
         this.setAttribute('value', value);
         const option = this._options.find(item => item.value === value) ?? null;
         this.dispatchEvent(new CustomEvent('tab-change', {

package/dist/virtual-list.js

@@ -8,7 +8,12 @@ export function calculateVirtualListRange(itemCount, itemHeight, viewportHeight,
     const count = Math.max(0, Math.floor(finiteNumber(itemCount, 0)));
     const rowHeight = Math.max(1, finiteNumber(itemHeight, DEFAULT_ITEM_HEIGHT));
     const visibleHeight = Math.max(0, finiteNumber(viewportHeight, 0));
-    const offset = Math.max(0, finiteNumber(scrollTop, 0));
+    const requestedOffset = Math.max(0, finiteNumber(scrollTop, 0));
+    const maximumOffset = Math.max(0, count * rowHeight - visibleHeight);
+    // Layout and ResizeObserver notifications can briefly observe a stale
+    // scrollTop after the viewport or item count changes. Keep the calculated
+    // window inside the collection instead of emitting an empty render range.
+    const offset = Math.min(requestedOffset, maximumOffset);
     const buffer = Math.max(0, Math.floor(finiteNumber(overscan, DEFAULT_OVERSCAN)));
     const visibleStartIndex = Math.min(count, Math.floor(offset / rowHeight));
     const visibleEndIndex = Math.min(count, Math.ceil((offset + visibleHeight) / rowHeight));
@@ -76,7 +81,7 @@ export class HYVirtualList extends HTMLElement {
       .viewport::-webkit-scrollbar-thumb:hover { background: var(--hy-accent-color, #79a8ff); }
       .spacer { position: relative; width: 100%; }
       .window { position: absolute; inset: 0 0 auto; will-change: transform; }
-      ::slotted(.hy-virtual-list-item) {
+      .hy-virtual-list-item {
         display: flex;
         align-items: center;
         width: 100%;
@@ -85,7 +90,7 @@ export class HYVirtualList extends HTMLElement {
         background: var(--hy-surface-color, #171d27);
         box-sizing: border-box;
       }
-      ::slotted(.hy-virtual-list-item:hover) { background: var(--hy-hover-bg-color, #273241); }
+      .hy-virtual-list-item:hover { background: var(--hy-hover-bg-color, #273241); }
       .empty {
         display: grid;
         height: 100%;
@@ -101,9 +106,6 @@ export class HYVirtualList extends HTMLElement {
         this._viewport.setAttribute('role', 'list');
         this._spacer.className = 'spacer';
         this._window.className = 'window';
-        const itemSlot = document.createElement('slot');
-        itemSlot.name = 'items';
-        this._window.append(itemSlot);
         this._spacer.append(this._window);
         this._empty.className = 'empty';
         this._empty.hidden = true;
@@ -270,7 +272,6 @@ export class HYVirtualList extends HTMLElement {
             const item = this._items[index];
             const row = document.createElement('div');
             row.className = 'hy-virtual-list-item';
-            row.slot = 'items';
             row.dataset.hyVirtualListGenerated = '';
             row.dataset.index = String(index);
             row.style.height = `${this._itemHeight}px`;
@@ -310,9 +311,10 @@ export class HYVirtualList extends HTMLElement {
         }));
     }
     _replaceRows(rows) {
-        for (const row of this.querySelectorAll(':scope > [data-hy-virtual-list-generated]'))
-            row.remove();
-        this.append(...rows);
+        // Keep the recycled window entirely inside the shadow tree. Slotted light
+        // DOM rows can be redistributed asynchronously while a host application is
+        // also updating, which may briefly paint rows from the previous range.
+        this._window.replaceChildren(...rows);
     }
 }
 export function defineVirtualListComponents() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haiyue/ui",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "description": "Dependency-free Web Components for HaiyueStudio tools and products.",
   "license": "MIT",
@@ -8,6 +8,7 @@
     "type": "git",
     "url": "git+https://github.com/HaiyueStudio/UI.git"
   },
+  "homepage": "https://haiyuestudio.github.io/UI/",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -94,15 +95,22 @@
     },
     "./themes/light.css": "./themes/haiyue-light.css",
     "./themes/dark.css": "./themes/haiyue-dark.css",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./expandable": {
+      "types": "./dist/expandable.d.ts",
+      "import": "./dist/expandable.js"
+    }
+  },
+  "engines": {
+    "node": ">=22"
   },
-  "engines": { "node": ">=22" },
   "publishConfig": {
     "access": "public",
     "tag": "latest"
   },
   "files": [
     "README.md",
+    "CHANGELOG.md",
     "LICENSE",
     "dist/**/*.js",
     "dist/**/*.d.ts",
@@ -110,13 +118,22 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "build:pages": "npm run build && node scripts/build-pages.mjs",
+    "check:pages": "npm run build:pages && node scripts/verify-pages.mjs",
     "examples": "npm run build && node scripts/serve-examples.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "npm run build && node --test \"test/**/*.test.mjs\"",
-    "prepack": "npm run typecheck && npm test",
-    "pack:candidate": "node scripts/pack-candidate.mjs"
+    "prepack": "npm run typecheck && npm test && npm run api:check",
+    "pack:candidate": "node scripts/pack-candidate.mjs",
+    "api:check": "node scripts/api-surface.mjs --check",
+    "api:update": "node scripts/api-surface.mjs --write",
+    "test:browser": "npm run build && playwright test",
+    "verify:package": "npm run prepack && node scripts/verify-package.mjs",
+    "release:check": "npm run verify:package && npm run test:browser && npm run check:pages"
   },
   "devDependencies": {
+    "@playwright/test": "^1.63.0",
+    "rollup": "^4.63.4",
     "typescript": "^5.2.0"
   }
 }