mdui 2.0.2 → 2.0.4

package/components/navigation-drawer/index.d.ts

@@ -12,52 +12,51 @@ import type { CSSResultGroup, PropertyValues, TemplateResult } from 'lit';
  * <mdui-navigation-drawer>content</mdui-navigation-drawer>
  * ```
  *
- * @event open - 在抽屉导航打开之前触发。可以通过调用 `event.preventDefault()` 阻止抽屉导航打开
- * @event opened - 在抽屉导航打开之后触发
- * @event close - 在抽屉导航关闭之前触发。可以通过调用 `event.preventDefault()` 阻止抽屉导航关闭
- * @event closed - 在抽屉导航关闭之后触发
+ * @event open - 抽屉栏打开之前触发。可以通过调用 `event.preventDefault()` 阻止抽屉栏打开
+ * @event opened - 抽屉栏打开动画完成之后触发
+ * @event close - 抽屉栏关闭之前触发。可以通过调用 `event.preventDefault()` 阻止抽屉栏关闭
+ * @event closed - 抽屉栏关闭动画完成之后触发
  * @event overlay-click - 点击遮罩层时触发
  *
- * @slot - 抽屉导航中的内容
+ * @slot - 抽屉栏中的内容
  *
  * @csspart overlay - 遮罩层
- * @csspart panel - 抽屉导航容器
+ * @csspart panel - 抽屉栏容器
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
- * @cssprop --z-index - 组件的 CSS 的 `z-index` 值
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --z-index - 组件的 CSS `z-index` 值
  */
-export declare class NavigationDrawer extends LayoutItemBase {
+export declare class NavigationDrawer extends LayoutItemBase<NavigationDrawerEventMap> {
     static styles: CSSResultGroup;
     /**
-     * 是否打开抽屉导航
+     * 是否打开抽屉栏
      */
     open: boolean;
     /**
-     * 打开时，是否显示遮罩层
+     * 抽屉栏打开时，是否显示遮罩层
      *
-     * 较窄的设备上（屏幕宽度小于 [`--mdui-breakpoint-md`](/docs/2/styles/design-tokens#breakpoint) 时），会无视该参数，始终显示遮罩层
+     * 在窄屏设备上（屏幕宽度小于 [`--mdui-breakpoint-md`](/docs/2/styles/design-tokens#breakpoint)），会始终显示遮罩层，无视该参数
      */
     modal: boolean;
     /**
-     * 在含遮罩层时，是否在按下 ESC 键时，关闭抽屉导航
+     * 在有遮罩层的情况下，按下 ESC 键是否关闭抽屉栏
      */
     closeOnEsc: boolean;
     /**
-     * 是否在点击遮罩时，关闭抽屉导航
+     * 点击遮罩层时，是否关闭抽屉栏
      */
     closeOnOverlayClick: boolean;
     /**
-     * 抽屉导航的显示位置。可选值为：
+     * 抽屉栏的位置。可选值包括：
      *
-     * * `left`：显示在左侧
-     * * `right`：显示在右侧
+     * * `left`：左侧
+     * * `right`：右侧
      */
-    placement: /*显示在左侧*/ 'left' | /*显示在右侧*/ 'right';
+    placement: /*左侧*/ 'left' | /*右侧*/ 'right';
     /**
-     * 默认抽屉导航相对于 `body` 元素显示，该参数设置为 `true` 时，抽屉导航将相对于它的父元素显示
+     * 默认情况下，抽屉栏相对于 `body` 元素显示。当该参数设置为 `true` 时，抽屉栏将相对于其父元素显示。
      *
-     * Note:
-     * 设置了该属性时，必须手动在父元素上设置样式 `position: relative; overflow: hidden;`
+     * **Note**：设置该属性时，必须在父元素上手动设置样式 `position: relative; overflow: hidden;`。
      */
     contained: boolean;
     private mobile;
@@ -81,6 +80,13 @@ export declare class NavigationDrawer extends LayoutItemBase {
     private onOverlayClick;
     private getLockTargetAnimate;
 }
+export interface NavigationDrawerEventMap {
+    open: CustomEvent<void>;
+    opened: CustomEvent<void>;
+    close: CustomEvent<void>;
+    closed: CustomEvent<void>;
+    'overlay-click': CustomEvent<void>;
+}
 declare global {
     interface HTMLElementTagNameMap {
         'mdui-navigation-drawer': NavigationDrawer;

package/components/navigation-drawer/index.js

@@ -12,7 +12,6 @@ import { watch } from '@mdui/shared/decorators/watch.js';
 import { animateTo, stopAnimations } from '@mdui/shared/helpers/animate.js';
 import { breakpoint } from '@mdui/shared/helpers/breakpoint.js';
 import { booleanConverter } from '@mdui/shared/helpers/decorator.js';
-import { emit } from '@mdui/shared/helpers/event.js';
 import { Modal } from '@mdui/shared/helpers/modal.js';
 import { getDuration, getEasing } from '@mdui/shared/helpers/motion.js';
 import { observeResize } from '@mdui/shared/helpers/observeResize.js';
@@ -29,53 +28,52 @@ import { style } from './style.js';
  * <mdui-navigation-drawer>content</mdui-navigation-drawer>
  * ```
  *
- * @event open - 在抽屉导航打开之前触发。可以通过调用 `event.preventDefault()` 阻止抽屉导航打开
- * @event opened - 在抽屉导航打开之后触发
- * @event close - 在抽屉导航关闭之前触发。可以通过调用 `event.preventDefault()` 阻止抽屉导航关闭
- * @event closed - 在抽屉导航关闭之后触发
+ * @event open - 抽屉栏打开之前触发。可以通过调用 `event.preventDefault()` 阻止抽屉栏打开
+ * @event opened - 抽屉栏打开动画完成之后触发
+ * @event close - 抽屉栏关闭之前触发。可以通过调用 `event.preventDefault()` 阻止抽屉栏关闭
+ * @event closed - 抽屉栏关闭动画完成之后触发
  * @event overlay-click - 点击遮罩层时触发
  *
- * @slot - 抽屉导航中的内容
+ * @slot - 抽屉栏中的内容
  *
  * @csspart overlay - 遮罩层
- * @csspart panel - 抽屉导航容器
+ * @csspart panel - 抽屉栏容器
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
- * @cssprop --z-index - 组件的 CSS 的 `z-index` 值
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --z-index - 组件的 CSS `z-index` 值
  */
 let NavigationDrawer = class NavigationDrawer extends LayoutItemBase {
     constructor() {
         super(...arguments);
         /**
-         * 是否打开抽屉导航
+         * 是否打开抽屉栏
          */
         this.open = false;
         /**
-         * 打开时，是否显示遮罩层
+         * 抽屉栏打开时，是否显示遮罩层
          *
-         * 较窄的设备上（屏幕宽度小于 [`--mdui-breakpoint-md`](/docs/2/styles/design-tokens#breakpoint) 时），会无视该参数，始终显示遮罩层
+         * 在窄屏设备上（屏幕宽度小于 [`--mdui-breakpoint-md`](/docs/2/styles/design-tokens#breakpoint)），会始终显示遮罩层，无视该参数
          */
         this.modal = false;
         /**
-         * 在含遮罩层时，是否在按下 ESC 键时，关闭抽屉导航
+         * 在有遮罩层的情况下，按下 ESC 键是否关闭抽屉栏
          */
         this.closeOnEsc = false;
         /**
-         * 是否在点击遮罩时，关闭抽屉导航
+         * 点击遮罩层时，是否关闭抽屉栏
          */
         this.closeOnOverlayClick = false;
         /**
-         * 抽屉导航的显示位置。可选值为：
+         * 抽屉栏的位置。可选值包括：
          *
-         * * `left`：显示在左侧
-         * * `right`：显示在右侧
+         * * `left`：左侧
+         * * `right`：右侧
          */
         this.placement = 'left';
         /**
-         * 默认抽屉导航相对于 `body` 元素显示，该参数设置为 `true` 时，抽屉导航将相对于它的父元素显示
+         * 默认情况下，抽屉栏相对于 `body` 元素显示。当该参数设置为 `true` 时，抽屉栏将相对于其父元素显示。
          *
-         * Note:
-         * 设置了该属性时，必须手动在父元素上设置样式 `position: relative; overflow: hidden;`
+         * **Note**：设置该属性时，必须在父元素上手动设置样式 `position: relative; overflow: hidden;`。
          */
         this.contained = false;
         // 断点为 mobile 时为 `true` 时，强制使用遮罩层
@@ -92,7 +90,7 @@ let NavigationDrawer = class NavigationDrawer extends LayoutItemBase {
     get lockTarget() {
         return this.contained || this.isParentLayout
             ? this.parentElement
-            : document.body;
+            : document.documentElement;
     }
     get isModal() {
         return this.mobile || this.modal;
@@ -101,7 +99,7 @@ let NavigationDrawer = class NavigationDrawer extends LayoutItemBase {
     async onContainedChange() {
         await this.definedController.whenDefined();
         this.observeResize?.unobserve();
-        this.observeResize = observeResize(this.contained ? this.parentElement : document.body, () => {
+        this.observeResize = observeResize(this.contained ? this.parentElement : document.documentElement, () => {
             const target = this.contained ? this.parentElement : undefined;
             this.mobile = breakpoint(target).down('md');
             // 若位于 layout 中，且为模态化，则重新布局时，占据的宽度为 0
@@ -143,14 +141,22 @@ let NavigationDrawer = class NavigationDrawer extends LayoutItemBase {
         };
         // 停止原有动画
         const stopOldAnimations = async () => {
-            await Promise.all([
-                this.isModal
-                    ? stopAnimations(overlay)
-                    : !this.isParentLayout
-                        ? stopAnimations(this.lockTarget)
-                        : Promise.resolve(),
-                this.isModal ? stopAnimations(panel) : stopAnimations(this),
-            ]);
+            const elements = [];
+            if (this.isModal) {
+                elements.push(overlay, panel);
+            }
+            else if (!this.isParentLayout) {
+                elements.push(this.lockTarget);
+            }
+            if (this.isParentLayout) {
+                const layoutItems = this.layoutManager.getItemsAndMain();
+                const layoutIndex = layoutItems.indexOf(this);
+                elements.push(...layoutItems.slice(layoutIndex));
+            }
+            if (!this.isModal && !elements.includes(this)) {
+                elements.push(this);
+            }
+            await Promise.all(elements.map((element) => stopAnimations(element)));
         };
         // 打开
         // 要区分是否首次渲染，首次渲染时不触发事件，不执行动画；非首次渲染，触发事件，执行动画
@@ -162,8 +168,8 @@ let NavigationDrawer = class NavigationDrawer extends LayoutItemBase {
                 overlay = this.overlayRef.value;
             }
             if (hasUpdated) {
-                const requestOpen = emit(this, 'open', { cancelable: true });
-                if (requestOpen.defaultPrevented) {
+                const eventProceeded = this.emit('open', { cancelable: true });
+                if (!eventProceeded) {
                     return;
                 }
             }
@@ -204,6 +210,7 @@ let NavigationDrawer = class NavigationDrawer extends LayoutItemBase {
             // 但首次渲染不执行动画
             if (this.isParentLayout && hasUpdated) {
                 setLayoutTransition(duration, easingEmphasized);
+                this.layoutManager.updateLayout(this);
             }
             // drawer 显示动画
             animations.push(animateTo(this.isModal ? panel : this, [
@@ -214,18 +221,21 @@ let NavigationDrawer = class NavigationDrawer extends LayoutItemBase {
                 easing: easingEmphasized,
             }));
             await Promise.all(animations);
+            if (!this.open) {
+                return;
+            }
             // 若位于 layout 中，则 drawer 动画完成后，移除 layout-main 的动画
             if (this.isParentLayout && hasUpdated) {
                 setLayoutTransition(null);
             }
             if (hasUpdated) {
-                emit(this, 'opened');
+                this.emit('opened');
             }
         }
         else if (this.hasUpdated) {
             // 关闭
-            const requestClose = emit(this, 'close', { cancelable: true });
-            if (requestClose.defaultPrevented) {
+            const eventProceeded = this.emit('close', { cancelable: true });
+            if (!eventProceeded) {
                 return;
             }
             await this.definedController.whenDefined();
@@ -259,6 +269,9 @@ let NavigationDrawer = class NavigationDrawer extends LayoutItemBase {
                 { transform: `translateX(${isRight ? '' : '-'}100%)` },
             ], { duration, easing: easingEmphasized }));
             await Promise.all(animations);
+            if (this.open) {
+                return;
+            }
             // 若位于 layout 中，则 drawer 动画结束后，移除 layout-main 的动画
             if (this.isParentLayout) {
                 setLayoutTransition(null);
@@ -267,12 +280,12 @@ let NavigationDrawer = class NavigationDrawer extends LayoutItemBase {
             if (this.isModal && !this.contained) {
                 unlockScreen(this, this.lockTarget);
             }
-            // 抽屉导航关闭后，恢复焦点到原有的元素上
+            // 抽屉栏关闭后，恢复焦点到原有的元素上
             const trigger = this.originalTrigger;
             if (isFunction(trigger?.focus)) {
                 setTimeout(() => trigger.focus());
             }
-            emit(this, 'closed');
+            this.emit('closed');
         }
     }
     connectedCallback() {
@@ -300,7 +313,7 @@ let NavigationDrawer = class NavigationDrawer extends LayoutItemBase {
         return html `${when(this.isModal, () => html `<div ${ref(this.overlayRef)} part="overlay" class="overlay" @click="${this.onOverlayClick}"></div>`)}<slot ${ref(this.panelRef)} part="panel" class="panel" tabindex="0"></slot>`;
     }
     onOverlayClick() {
-        emit(this, 'overlay-click');
+        this.emit('overlay-click');
         if (this.closeOnOverlayClick) {
             this.open = false;
         }

package/components/navigation-drawer/style.js

@@ -1,2 +1,2 @@
 import { css } from 'lit';
-export const style = css `:host{--shape-corner:var(--mdui-shape-corner-large);--z-index:2200;display:none;position:fixed;top:0;bottom:0;left:0;z-index:1;width:22.5rem}:host([placement=right]){left:initial;right:0}:host([mobile]),:host([modal]){top:0!important;right:0;bottom:0!important;width:initial;z-index:var(--z-index)}:host([placement=right][mobile]),:host([placement=right][modal]){left:0}:host([contained]){position:absolute}.overlay{position:absolute;inset:0;z-index:inherit;background-color:rgba(var(--mdui-color-scrim),.4)}.panel{display:block;position:absolute;top:0;bottom:0;left:0;width:100%;overflow:auto;z-index:inherit;background-color:rgb(var(--mdui-color-surface));box-shadow:var(--mdui-elevation-level0)}:host([mobile]) .panel,:host([modal]) .panel{border-radius:0 var(--shape-corner) var(--shape-corner) 0;width:22.5rem;background-color:rgb(var(--mdui-color-surface-container-low));box-shadow:var(--mdui-elevation-level1)}:host([placement=right]) .panel{left:initial;right:0}:host([placement=right][mobile]) .panel,:host([placement=right][modal]) .panel{border-radius:var(--shape-corner) 0 0 var(--shape-corner)}`;
+export const style = css `:host{--shape-corner:var(--mdui-shape-corner-large);--z-index:2200;display:none;position:fixed;top:0;bottom:0;left:0;z-index:1;width:22.5rem}:host([placement=right]){left:initial;right:0}:host([mobile]),:host([modal]){top:0!important;right:0;bottom:0!important;width:initial;z-index:var(--z-index)}:host([placement=right][mobile]),:host([placement=right][modal]){left:0}:host([contained]){position:absolute}.overlay{position:absolute;inset:0;z-index:inherit;background-color:rgba(var(--mdui-color-scrim),.4)}.panel{display:block;position:absolute;top:0;bottom:0;left:0;width:100%;overflow:auto;z-index:inherit;background-color:rgb(var(--mdui-color-surface));box-shadow:var(--mdui-elevation-level0)}:host([mobile]) .panel,:host([modal]) .panel{border-radius:0 var(--shape-corner) var(--shape-corner) 0;max-width:80%;width:22.5rem;background-color:rgb(var(--mdui-color-surface-container-low));box-shadow:var(--mdui-elevation-level1)}:host([placement=right]) .panel{left:initial;right:0}:host([placement=right][mobile]) .panel,:host([placement=right][modal]) .panel{border-radius:var(--shape-corner) 0 0 var(--shape-corner)}`;

package/components/navigation-rail/navigation-rail-item.d.ts

@@ -1,10 +1,10 @@
-import { LitElement } from 'lit';
+import { MduiElement } from '@mdui/shared/base/mdui-element.js';
 import '../icon.js';
 import type { Ripple } from '../ripple/index.js';
 import type { CSSResultGroup, TemplateResult } from 'lit';
-declare const NavigationRailItem_base: import("@open-wc/dedupe-mixin").Constructor<import("@mdui/shared/mixins/anchor.js").AnchorMixinInterface> & import("@open-wc/dedupe-mixin").Constructor<import("../ripple/ripple-mixin.js").RippleMixinInterface> & import("@open-wc/dedupe-mixin").Constructor<import("@mdui/shared/mixins/focusable.js").FocusableMixinInterface> & typeof LitElement;
+declare const NavigationRailItem_base: import("@open-wc/dedupe-mixin").Constructor<import("@mdui/shared/mixins/anchor.js").AnchorMixinInterface> & import("@open-wc/dedupe-mixin").Constructor<import("../ripple/ripple-mixin.js").RippleMixinInterface> & import("@open-wc/dedupe-mixin").Constructor<import("@mdui/shared/mixins/focusable.js").FocusableMixinInterface> & typeof MduiElement;
 /**
- * @summary 侧边导航栏项组件。需与 `<mdui-navigation-rail>` 组件配合使用
+ * @summary 侧边导航项组件。需配合 `<mdui-navigation-rail>` 组件使用
  *
  * ```html
  * <mdui-navigation-rail>
@@ -14,7 +14,7 @@ declare const NavigationRailItem_base: import("@open-wc/dedupe-mixin").Construct
  * </mdui-navigation-rail>
  * ```
  *
- * @slot - 文本
+ * @slot - 文本内容
  * @slot icon - 图标
  * @slot active-icon - 激活状态的图标
  * @slot badge - 徽标
@@ -27,18 +27,18 @@ declare const NavigationRailItem_base: import("@open-wc/dedupe-mixin").Construct
  * @csspart badge - 徽标
  * @csspart icon - 图标
  * @csspart active-icon - 激活状态的图标
- * @csspart label - 文本
+ * @csspart label - 文本内容
  *
- * @cssprop --shape-corner-indicator - 指示器的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner-indicator - 指示器的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
-export declare class NavigationRailItem extends NavigationRailItem_base {
+export declare class NavigationRailItem extends NavigationRailItem_base<NavigationRailItemEventMap> {
     static styles: CSSResultGroup;
     /**
-     * 未激活状态的 Material Icons 图标名。也可以通过 `slot="icon"` 设置
+     * 未激活状态下的 Material Icons 图标名。也可以通过 `slot="icon"` 设置
      */
     icon?: string;
     /**
-     * 激活状态的 Material Icons 图标名。也可以通过 `slot="active-icon"` 设置
+     * 激活状态下的 Material Icons 图标名。也可以通过 `slot="active-icon"` 设置
      */
     activeIcon?: string;
     /**
@@ -68,6 +68,10 @@ export declare class NavigationRailItem extends NavigationRailItem_base {
     protected render(): TemplateResult;
     private renderInner;
 }
+export interface NavigationRailItemEventMap {
+    focus: FocusEvent;
+    blur: FocusEvent;
+}
 declare global {
     interface HTMLElementTagNameMap {
         'mdui-navigation-rail-item': NavigationRailItem;

package/components/navigation-rail/navigation-rail-item.js

@@ -1,9 +1,10 @@
 import { __decorate } from "tslib";
-import { html, LitElement, nothing } from 'lit';
+import { html, nothing } from 'lit';
 import { customElement, property, state } from 'lit/decorators.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { createRef, ref } from 'lit/directives/ref.js';
 import cc from 'classcat';
+import { MduiElement } from '@mdui/shared/base/mdui-element.js';
 import { HasSlotController } from '@mdui/shared/controllers/has-slot.js';
 import { booleanConverter } from '@mdui/shared/helpers/decorator.js';
 import { nothingTemplate } from '@mdui/shared/helpers/template.js';
@@ -15,7 +16,7 @@ import '../icon.js';
 import { RippleMixin } from '../ripple/ripple-mixin.js';
 import { navigationRailItemStyle } from './navigation-rail-item-style.js';
 /**
- * @summary 侧边导航栏项组件。需与 `<mdui-navigation-rail>` 组件配合使用
+ * @summary 侧边导航项组件。需配合 `<mdui-navigation-rail>` 组件使用
  *
  * ```html
  * <mdui-navigation-rail>
@@ -25,7 +26,7 @@ import { navigationRailItemStyle } from './navigation-rail-item-style.js';
  * </mdui-navigation-rail>
  * ```
  *
- * @slot - 文本
+ * @slot - 文本内容
  * @slot icon - 图标
  * @slot active-icon - 激活状态的图标
  * @slot badge - 徽标
@@ -38,11 +39,11 @@ import { navigationRailItemStyle } from './navigation-rail-item-style.js';
  * @csspart badge - 徽标
  * @csspart icon - 图标
  * @csspart active-icon - 激活状态的图标
- * @csspart label - 文本
+ * @csspart label - 文本内容
  *
- * @cssprop --shape-corner-indicator - 指示器的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --shape-corner-indicator - 指示器的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
  */
-let NavigationRailItem = class NavigationRailItem extends AnchorMixin(RippleMixin(FocusableMixin(LitElement))) {
+let NavigationRailItem = class NavigationRailItem extends AnchorMixin(RippleMixin(FocusableMixin(MduiElement))) {
     constructor() {
         super(...arguments);
         /**

package/components/navigation-rail/navigation-rail.d.ts

@@ -4,7 +4,7 @@ import { LayoutItemBase } from '../layout/layout-item-base.js';
 import type { LayoutPlacement } from '../layout/helper.js';
 import type { CSSResultGroup, TemplateResult } from 'lit';
 /**
- * @summary 侧边导航栏组件。需与 `<mdui-navigation-rail-item>` 组件配合使用
+ * @summary 侧边导航栏组件。需配合 `<mdui-navigation-rail-item>` 组件使用
  *
  * ```html
  * <mdui-navigation-rail>
@@ -24,24 +24,24 @@ import type { CSSResultGroup, TemplateResult } from 'lit';
  * @csspart bottom - 底部元素的容器
  * @csspart items - `<mdui-navigation-rail-item>` 组件的容器
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
- * @cssprop --z-index - 组件的 CSS 的 `z-index` 值
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --z-index - 组件的 CSS `z-index` 值
  */
-export declare class NavigationRail extends LayoutItemBase {
+export declare class NavigationRail extends LayoutItemBase<NavigationRailEventMap> {
     static styles: CSSResultGroup;
     /**
      * 当前选中的 `<mdui-navigation-rail-item>` 的值
      */
     value?: string;
     /**
-     * 导航栏的位置。可选值为：
+     * 导航栏的位置。可选值包括：
      *
-     * * `left`：显示在左侧
-     * * `right`：显示在右侧
+     * * `left`：左侧
+     * * `right`：右侧
      */
-    placement: /*显示在左侧*/ 'left' | /*显示在右侧*/ 'right';
+    placement: /*左侧*/ 'left' | /*右侧*/ 'right';
     /**
-     * 导航栏中的 `<mdui-navigation-rail-item>` 元素的对齐方式。可选值为：
+     * `<mdui-navigation-rail-item>` 元素的对齐方式。可选值包括：
      *
      * * `start`：顶部对齐
      * * `center`：居中对齐
@@ -49,10 +49,9 @@ export declare class NavigationRail extends LayoutItemBase {
      */
     alignment: /*顶部对齐*/ 'start' | /*居中对齐*/ 'center' | /*底部对齐*/ 'end';
     /**
-     * 默认导航栏相对于 `body` 元素显示，该参数设置为 `true` 时，导航栏将相对于它的父元素显示
+     * 默认情况下，导航栏相对于 `body` 元素显示。当该参数设置为 `true` 时，导航栏将相对于其父元素显示。
      *
-     * Note:
-     * 设置了该属性时，必须手动在父元素上设置样式 `position: relative;`
+     * **Note**：设置该属性时，必须在父元素上手动设置样式 `position: relative;`。
      */
     contained: boolean;
     /**
@@ -79,6 +78,9 @@ export declare class NavigationRail extends LayoutItemBase {
     private updateItems;
     private onSlotChange;
 }
+export interface NavigationRailEventMap {
+    change: CustomEvent<void>;
+}
 declare global {
     interface HTMLElementTagNameMap {
         'mdui-navigation-rail': NavigationRail;

package/components/navigation-rail/navigation-rail.js

@@ -9,12 +9,11 @@ import { DefinedController } from '@mdui/shared/controllers/defined.js';
 import { HasSlotController } from '@mdui/shared/controllers/has-slot.js';
 import { watch } from '@mdui/shared/decorators/watch.js';
 import { booleanConverter } from '@mdui/shared/helpers/decorator.js';
-import { emit } from '@mdui/shared/helpers/event.js';
 import { componentStyle } from '@mdui/shared/lit-styles/component-style.js';
 import { LayoutItemBase } from '../layout/layout-item-base.js';
 import { navigationRailStyle } from './navigation-rail-style.js';
 /**
- * @summary 侧边导航栏组件。需与 `<mdui-navigation-rail-item>` 组件配合使用
+ * @summary 侧边导航栏组件。需配合 `<mdui-navigation-rail-item>` 组件使用
  *
  * ```html
  * <mdui-navigation-rail>
@@ -34,21 +33,21 @@ import { navigationRailStyle } from './navigation-rail-style.js';
  * @csspart bottom - 底部元素的容器
  * @csspart items - `<mdui-navigation-rail-item>` 组件的容器
  *
- * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐[引用设计令牌](/docs/2/styles/design-tokens#shape-corner)
- * @cssprop --z-index - 组件的 CSS 的 `z-index` 值
+ * @cssprop --shape-corner - 组件的圆角大小。可以指定一个具体的像素值；但更推荐引用[设计令牌](/docs/2/styles/design-tokens#shape-corner)
+ * @cssprop --z-index - 组件的 CSS `z-index` 值
  */
 let NavigationRail = class NavigationRail extends LayoutItemBase {
     constructor() {
         super(...arguments);
         /**
-         * 导航栏的位置。可选值为：
+         * 导航栏的位置。可选值包括：
          *
-         * * `left`：显示在左侧
-         * * `right`：显示在右侧
+         * * `left`：左侧
+         * * `right`：右侧
          */
         this.placement = 'left';
         /**
-         * 导航栏中的 `<mdui-navigation-rail-item>` 元素的对齐方式。可选值为：
+         * `<mdui-navigation-rail-item>` 元素的对齐方式。可选值包括：
          *
          * * `start`：顶部对齐
          * * `center`：居中对齐
@@ -56,10 +55,9 @@ let NavigationRail = class NavigationRail extends LayoutItemBase {
          */
         this.alignment = 'start';
         /**
-         * 默认导航栏相对于 `body` 元素显示，该参数设置为 `true` 时，导航栏将相对于它的父元素显示
+         * 默认情况下，导航栏相对于 `body` 元素显示。当该参数设置为 `true` 时，导航栏将相对于其父元素显示。
          *
-         * Note:
-         * 设置了该属性时，必须手动在父元素上设置样式 `position: relative;`
+         * **Note**：设置该属性时，必须在父元素上手动设置样式 `position: relative;`。
          */
         this.contained = false;
         /**
@@ -97,7 +95,7 @@ let NavigationRail = class NavigationRail extends LayoutItemBase {
         const item = this.items.find((item) => item.key === this.activeKey);
         this.value = item?.value;
         if (!this.isInitial) {
-            emit(this, 'change');
+            this.emit('change');
         }
     }
     async onValueChange() {
@@ -166,6 +164,9 @@ let NavigationRail = class NavigationRail extends LayoutItemBase {
         }
         const target = event.target;
         const item = target.closest('mdui-navigation-rail-item');
+        if (!item) {
+            return;
+        }
         this.activeKey = item.key;
         this.isInitial = false;
         this.updateItems();

package/components/radio/radio-group.d.ts

@@ -1,11 +1,11 @@
-import { LitElement } from 'lit';
 import '@mdui/jq/methods/closest.js';
 import '@mdui/jq/methods/find.js';
 import '@mdui/jq/methods/get.js';
+import { MduiElement } from '@mdui/shared/base/mdui-element.js';
 import type { FormControl } from '@mdui/jq/shared/form.js';
 import type { CSSResultGroup, TemplateResult } from 'lit';
 /**
- * @summary 单选框组组件。需与 `<mdui-radio>` 组件配合使用
+ * @summary 单选框组组件。需配合 `<mdui-radio>` 组件使用
  *
  * ```html
  * <mdui-radio-group value="chinese">
@@ -20,24 +20,24 @@ import type { CSSResultGroup, TemplateResult } from 'lit';
  *
  * @slot - `<mdui-radio>` 元素
  */
-export declare class RadioGroup extends LitElement implements FormControl {
+export declare class RadioGroup extends MduiElement<RadioGroupEventMap> implements FormControl {
     static styles: CSSResultGroup;
     /**
-     * 是否为禁用状态
+     * 是否禁用此组件
      */
     disabled: boolean;
     /**
-     * 关联的 `form` 元素。此属性值必须为同一页面中的一个 `<form>` 元素的 `id` 属性。
+     * 关联的 `<form>` 元素。此属性值应为同一页面中的一个 `<form>` 元素的 `id`。
      *
-     * 如果此属性未指定，则元素必须是 `form` 元素的后代。利用此属性，你可以将元素放置在页面中的任何位置，而不仅仅是作为 `form` 元素的后代。
+     * 如果未指定此属性，则该元素必须是 `<form>` 元素的子元素。通过此属性，你可以将元素放置在页面的任何位置，而不仅仅是 `<form>` 元素的子元素。
      */
     form?: string;
     /**
-     * 单选框名称，将与表单数据一起提交
+     * 单选框组的名称，将与表单数据一起提交
      */
     name: string;
     /**
-     * 单选框的值，将于表单数据一起提交
+     * 单选框组的名称，将于表单数据一起提交
      */
     value: string;
     /**
@@ -57,11 +57,11 @@ export declare class RadioGroup extends LitElement implements FormControl {
     private readonly formController;
     private readonly definedController;
     /**
-     * 表单验证状态对象
+     * 表单验证状态对象，具体参见 [`ValidityState`](https://developer.mozilla.org/zh-CN/docs/Web/API/ValidityState)
      */
     get validity(): ValidityState;
     /**
-     * 表单验证的错误提示信息
+     * 如果表单验证未通过，此属性将包含提示信息。如果验证通过，此属性将为空字符串
      */
     get validationMessage(): string;
     private get items();
@@ -69,19 +69,19 @@ export declare class RadioGroup extends LitElement implements FormControl {
     private onValueChange;
     private onInvalidChange;
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`
      */
     checkValidity(): boolean;
     /**
-     * 检查表单字段是否验证通过。若未通过则返回 `false`，并触发 `invalid` 事件；若验证通过，则返回 `true`。
+     * 检查表单字段是否通过验证。如果未通过，返回 `false` 并触发 `invalid` 事件；如果通过，返回 `true`。
      *
-     * 验证未通过时，还将在组件上显示未通过的提示。
+     * 如果验证未通过，还会在组件上显示验证失败的提示。
      */
     reportValidity(): boolean;
     /**
-     * 设置自定义的错误提示文本。只要文本不为空，则表示字段验证未通过
+     * 设置自定义的错误提示文本。只要这个文本不为空，就表示字段未通过验证
      *
-     * @param message 自定义的提示文本
+     * @param message 自定义的错误提示文本
      */
     setCustomValidity(message: string): void;
     protected render(): TemplateResult;
@@ -98,6 +98,11 @@ export declare class RadioGroup extends LitElement implements FormControl {
     private onCheckedChange;
     private updateItems;
 }
+export interface RadioGroupEventMap {
+    change: CustomEvent<void>;
+    input: CustomEvent<void>;
+    invalid: CustomEvent<void>;
+}
 declare global {
     interface HTMLElementTagNameMap {
         'mdui-radio-group': RadioGroup;