From d4346b670e2ee396c209d1c0fdb73fbb99245e57 Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Mon, 29 Jun 2026 19:43:30 -0700
Subject: [PATCH 01/12] feat(layout): add various layout demos including
 resizable aside, floating panels, and scrollable main content

---
 docs/.vitepress/themeConfig.ts              |   1 +
 docs/demos/layout/aside-collapse-effect.vue | 191 ++++++++++++
 docs/demos/layout/aside-modes.vue           | 143 +++++++++
 docs/demos/layout/aside-resizable.vue       | 106 +++++++
 docs/demos/layout/aside-slot-props.vue      | 197 +++++++++++++
 docs/demos/layout/basic.vue                 |  61 ++++
 docs/demos/layout/floating-panels.vue       | 170 +++++++++++
 docs/demos/layout/floating.vue              | 113 +++++++
 docs/demos/layout/main-scroll-bubble.vue    |  61 ++++
 docs/demos/layout/main-scroll-div.vue       |  56 ++++
 docs/demos/layout/main-scroll.vue           |  92 ++++++
 docs/src/components/layout.md               | 308 ++++++++++++++++++++
 12 files changed, 1499 insertions(+)
 create mode 100644 docs/demos/layout/aside-collapse-effect.vue
 create mode 100644 docs/demos/layout/aside-modes.vue
 create mode 100644 docs/demos/layout/aside-resizable.vue
 create mode 100644 docs/demos/layout/aside-slot-props.vue
 create mode 100644 docs/demos/layout/basic.vue
 create mode 100644 docs/demos/layout/floating-panels.vue
 create mode 100644 docs/demos/layout/floating.vue
 create mode 100644 docs/demos/layout/main-scroll-bubble.vue
 create mode 100644 docs/demos/layout/main-scroll-div.vue
 create mode 100644 docs/demos/layout/main-scroll.vue
 create mode 100644 docs/src/components/layout.md

diff --git a/docs/.vitepress/themeConfig.ts b/docs/.vitepress/themeConfig.ts
index 552102715..c60a727f0 100644
--- a/docs/.vitepress/themeConfig.ts
+++ b/docs/.vitepress/themeConfig.ts
@@ -15,6 +15,7 @@ const sharedSidebarItems = [
     base: '/components/',
     items: [
       { text: 'Container 容器', link: 'container' },
+      { text: 'Layout 布局', link: 'layout' },
       { text: 'Bubble 气泡', link: 'bubble' },
       { text: 'Sender 消息输入框', link: 'sender' },
       { text: 'Prompts 提示集', link: 'prompts' },
diff --git a/docs/demos/layout/aside-collapse-effect.vue b/docs/demos/layout/aside-collapse-effect.vue
new file mode 100644
index 000000000..28d3b902e
--- /dev/null
+++ b/docs/demos/layout/aside-collapse-effect.vue
@@ -0,0 +1,191 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+import { TinyRadio, TinyRadioGroup, TinySwitch } from '@opentiny/vue'
+import type { LayoutAsideCollapseEffect, LayoutAsideProps } from '@opentiny/tiny-robot'
+
+const collapseEffect = ref<LayoutAsideCollapseEffect>('overlay')
+const collapsedWidth = ref(72)
+const open = ref(true)
+
+const leftAside = computed<LayoutAsideProps>(() => ({
+  open: open.value,
+  expandedWidth: 176,
+  collapsedWidth: collapsedWidth.value,
+  collapseEffect: collapseEffect.value,
+}))
+
+const hint = computed(() =>
+  collapseEffect.value === 'overlay' ? '收起时更像把内容盖住，内容留在原位' : '收起时更像整块一起滑走',
+)
+
+const collapsedHint = computed(() =>
+  collapsedWidth.value === 0 ? '当前收起到 0，主要看收起过程。' : '当前会留一条窄栏，更容易看出两种结果的差别。',
+)
+</script>
+
+<template>
+  <div class="layout-collapse-effect-demo">
+    <div class="layout-collapse-effect-demo__controls">
+      <div class="layout-collapse-effect-demo__group">
+        <label class="layout-collapse-effect-demo__field">
+          <span>收起方式</span>
+          <tiny-radio-group v-model="collapseEffect">
+            <tiny-radio label="overlay">overlay</tiny-radio>
+            <tiny-radio label="slide">slide</tiny-radio>
+          </tiny-radio-group>
+        </label>
+
+        <label class="layout-collapse-effect-demo__field">
+          <span>展开</span>
+          <tiny-switch v-model="open"></tiny-switch>
+        </label>
+      </div>
+
+      <label class="layout-collapse-effect-demo__field layout-collapse-effect-demo__field--range">
+        <span class="layout-collapse-effect-demo__range-label">收起宽度</span>
+        <input
+          v-model.number="collapsedWidth"
+          class="layout-collapse-effect-demo__range"
+          type="range"
+          min="0"
+          max="120"
+          step="4"
+        />
+        <strong>{{ collapsedWidth }}px</strong>
+      </label>
+    </div>
+
+    <TrLayout class="layout-collapse-effect-demo__layout" :left-aside="leftAside">
+      <template #left-aside>
+        <div class="layout-collapse-effect-demo__aside">
+          <div class="layout-collapse-effect-demo__aside-rail" />
+          <div class="layout-collapse-effect-demo__aside-panel" />
+        </div>
+      </template>
+
+      <template #main>
+        <div class="layout-collapse-effect-demo__main">
+          <strong>{{ collapseEffect }}</strong>
+          <span>{{ hint }}</span>
+          <em>{{ collapsedHint }}</em>
+        </div>
+      </template>
+    </TrLayout>
+  </div>
+</template>
+
+<style>
+.layout-collapse-effect-demo__layout {
+  --layout-collapse-effect-demo-aside-bg: color-mix(
+    in srgb,
+    var(--vp-c-brand-1, var(--tr-color-primary, #5e7ce0)) 6%,
+    var(--vp-c-bg, #ffffff)
+  );
+  --layout-collapse-effect-demo-rail-bg: color-mix(in srgb, var(--vp-c-text-1, #1f2329) 4%, var(--vp-c-bg, #ffffff));
+  --layout-collapse-effect-demo-panel-bg: color-mix(
+    in srgb,
+    var(--vp-c-brand-1, var(--tr-color-primary, #5e7ce0)) 10%,
+    var(--vp-c-bg, #ffffff)
+  );
+  --tr-layout-height: 216px;
+  --tr-layout-main-min-width: 0;
+  --tr-layout-left-aside-bg: var(--layout-collapse-effect-demo-aside-bg);
+  --tr-layout-main-bg: var(--vp-c-bg, #ffffff);
+  overflow: hidden;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 12px;
+  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
+}
+</style>
+
+<style scoped>
+.layout-collapse-effect-demo {
+  display: grid;
+  gap: 12px;
+}
+
+.layout-collapse-effect-demo__controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  align-items: center;
+  justify-content: space-between;
+}
+
+.layout-collapse-effect-demo__group {
+  display: inline-flex;
+  align-items: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+
+.layout-collapse-effect-demo__field {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
+.layout-collapse-effect-demo__field--range {
+  min-width: min(320px, 100%);
+  flex: 1 1 280px;
+}
+
+.layout-collapse-effect-demo__range-label {
+  min-width: 60px;
+}
+
+.layout-collapse-effect-demo__range {
+  width: 100%;
+  min-width: 120px;
+}
+
+.layout-collapse-effect-demo__aside {
+  display: grid;
+  grid-template-columns: 48px minmax(0, 1fr);
+  gap: 10px;
+  box-sizing: border-box;
+  width: 176px;
+  height: 100%;
+  padding: 12px;
+  background: var(--layout-collapse-effect-demo-aside-bg);
+}
+
+.layout-collapse-effect-demo__aside-rail,
+.layout-collapse-effect-demo__aside-panel {
+  height: 100%;
+  border-radius: 12px;
+}
+
+.layout-collapse-effect-demo__aside-rail {
+  background: var(--layout-collapse-effect-demo-rail-bg);
+}
+
+.layout-collapse-effect-demo__aside-panel {
+  background: var(--layout-collapse-effect-demo-panel-bg);
+}
+
+.layout-collapse-effect-demo__main {
+  display: grid;
+  align-content: center;
+  justify-items: center;
+  gap: 8px;
+  height: 100%;
+  padding: 20px;
+  box-sizing: border-box;
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+  text-align: center;
+  background: var(--vp-c-bg, #ffffff);
+}
+
+.layout-collapse-effect-demo__main strong {
+  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
+  font-size: 14px;
+}
+
+.layout-collapse-effect-demo__main em {
+  font-style: normal;
+  font-size: 12px;
+}
+</style>
diff --git a/docs/demos/layout/aside-modes.vue b/docs/demos/layout/aside-modes.vue
new file mode 100644
index 000000000..78b9e411d
--- /dev/null
+++ b/docs/demos/layout/aside-modes.vue
@@ -0,0 +1,143 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+import type { LayoutAsideOpenDetail } from '@opentiny/tiny-robot'
+
+const leftOpen = ref(true)
+const rightOpen = ref(false)
+
+function updateLeftAside(detail: LayoutAsideOpenDetail) {
+  leftOpen.value = detail.open
+}
+
+function updateRightAside(detail: LayoutAsideOpenDetail) {
+  rightOpen.value = detail.open
+}
+</script>
+
+<template>
+  <div class="layout-aside-demo">
+    <TrLayout
+      :left-aside="{ open: leftOpen, expandedWidth: 156, collapsedWidth: 56 }"
+      :right-aside="{ mode: 'drawer', open: rightOpen }"
+      @left-aside-open-change="updateLeftAside"
+      @right-aside-open-change="updateRightAside"
+    >
+      <template #left-aside>
+        <div v-if="leftOpen" class="layout-aside-demo__aside">
+          <TrLayout.AsideToggle side="left" class="layout-aside-demo__chip">收起侧栏</TrLayout.AsideToggle>
+          <div class="layout-aside-demo__chip">collapsedWidth: 56px</div>
+        </div>
+        <div v-else class="layout-aside-demo__rail">
+          <TrLayout.AsideToggle side="left" class="layout-aside-demo__rail-chip">栏</TrLayout.AsideToggle>
+          <div class="layout-aside-demo__rail-chip">56</div>
+        </div>
+      </template>
+
+      <template #header>
+        <div class="layout-aside-demo__header">
+          <span>侧栏模式</span>
+          <button type="button" class="layout-aside-demo__chip" @click="rightOpen = true">打开抽屉</button>
+        </div>
+      </template>
+
+      <template #main>
+        <div class="layout-aside-demo__main">左侧是 `dock + collapsedWidth`，右侧是 `drawer`。</div>
+      </template>
+
+      <template #right-aside>
+        <div class="layout-aside-demo__drawer layout-aside-demo__drawer-panel">
+          <div>Drawer</div>
+          <div>点击遮罩、按 `Esc` 或按钮关闭。</div>
+          <TrLayout.AsideToggle side="right" class="layout-aside-demo__chip">关闭抽屉</TrLayout.AsideToggle>
+        </div>
+      </template>
+    </TrLayout>
+  </div>
+</template>
+
+<style scoped>
+.layout-aside-demo {
+  --tr-layout-height: 100%;
+  --tr-layout-left-aside-bg: var(--vp-c-bg-alt, #f8fafc);
+  --tr-layout-drawer-width: 240px;
+  height: 400px;
+  overflow: hidden;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 16px;
+  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
+}
+
+.layout-aside-demo__drawer-panel {
+  height: 100%;
+}
+
+.layout-aside-demo__header,
+.layout-aside-demo__main,
+.layout-aside-demo__drawer {
+  background: var(--vp-c-bg, #ffffff);
+}
+
+.layout-aside-demo__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-wrap: wrap;
+  gap: 8px;
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+}
+
+.layout-aside-demo__main,
+.layout-aside-demo__aside,
+.layout-aside-demo__drawer {
+  padding: 16px;
+  box-sizing: border-box;
+}
+
+.layout-aside-demo__aside,
+.layout-aside-demo__drawer,
+.layout-aside-demo__rail {
+  display: grid;
+  gap: 8px;
+}
+
+.layout-aside-demo__rail {
+  width: 56px;
+  height: 100%;
+  padding: 12px 8px;
+  box-sizing: border-box;
+  justify-items: center;
+}
+
+.layout-aside-demo__drawer {
+  min-height: 100%;
+}
+
+.layout-aside-demo__main,
+.layout-aside-demo__drawer {
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
+.layout-aside-demo__chip,
+.layout-aside-demo__rail-chip {
+  display: grid;
+  place-items: center;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  background: var(--vp-c-bg, #ffffff);
+  color: inherit;
+}
+
+.layout-aside-demo__chip {
+  min-height: 36px;
+  padding: 0 12px;
+  border-radius: 8px;
+}
+
+.layout-aside-demo__rail-chip {
+  width: 40px;
+  min-height: 40px;
+  padding: 0;
+  border-radius: 8px;
+}
+</style>
diff --git a/docs/demos/layout/aside-resizable.vue b/docs/demos/layout/aside-resizable.vue
new file mode 100644
index 000000000..6311094ab
--- /dev/null
+++ b/docs/demos/layout/aside-resizable.vue
@@ -0,0 +1,106 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+import type { LayoutAsideProps, LayoutAsideResizeDetail } from '@opentiny/tiny-robot'
+
+const minExpandedWidth = 160
+const maxExpandedWidth = 320
+const expandedWidth = ref(220)
+
+const leftAside = computed<LayoutAsideProps>(() => ({
+  defaultOpen: true,
+  expandedWidth: expandedWidth.value,
+  minExpandedWidth,
+  maxExpandedWidth,
+  resizable: true,
+}))
+
+function updateLeftAsideWidth(detail: LayoutAsideResizeDetail) {
+  expandedWidth.value = detail.expandedWidth
+}
+</script>
+
+<template>
+  <div class="layout-aside-resizable-demo">
+    <TrLayout :left-aside="leftAside" @left-aside-resize="updateLeftAsideWidth">
+      <template #left-aside>
+        <div class="layout-aside-resizable-demo__aside">
+          <strong>{{ expandedWidth }}px</strong>
+          <span>拖动右侧分隔线</span>
+        </div>
+      </template>
+
+      <template #main>
+        <div class="layout-aside-resizable-demo__main">
+          <div class="layout-aside-resizable-demo__metric">
+            <span>最小宽度</span>
+            <strong>{{ minExpandedWidth }}px</strong>
+          </div>
+          <div class="layout-aside-resizable-demo__metric">
+            <span>当前宽度</span>
+            <strong>{{ expandedWidth }}px</strong>
+          </div>
+          <div class="layout-aside-resizable-demo__metric">
+            <span>最大宽度</span>
+            <strong>{{ maxExpandedWidth }}px</strong>
+          </div>
+        </div>
+      </template>
+    </TrLayout>
+  </div>
+</template>
+
+<style scoped>
+.layout-aside-resizable-demo {
+  --tr-layout-height: 100%;
+  --tr-layout-main-min-width: 0;
+  --tr-layout-left-aside-bg: var(--vp-c-bg-alt, #f8fafc);
+  height: 400px;
+  overflow: hidden;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 16px;
+  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
+}
+
+.layout-aside-resizable-demo__aside {
+  display: grid;
+  place-items: center;
+  gap: 8px;
+  height: 100%;
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
+.layout-aside-resizable-demo__aside strong {
+  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
+}
+
+.layout-aside-resizable-demo__main {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+  align-content: center;
+  height: 100%;
+  padding: 16px;
+  box-sizing: border-box;
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
+.layout-aside-resizable-demo__metric {
+  display: grid;
+  gap: 6px;
+  padding: 12px;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 8px;
+  background: var(--vp-c-bg, #ffffff);
+}
+
+.layout-aside-resizable-demo__metric strong {
+  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
+}
+
+@media (max-width: 520px) {
+  .layout-aside-resizable-demo__main {
+    grid-template-columns: 1fr;
+  }
+}
+</style>
diff --git a/docs/demos/layout/aside-slot-props.vue b/docs/demos/layout/aside-slot-props.vue
new file mode 100644
index 000000000..5051291d7
--- /dev/null
+++ b/docs/demos/layout/aside-slot-props.vue
@@ -0,0 +1,197 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+import type { LayoutAsideProps, LayoutAsideOpenDetail, LayoutAsideResizeDetail } from '@opentiny/tiny-robot'
+
+const leftOpen = ref(true)
+const leftExpandedWidth = ref(220)
+const leftWidthMin = 160
+const leftWidthMax = 320
+const rightOpen = ref(false)
+
+const leftAside = computed<LayoutAsideProps>(() => ({
+  open: leftOpen.value,
+  expandedWidth: leftExpandedWidth.value,
+  collapsedWidth: 0,
+  minExpandedWidth: leftWidthMin,
+  maxExpandedWidth: leftWidthMax,
+  resizable: true,
+}))
+
+const rightAside = computed<LayoutAsideProps>(() => ({
+  mode: 'drawer',
+  open: rightOpen.value,
+}))
+
+function updateLeftAsideOpen(detail: LayoutAsideOpenDetail) {
+  leftOpen.value = detail.open
+}
+
+function updateLeftAsideWidth(detail: LayoutAsideResizeDetail) {
+  leftExpandedWidth.value = detail.expandedWidth
+}
+
+function updateRightAsideOpen(detail: LayoutAsideOpenDetail) {
+  rightOpen.value = detail.open
+}
+</script>
+
+<template>
+  <div class="layout-slot-props-demo">
+    <div class="layout-slot-props-demo__controls">
+      <div class="layout-slot-props-demo__group">
+        <span class="layout-slot-props-demo__group-label">左侧栏</span>
+        <button type="button" class="layout-slot-props-demo__button" @click="leftOpen = !leftOpen">
+          {{ leftOpen ? '收起侧栏' : '展开侧栏' }}
+        </button>
+        <label class="layout-slot-props-demo__range-wrap">
+          <span class="layout-slot-props-demo__range-label">宽度</span>
+          <input
+            v-model.number="leftExpandedWidth"
+            class="layout-slot-props-demo__range"
+            type="range"
+            :min="leftWidthMin"
+            :max="leftWidthMax"
+            step="4"
+            @input="leftOpen = true"
+          />
+          <strong>{{ leftExpandedWidth }}px</strong>
+        </label>
+      </div>
+
+      <div class="layout-slot-props-demo__group">
+        <span class="layout-slot-props-demo__group-label">右侧栏</span>
+        <button type="button" class="layout-slot-props-demo__button" @click="rightOpen = !rightOpen">
+          {{ rightOpen ? '关闭抽屉' : '打开抽屉' }}
+        </button>
+      </div>
+    </div>
+
+    <TrLayout
+      class="layout-slot-props-demo__layout"
+      :left-aside="leftAside"
+      :right-aside="rightAside"
+      @left-aside-open-change="updateLeftAsideOpen"
+      @left-aside-resize="updateLeftAsideWidth"
+      @right-aside-open-change="updateRightAsideOpen"
+    >
+      <template #left-aside>
+        <div v-if="leftOpen" class="layout-slot-props-demo__aside">
+          <p>左侧栏宽度：{{ leftExpandedWidth }}px</p>
+          <TrLayout.AsideToggle side="left" class="layout-slot-props-demo__button">
+            <template #default="{ isOpen }">
+              {{ isOpen ? '收起侧栏' : '展开侧栏' }}
+            </template>
+          </TrLayout.AsideToggle>
+        </div>
+
+        <div v-else class="layout-slot-props-demo__rail">
+          <TrLayout.AsideToggle side="left" class="layout-slot-props-demo__button">
+            <template #default="{ isOpen }">
+              {{ isOpen ? '收起' : '展开' }}
+            </template>
+          </TrLayout.AsideToggle>
+        </div>
+      </template>
+
+      <template #header>
+        <div class="layout-slot-props-demo__header">外层更新 leftAside / rightAside，并通过事件回写状态。</div>
+      </template>
+
+      <template #main>
+        <div class="layout-slot-props-demo__main">外层控制 open 和 expandedWidth，状态变化后通过事件回写。</div>
+      </template>
+
+      <template #right-aside>
+        <div class="layout-slot-props-demo__drawer">
+          <p>右侧抽屉</p>
+          <TrLayout.AsideToggle side="right" class="layout-slot-props-demo__button"> 关闭抽屉 </TrLayout.AsideToggle>
+        </div>
+      </template>
+    </TrLayout>
+  </div>
+</template>
+
+<style>
+.layout-slot-props-demo__layout {
+  --tr-layout-height: 360px;
+  overflow: hidden;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 16px;
+}
+</style>
+
+<style scoped>
+.layout-slot-props-demo {
+  display: grid;
+  gap: 12px;
+}
+
+.layout-slot-props-demo__controls {
+  display: grid;
+  gap: 8px;
+}
+
+.layout-slot-props-demo__group {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  align-items: center;
+}
+
+.layout-slot-props-demo__group-label {
+  font-weight: 600;
+}
+
+.layout-slot-props-demo__button {
+  min-height: 36px;
+  padding: 0 12px;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 8px;
+  background: var(--vp-c-bg, #ffffff);
+  cursor: pointer;
+}
+
+.layout-slot-props-demo__range-wrap {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.layout-slot-props-demo__range-label {
+  font-weight: 600;
+}
+
+.layout-slot-props-demo__range {
+  width: 180px;
+}
+
+.layout-slot-props-demo__header {
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+}
+
+.layout-slot-props-demo__aside,
+.layout-slot-props-demo__drawer,
+.layout-slot-props-demo__main {
+  display: grid;
+  align-content: start;
+  gap: 10px;
+  box-sizing: border-box;
+  height: 100%;
+  padding: 16px;
+  background: var(--vp-c-bg, #ffffff);
+}
+
+.layout-slot-props-demo__rail {
+  display: grid;
+  place-items: center;
+  height: 100%;
+}
+
+.layout-slot-props-demo__aside p,
+.layout-slot-props-demo__drawer p {
+  margin: 0;
+}
+</style>
diff --git a/docs/demos/layout/basic.vue b/docs/demos/layout/basic.vue
new file mode 100644
index 000000000..2b4af0607
--- /dev/null
+++ b/docs/demos/layout/basic.vue
@@ -0,0 +1,61 @@
+<script setup lang="ts">
+import { TrLayout } from '@opentiny/tiny-robot'
+</script>
+
+<template>
+  <div class="layout-basic-demo">
+    <TrLayout
+      :left-aside="{ defaultOpen: true, defaultExpandedWidth: 160 }"
+      :right-aside="{ defaultOpen: true, defaultExpandedWidth: 160 }"
+    >
+      <template #left-aside>
+        <div class="layout-basic-demo__aside">导航</div>
+      </template>
+
+      <template #header>
+        <div class="layout-basic-demo__header">Header</div>
+      </template>
+
+      <template #main>
+        <div class="layout-basic-demo__main">Main</div>
+      </template>
+
+      <template #footer>
+        <div class="layout-basic-demo__footer">Footer</div>
+      </template>
+
+      <template #right-aside>
+        <div class="layout-basic-demo__aside">信息栏</div>
+      </template>
+    </TrLayout>
+  </div>
+</template>
+
+<style scoped>
+.layout-basic-demo {
+  --tr-layout-height: 100%;
+  --tr-layout-main-min-width: 0;
+  --tr-layout-header-bg: var(--vp-c-bg-soft, #f6f8fa);
+  --tr-layout-main-bg: var(--vp-c-bg, #ffffff);
+  --tr-layout-footer-bg: var(--vp-c-bg-soft, #f6f8fa);
+  --tr-layout-left-aside-bg: var(--vp-c-bg-alt, #f8fafc);
+  --tr-layout-right-aside-bg: var(--vp-c-bg-alt, #f8fafc);
+  height: 400px;
+  overflow: hidden;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 16px;
+}
+
+.layout-basic-demo__header,
+.layout-basic-demo__footer {
+  padding: 12px 16px;
+  text-align: center;
+}
+
+.layout-basic-demo__main,
+.layout-basic-demo__aside {
+  display: grid;
+  place-items: center;
+  height: 100%;
+}
+</style>
diff --git a/docs/demos/layout/floating-panels.vue b/docs/demos/layout/floating-panels.vue
new file mode 100644
index 000000000..26d4bbb78
--- /dev/null
+++ b/docs/demos/layout/floating-panels.vue
@@ -0,0 +1,170 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+import type { LayoutAsideOpenDetail, LayoutFloatingOptions, LayoutFloatingState } from '@opentiny/tiny-robot'
+
+const open = ref(false)
+const leftOpen = ref(false)
+const rightOpen = ref(false)
+
+const defaultFloatingState: LayoutFloatingState = {
+  placement: 'top-right',
+  offsetX: 24,
+  offsetY: 32,
+  width: 560,
+  height: 420,
+}
+
+const floatingOptions: LayoutFloatingOptions = {
+  draggable: true,
+  resizable: true,
+  minWidth: 420,
+  maxWidth: 760,
+  minHeight: 320,
+}
+
+function updateLeftAside(detail: LayoutAsideOpenDetail) {
+  leftOpen.value = detail.open
+}
+
+function updateRightAside(detail: LayoutAsideOpenDetail) {
+  rightOpen.value = detail.open
+}
+</script>
+
+<template>
+  <div class="layout-floating-panels-demo">
+    <div class="layout-floating-panels-demo__toolbar">
+      <button type="button" class="layout-floating-panels-demo__button" @click="open = !open">
+        {{ open ? '关闭浮层' : '打开浮层' }}
+      </button>
+    </div>
+
+    <TrLayout
+      v-if="open"
+      class="layout-floating-panels-demo__layout"
+      mode="floating"
+      :default-floating-state="defaultFloatingState"
+      :floating-options="floatingOptions"
+      :left-aside="{ mode: 'drawer', open: leftOpen }"
+      :right-aside="{ mode: 'drawer', open: rightOpen }"
+      @left-aside-open-change="updateLeftAside"
+      @right-aside-open-change="updateRightAside"
+    >
+      <template #left-aside>
+        <div class="layout-floating-panels-demo__drawer">
+          <div class="layout-floating-panels-demo__drawer-title">左侧抽屉</div>
+          <div>适合放筛选、导航或补充信息。</div>
+          <TrLayout.AsideToggle side="left" class="layout-floating-panels-demo__chip">关闭抽屉</TrLayout.AsideToggle>
+        </div>
+      </template>
+
+      <template #header>
+        <div class="layout-floating-panels-demo__header">
+          <strong>浮层工作区</strong>
+          <div class="layout-floating-panels-demo__actions">
+            <button type="button" class="layout-floating-panels-demo__button" @click="leftOpen = true">
+              打开左抽屉
+            </button>
+            <button type="button" class="layout-floating-panels-demo__button" @click="rightOpen = true">
+              打开右抽屉
+            </button>
+          </div>
+        </div>
+      </template>
+
+      <template #main>
+        <div class="layout-floating-panels-demo__main">
+          <div class="layout-floating-panels-demo__card">左右两侧都使用 drawer，需要时再展开，不占主区宽度。</div>
+          <div class="layout-floating-panels-demo__card">整个浮层仍可拖拽、缩放，适合临时工作区或对话面板。</div>
+        </div>
+      </template>
+
+      <template #right-aside>
+        <div class="layout-floating-panels-demo__drawer">
+          <div class="layout-floating-panels-demo__drawer-title">右侧抽屉</div>
+          <div>点击遮罩、按 `Esc` 或按钮都可以关闭。</div>
+          <TrLayout.AsideToggle side="right" class="layout-floating-panels-demo__chip">关闭抽屉</TrLayout.AsideToggle>
+        </div>
+      </template>
+    </TrLayout>
+  </div>
+</template>
+
+<style>
+.layout-floating-panels-demo__layout {
+  --tr-layout-floating-radius: 16px;
+  --tr-layout-drawer-width: 240px;
+}
+</style>
+
+<style scoped>
+.layout-floating-panels-demo {
+  display: grid;
+  gap: 8px;
+}
+
+.layout-floating-panels-demo__toolbar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.layout-floating-panels-demo__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.layout-floating-panels-demo__button,
+.layout-floating-panels-demo__chip,
+.layout-floating-panels-demo__rail-chip {
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  background: var(--vp-c-bg, #ffffff);
+  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
+}
+
+.layout-floating-panels-demo__button,
+.layout-floating-panels-demo__chip {
+  min-height: 36px;
+  padding: 0 12px;
+  border-radius: 8px;
+  cursor: pointer;
+}
+
+.layout-floating-panels-demo__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 24px 16px;
+  background: var(--vp-c-bg, #ffffff);
+}
+
+.layout-floating-panels-demo__main,
+.layout-floating-panels-demo__drawer {
+  display: grid;
+  align-content: start;
+  gap: 12px;
+  padding: 16px;
+  box-sizing: border-box;
+  height: 100%;
+  background: var(--vp-c-bg, #ffffff);
+}
+
+.layout-floating-panels-demo__main {
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
+.layout-floating-panels-demo__card {
+  padding: 12px 14px;
+  border-radius: 12px;
+  background: var(--vp-c-bg-soft, #f6f8fa);
+}
+
+.layout-floating-panels-demo__drawer-title {
+  font-weight: 600;
+  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
+}
+</style>
diff --git a/docs/demos/layout/floating.vue b/docs/demos/layout/floating.vue
new file mode 100644
index 000000000..e85bfff6e
--- /dev/null
+++ b/docs/demos/layout/floating.vue
@@ -0,0 +1,113 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+import type { LayoutFloatingOptions, LayoutFloatingState } from '@opentiny/tiny-robot'
+
+const open = ref(false)
+
+const defaultFloatingState: LayoutFloatingState = {
+  placement: 'top-right',
+  offsetX: 24,
+  offsetY: 32,
+  width: 520,
+  height: 360,
+}
+
+const floatingOptions: LayoutFloatingOptions = {
+  draggable: true,
+  resizable: true,
+  minWidth: 360,
+  maxWidth: 680,
+}
+</script>
+
+<template>
+  <div class="layout-floating-demo">
+    <div class="layout-floating-demo__toolbar">
+      <button type="button" class="layout-floating-demo__trigger" @click="open = !open">
+        {{ open ? '关闭浮层' : '打开浮层' }}
+      </button>
+      <span class="layout-floating-demo__tip">拖动顶部横条或边缘手柄调整位置和大小。</span>
+    </div>
+
+    <TrLayout
+      v-if="open"
+      class="layout-floating-demo__layout"
+      mode="floating"
+      :default-floating-state="defaultFloatingState"
+      :floating-options="floatingOptions"
+    >
+      <template #header>
+        <div class="layout-floating-demo__header">
+          <strong>浮层布局</strong>
+          <button type="button" class="layout-floating-demo__close" @click="open = false">关闭</button>
+        </div>
+      </template>
+
+      <template #main>
+        <div class="layout-floating-demo__main">
+          <div class="layout-floating-demo__card">`defaultFloatingState` 设置初始位置和大小。</div>
+          <div class="layout-floating-demo__card">`floatingOptions` 控制拖动、缩放和尺寸范围。</div>
+        </div>
+      </template>
+    </TrLayout>
+  </div>
+</template>
+
+<style>
+.layout-floating-demo__layout {
+  --tr-layout-floating-radius: 12px;
+}
+</style>
+
+<style scoped>
+.layout-floating-demo {
+  display: grid;
+  gap: 8px;
+}
+
+.layout-floating-demo__toolbar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.layout-floating-demo__trigger,
+.layout-floating-demo__close {
+  height: 36px;
+  padding: 0 12px;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 8px;
+  background: var(--vp-c-bg, #ffffff);
+  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
+  cursor: pointer;
+}
+
+.layout-floating-demo__tip {
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
+.layout-floating-demo__main {
+  display: grid;
+  gap: 12px;
+  padding: 16px;
+}
+
+.layout-floating-demo__card {
+  padding: 12px 14px;
+  border-radius: 12px;
+  background: var(--vp-c-bg-soft, #f6f8fa);
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
+.layout-floating-demo__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
+}
+</style>
diff --git a/docs/demos/layout/main-scroll-bubble.vue b/docs/demos/layout/main-scroll-bubble.vue
new file mode 100644
index 000000000..f0219e49c
--- /dev/null
+++ b/docs/demos/layout/main-scroll-bubble.vue
@@ -0,0 +1,61 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { BubbleList, TrLayout } from '@opentiny/tiny-robot'
+import type { BubbleListProps, BubbleRoleConfig, LayoutScrollTarget } from '@opentiny/tiny-robot'
+
+const props = defineProps<{
+  centered: boolean
+}>()
+
+const scrollTargetRef = ref<LayoutScrollTarget>(null)
+
+const roles: Record<string, BubbleRoleConfig> = {
+  user: { placement: 'end' },
+  assistant: { placement: 'start' },
+}
+
+const messages: BubbleListProps['messages'] = Array.from({ length: 12 }, (_, index) => [
+  {
+    role: 'user',
+    content: `第 ${index + 1} 轮：帮我整理一下当前布局的滚动区。`,
+  },
+  {
+    role: 'assistant',
+    content: '可以。内容区可以居中显示，滚动条仍然贴着 Layout 主区右侧。',
+  },
+]).flat()
+</script>
+
+<template>
+  <TrLayout>
+    <template #main>
+      <BubbleList
+        ref="scrollTargetRef"
+        class="layout-main-scroll-bubble"
+        :class="{ 'is-centered': props.centered }"
+        :messages="messages"
+        :role-configs="roles"
+      />
+      <TrLayout.ProxyScrollbar :scroll-target="scrollTargetRef" />
+    </template>
+  </TrLayout>
+</template>
+
+<style scoped>
+.layout-main-scroll-bubble {
+  --tr-bubble-list-padding: 16px;
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+  overflow: auto;
+}
+
+.layout-main-scroll-bubble.is-centered {
+  max-width: 450px;
+  margin: 0 auto;
+}
+
+:deep([data-role='user']) {
+  --tr-bubble-box-bg: var(--tr-color-primary-light);
+}
+</style>
diff --git a/docs/demos/layout/main-scroll-div.vue b/docs/demos/layout/main-scroll-div.vue
new file mode 100644
index 000000000..2698c7ebf
--- /dev/null
+++ b/docs/demos/layout/main-scroll-div.vue
@@ -0,0 +1,56 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+import type { LayoutScrollTarget } from '@opentiny/tiny-robot'
+
+const props = defineProps<{
+  centered: boolean
+}>()
+
+const scrollTargetRef = ref<LayoutScrollTarget>(null)
+
+const sections = Array.from({ length: 12 }, (_, index) => index + 1)
+</script>
+
+<template>
+  <TrLayout>
+    <template #main>
+      <div ref="scrollTargetRef" class="layout-main-scroll-div" :class="{ 'is-centered': props.centered }">
+        <section v-for="section in sections" :key="section" class="layout-main-scroll-div__item">
+          <strong>Section {{ section }}</strong>
+          <p>普通内容区也可以把滚动容器交给 Layout.ProxyScrollbar。</p>
+        </section>
+      </div>
+      <TrLayout.ProxyScrollbar :scroll-target="scrollTargetRef" />
+    </template>
+  </TrLayout>
+</template>
+
+<style scoped>
+.layout-main-scroll-div {
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+  display: grid;
+  gap: 12px;
+  padding: 16px;
+  overflow: auto;
+}
+
+.layout-main-scroll-div.is-centered {
+  max-width: 550px;
+  margin: 0 auto;
+}
+
+.layout-main-scroll-div__item {
+  padding: 16px;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 12px;
+  background: var(--vp-c-bg, #ffffff);
+}
+
+.layout-main-scroll-div__item p {
+  margin: 8px 0 0;
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+</style>
diff --git a/docs/demos/layout/main-scroll.vue b/docs/demos/layout/main-scroll.vue
new file mode 100644
index 000000000..9df127122
--- /dev/null
+++ b/docs/demos/layout/main-scroll.vue
@@ -0,0 +1,92 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TinySwitch } from '@opentiny/vue'
+import MainScrollBubble from './main-scroll-bubble.vue'
+import MainScrollDiv from './main-scroll-div.vue'
+
+const activeExample = ref<'bubble' | 'div'>('bubble')
+const isCentered = ref(true)
+</script>
+
+<template>
+  <div class="layout-main-scroll-demo">
+    <div class="layout-main-scroll-demo__toolbar">
+      <div class="layout-main-scroll-demo__switcher" aria-label="主区滚动示例切换">
+        <button
+          type="button"
+          class="layout-main-scroll-demo__switch"
+          :class="{ 'is-active': activeExample === 'bubble' }"
+          :aria-pressed="activeExample === 'bubble'"
+          @click="activeExample = 'bubble'"
+        >
+          BubbleList
+        </button>
+
+        <button
+          type="button"
+          class="layout-main-scroll-demo__switch"
+          :class="{ 'is-active': activeExample === 'div' }"
+          :aria-pressed="activeExample === 'div'"
+          @click="activeExample = 'div'"
+        >
+          普通 div
+        </button>
+      </div>
+
+      <label class="layout-main-scroll-demo__field">
+        <span>内容居中</span>
+        <tiny-switch v-model="isCentered"></tiny-switch>
+      </label>
+    </div>
+
+    <div class="layout-main-scroll-demo__stage">
+      <MainScrollBubble v-if="activeExample === 'bubble'" :centered="isCentered" />
+      <MainScrollDiv v-else :centered="isCentered" />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.layout-main-scroll-demo {
+  display: grid;
+  gap: 12px;
+}
+
+.layout-main-scroll-demo__toolbar {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+.layout-main-scroll-demo__switcher {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.layout-main-scroll-demo__field {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
+.layout-main-scroll-demo__switch {
+  height: 34px;
+  padding: 0 12px;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 8px;
+  background: var(--vp-c-bg, #ffffff);
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+  cursor: pointer;
+}
+
+.layout-main-scroll-demo__switch.is-active {
+  border-color: var(--vp-c-brand-1, var(--tr-color-primary, #5e7ce0));
+  color: var(--vp-c-brand-1, var(--tr-color-primary, #5e7ce0));
+}
+
+.layout-main-scroll-demo__stage {
+  --tr-layout-height: 400px;
+}
+</style>
diff --git a/docs/src/components/layout.md b/docs/src/components/layout.md
new file mode 100644
index 000000000..79434c3e3
--- /dev/null
+++ b/docs/src/components/layout.md
@@ -0,0 +1,308 @@
+---
+outline: [1, 3]
+---
+
+# Layout 布局
+
+`Layout` 用来组织带有头部、主内容区、底部和左右侧栏的页面。
+
+它覆盖三类核心场景：
+
+- 标准页面骨架
+- 可收起的左右侧栏
+- 可拖动、可缩放的浮层布局
+
+## 基础布局
+
+`Layout` 用于定义页面结构，区域中的具体内容可按需配置。
+
+<demo vue="../../demos/layout/basic.vue" title="基础布局" description="最小布局示例。" />
+
+## 侧栏
+
+### 展示形态
+
+用 `leftAside` / `rightAside` 配置侧栏。
+
+- `dock`：占据页面空间
+- `drawer`：覆盖在内容上方
+
+`drawer` 的宽度优先通过 `--tr-layout-drawer-width` 控制，未设置时回退到侧栏展开宽度。
+
+<demo vue="../../demos/layout/aside-modes.vue" title="显示模式" description="左侧占据页面空间，右侧覆盖在内容上方。" />
+
+### 收起行为
+
+`collapsedWidth` 控制收起后还保留多少宽度，`collapseEffect` 控制收起时的动画效果。
+
+- `collapsedWidth > 0`：收起后保留一条窄栏
+- `collapsedWidth = 0`：收起后完全隐藏
+- `overlay`：内容留在原位
+- `slide`：内容跟着一起移动
+
+<demo
+  vue="../../demos/layout/aside-collapse-effect.vue"
+  title="收起行为"
+  description="对比 overlay 和 slide 两种收起动画。"
+/>
+
+### 状态控制
+
+用 `leftAside` / `rightAside` 控制开关和宽度。
+
+侧栏内容通过 `left-aside` / `right-aside` 提供。
+
+受控用法下，状态变化后需要同步回写。侧栏内部切换可使用 `Layout.AsideToggle`，默认插槽提供 `{ isOpen }`。
+
+<demo
+  vue="../../demos/layout/aside-slot-props.vue"
+  title="状态控制"
+  description="用开关和滑块展示 leftAside、rightAside 和事件同步。"
+/>
+
+### 宽度调整
+
+`resizable` 可以开启 `dock` 侧栏的拖拽改宽，宽度范围由 `minExpandedWidth` 和 `maxExpandedWidth` 控制。
+
+<demo vue="../../demos/layout/aside-resizable.vue" title="宽度调整" description="拖动分隔线查看当前宽度和边界。" />
+
+## 主区滚动
+
+`Layout.ProxyScrollbar` 用来显示主区滚动条，`scrollTarget` 指向实际滚动的内容区域。
+
+> 适合消息区居中的对话页：内容可以居中，滚动条仍固定在主区右侧，视觉更整齐。
+
+- `scrollTarget` 传实际滚动元素，或对应组件实例的 `ref`
+- 该元素需自行设置尺寸、`box-sizing` 和滚动样式
+- `Layout.ProxyScrollbar` 会自动隐藏该元素的原生滚动条
+
+```css
+.scroll-host {
+  width: 100%;
+  height: 100%;
+  box-sizing: border-box;
+  overflow: auto;
+}
+```
+
+<demo
+  vue="../../demos/layout/main-scroll.vue"
+  :vueFiles="[
+    '../../demos/layout/main-scroll.vue',
+    '../../demos/layout/main-scroll-bubble.vue',
+    '../../demos/layout/main-scroll-div.vue'
+  ]"
+  title="主区滚动"
+  description="演示内容区居中后，滚动条仍固定在主区右侧。"
+/>
+
+## 浮层
+
+适合临时面板或悬浮工作区，只在 `mode="floating"` 时生效。
+
+### 基本用法
+
+`defaultFloatingState` 设置初始位置和大小，`floatingOptions` 设置拖动、缩放和尺寸范围。
+
+- `defaultFloatingState`：只设置初始值
+- `floatingState`：由外部控制位置和大小
+
+传 `floatingState` 时，需要在 `update:floatingState` 中同步最新值。
+
+<demo
+  vue="../../demos/layout/floating.vue"
+  title="基本用法"
+  description="打开时通过 defaultFloatingState 设置初始位置和大小。"
+/>
+
+### 浮层工作区
+
+浮层里同样可以放入侧栏、头部和主区。常见用法是把左右两侧都做成按需展开的 drawer。
+
+<demo
+  vue="../../demos/layout/floating-panels.vue"
+  title="浮层工作区"
+  description="在浮层里组合左右 drawer，适合临时工作区、对话面板或侧边操作台。"
+/>
+
+## Props
+
+### Layout {#layout-props}
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| ------ | ---- | ---- | ------ |
+| `mode` | 布局模式；`normal` 参与普通布局，`floating` 会脱离普通布局，不占原来的位置空间 | `'normal' \| 'floating'` | `'normal'` |
+| `leftAside` | 左侧栏配置 | [`LayoutAsideProps`](#layout-aside-props) | `-` |
+| `rightAside` | 右侧栏配置 | [`LayoutAsideProps`](#layout-aside-props) | `-` |
+| `floatingState` | 受控浮层状态，需配合 `update:floatingState` 回写 | [`LayoutFloatingState`](#layout-floating-state) | `-` |
+| `defaultFloatingState` | 非受控浮层初始状态，仅首次挂载读取一次 | [`LayoutFloatingState`](#layout-floating-state) | `-` |
+| `floatingOptions` | 浮层拖拽、缩放和尺寸约束配置 | [`LayoutFloatingOptions`](#layout-floating-options) | `-` |
+
+### Layout.ProxyScrollbar {#layout-proxy-scrollbar-props}
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| ------ | ---- | ---- | ------ |
+| `scrollTarget` | 真实滚动容器的元素，或对应组件实例的 ref | [`LayoutScrollTarget`](#layout-scroll-target) | `-` |
+
+### Layout.AsideToggle {#layout-aside-toggle-props}
+
+| 属性名 | 说明 | 类型 | 默认值 |
+| ------ | ---- | ---- | ------ |
+| `side` | 控制的侧栏位置 | `'left' \| 'right'` | `-` |
+
+它是一个现成的开关按钮，只能在 `Layout` 内部使用，通常放在 `left-aside` / `right-aside` 插槽中。
+
+## Slots
+
+### Layout {#layout-slots}
+
+| 插槽名 | 说明 | 作用域参数 |
+| ------ | ---- | ---------- |
+| `left-aside` | 左侧栏内容 | `-` |
+| `header` | 顶部区域 | `-` |
+| `main` | 主区内容 | `-` |
+| `footer` | 底部区域 | `-` |
+| `right-aside` | 右侧栏内容 | `-` |
+
+### Layout.AsideToggle
+
+| 插槽名 | 说明 | 作用域参数 |
+| ------ | ---- | ---------- |
+| `default` | 自定义切换按钮内容 | `{ isOpen: boolean }` |
+
+## Events
+
+### Layout {#layout-layout-events}
+
+| 事件名 | 说明 | 回调参数 |
+| ------ | ---- | -------- |
+| `update:floatingState` | 浮层位置或尺寸变化 | (value: [`LayoutFloatingState`](#layout-floating-state)) |
+| `aside-open-change` | 侧栏开关变化 | (detail: [`LayoutAsideOpenDetail`](#layout-aside-open-detail)) |
+| `left-aside-open-change` | 左侧栏开关变化 | (detail: [`LayoutAsideOpenValue`](#layout-aside-open-value)) |
+| `right-aside-open-change` | 右侧栏开关变化 | (detail: [`LayoutAsideOpenValue`](#layout-aside-open-value)) |
+| `aside-resize-start` | 开始调整侧栏宽度 | (detail: [`LayoutAsideResizeDetail`](#layout-aside-resize-detail)) |
+| `aside-resize` | 调整侧栏宽度时持续触发 | (detail: [`LayoutAsideResizeDetail`](#layout-aside-resize-detail)) |
+| `aside-resize-end` | 结束调整侧栏宽度 | (detail: [`LayoutAsideResizeDetail`](#layout-aside-resize-detail)) |
+| `left-aside-resize-start` | 开始调整左侧栏宽度 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
+| `left-aside-resize` | 调整左侧栏宽度时持续触发 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
+| `left-aside-resize-end` | 结束调整左侧栏宽度 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
+| `right-aside-resize-start` | 开始调整右侧栏宽度 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
+| `right-aside-resize` | 调整右侧栏宽度时持续触发 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
+| `right-aside-resize-end` | 结束调整右侧栏宽度 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
+| `floating-drag-start` | 开始拖动浮层 | (detail: [`LayoutFloatingDragDetail`](#layout-floating-drag-detail)) |
+| `floating-drag` | 拖动浮层时持续触发 | (detail: [`LayoutFloatingDragDetail`](#layout-floating-drag-detail)) |
+| `floating-drag-end` | 结束拖动浮层 | (detail: [`LayoutFloatingDragDetail`](#layout-floating-drag-detail)) |
+| `floating-resize-start` | 开始调整浮层尺寸 | (detail: [`LayoutFloatingResizeDetail`](#layout-floating-resize-detail)) |
+| `floating-resize` | 调整浮层尺寸时持续触发 | (detail: [`LayoutFloatingResizeDetail`](#layout-floating-resize-detail)) |
+| `floating-resize-end` | 结束调整浮层尺寸 | (detail: [`LayoutFloatingResizeDetail`](#layout-floating-resize-detail)) |
+
+## Types {#types}
+
+### LayoutAsideProps {#layout-aside-props}
+
+| 字段 | 说明 | 类型 | 默认值 |
+| ---- | ---- | ---- | ------ |
+| `mode` | 侧栏模式 | `'dock' \| 'drawer'` | `'dock'` |
+| `open` | 受控开关状态 | `boolean` | `-` |
+| `defaultOpen` | 非受控初始开关状态 | `boolean` | `left: true` / `right: false` |
+| `expandedWidth` | 受控展开宽度；`drawer` 未设置 `--tr-layout-drawer-width` 时会回退使用该宽度 | `number` | `-` |
+| `defaultExpandedWidth` | 非受控初始展开宽度；`drawer` 宽度回退值 | `number` | `left: 300` / `right: 320` |
+| `minExpandedWidth` | 最小展开宽度边界 | `number` | `left: 200` / `right: 240` |
+| `maxExpandedWidth` | 最大展开宽度边界 | `number` | `left: 560` / `right: 640` |
+| `collapsedWidth` | 收起后保留的窄栏宽度，仅 `dock` 生效 | `number` | `0` |
+| `collapseEffect` | `dock` 收起到窄栏时的内容动画 | `'overlay' \| 'slide'` | `'overlay'` |
+| `resizable` | 是否允许拖拽改宽，仅 `dock` 生效 | `boolean` | `false` |
+
+### LayoutAsideOpenDetail {#layout-aside-open-detail}
+
+| 字段 | 说明 | 类型 |
+| ---- | ---- | ---- |
+| `side` | 当前侧栏位置 | `'left' \| 'right'` |
+| `open` | 当前是否展开 | `boolean` |
+
+### LayoutAsideOpenValue {#layout-aside-open-value}
+
+| 字段 | 说明 | 类型 |
+| ---- | ---- | ---- |
+| `open` | 当前是否展开 | `boolean` |
+
+### LayoutAsideResizeDetail {#layout-aside-resize-detail}
+
+| 字段 | 说明 | 类型 |
+| ---- | ---- | ---- |
+| `side` | 当前侧栏位置 | `'left' \| 'right'` |
+| `expandedWidth` | 当前侧栏宽度 | `number` |
+
+### LayoutAsideResizeValue {#layout-aside-resize-value}
+
+| 字段 | 说明 | 类型 |
+| ---- | ---- | ---- |
+| `expandedWidth` | 当前侧栏宽度 | `number` |
+
+### LayoutScrollTarget {#layout-scroll-target}
+
+`HTMLElement | Pick<ComponentPublicInstance, '$el'> | null | undefined`
+
+### LayoutFloatingState {#layout-floating-state}
+
+| 字段 | 说明 | 类型 | 默认值 |
+| ---- | ---- | ---- | ------ |
+| `placement` | 浮层位置 | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' \| 'center'` | `'center'` |
+| `offsetX` | 横向偏移；`placement` 为 `center` 时不生效 | `number` | `24` |
+| `offsetY` | 纵向偏移；`placement` 为 `center` 时不生效 | `number` | `24` |
+| `width` | 浮层宽度；非受控时表示初始值，受控时表示当前值 | `number` | `420` |
+| `height` | 浮层高度；非受控时表示初始值，受控时表示当前值 | `number` | `560` |
+
+### LayoutFloatingOptions {#layout-floating-options}
+
+| 字段 | 说明 | 类型 | 默认值 |
+| ---- | ---- | ---- | ------ |
+| `draggable` | 是否允许拖动浮层 | `boolean` | `true` |
+| `resizable` | 是否允许通过浮层边缘手柄调整尺寸 | `boolean` | `false` |
+| `minWidth` | 最小宽度 | `number` | `320` |
+| `maxWidth` | 最大宽度 | `number` | `视口宽度` |
+| `minHeight` | 最小高度 | `number` | `240` |
+| `maxHeight` | 最大高度 | `number` | `视口高度` |
+
+### LayoutFloatingDragDetail {#layout-floating-drag-detail}
+
+与 [`LayoutFloatingState`](#layout-floating-state) 一致。
+
+### LayoutFloatingResizeDetail {#layout-floating-resize-detail}
+
+在 [`LayoutFloatingState`](#layout-floating-state) 基础上增加以下字段：
+
+| 字段 | 说明 | 类型 |
+| ---- | ---- | ---- |
+| `handle` | 当前拖动的边或角 | `'s' \| 'e' \| 'w' \| 'ne' \| 'nw' \| 'se' \| 'sw'` |
+
+## CSS 变量
+
+### 布局基础 {#layout-css-basics}
+
+| 变量名 | 说明 |
+| ------ | ---- |
+| `--tr-layout-height` | 布局高度 |
+| `--tr-layout-bg` | 容器背景 |
+| `--tr-layout-left-aside-bg` | 左侧栏背景 |
+| `--tr-layout-right-aside-bg` | 右侧栏背景 |
+| `--tr-layout-header-bg` | 顶部背景 |
+| `--tr-layout-main-bg` | 主区背景 |
+| `--tr-layout-footer-bg` | 底部背景 |
+| `--tr-layout-divider-color` | 分隔线颜色 |
+| `--tr-layout-overlay-bg` | drawer 遮罩颜色 |
+| `--tr-layout-panel-shadow` | drawer 阴影 |
+| `--tr-layout-floating-radius` | 浮层圆角 |
+| `--tr-layout-floating-shadow` | 浮层阴影 |
+| `--tr-layout-floating-z-index` | 浮层层级 |
+
+### 内容与交互 {#layout-css-content}
+
+| 变量名 | 说明 |
+| ------ | ---- |
+| `--tr-layout-main-min-width` | 主区最小宽度 |
+| `--tr-layout-drawer-width` | drawer 展示宽度 |
+| `--tr-layout-main-scrollbar-width` | 滚动条宽度 |
+| `--tr-layout-main-scrollbar-thumb-bg` | 滚动条滑块颜色 |
+| `--tr-layout-main-scrollbar-thumb-bg-hover` | 滑块悬停颜色 |
+| `--tr-layout-main-scrollbar-thumb-bg-active` | 滑块激活颜色 |

From 6f9aac558bb95160efdfd6d3610a902bbe08a515 Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Mon, 29 Jun 2026 21:26:04 -0700
Subject: [PATCH 02/12] fix: review suggestions

---
 docs/demos/layout/aside-modes.vue      |  6 +++---
 docs/demos/layout/aside-resizable.vue  |  4 ++--
 docs/demos/layout/aside-slot-props.vue | 22 ++++------------------
 docs/demos/layout/floating-panels.vue  |  6 +++---
 4 files changed, 12 insertions(+), 26 deletions(-)

diff --git a/docs/demos/layout/aside-modes.vue b/docs/demos/layout/aside-modes.vue
index 78b9e411d..960c7a1e7 100644
--- a/docs/demos/layout/aside-modes.vue
+++ b/docs/demos/layout/aside-modes.vue
@@ -1,16 +1,16 @@
 <script setup lang="ts">
 import { ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
-import type { LayoutAsideOpenDetail } from '@opentiny/tiny-robot'
+import type { LayoutAsideOpenValue } from '@opentiny/tiny-robot'
 
 const leftOpen = ref(true)
 const rightOpen = ref(false)
 
-function updateLeftAside(detail: LayoutAsideOpenDetail) {
+function updateLeftAside(detail: LayoutAsideOpenValue) {
   leftOpen.value = detail.open
 }
 
-function updateRightAside(detail: LayoutAsideOpenDetail) {
+function updateRightAside(detail: LayoutAsideOpenValue) {
   rightOpen.value = detail.open
 }
 </script>
diff --git a/docs/demos/layout/aside-resizable.vue b/docs/demos/layout/aside-resizable.vue
index 6311094ab..06c8c38d9 100644
--- a/docs/demos/layout/aside-resizable.vue
+++ b/docs/demos/layout/aside-resizable.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
-import type { LayoutAsideProps, LayoutAsideResizeDetail } from '@opentiny/tiny-robot'
+import type { LayoutAsideProps, LayoutAsideResizeValue } from '@opentiny/tiny-robot'
 
 const minExpandedWidth = 160
 const maxExpandedWidth = 320
@@ -15,7 +15,7 @@ const leftAside = computed<LayoutAsideProps>(() => ({
   resizable: true,
 }))
 
-function updateLeftAsideWidth(detail: LayoutAsideResizeDetail) {
+function updateLeftAsideWidth(detail: LayoutAsideResizeValue) {
   expandedWidth.value = detail.expandedWidth
 }
 </script>
diff --git a/docs/demos/layout/aside-slot-props.vue b/docs/demos/layout/aside-slot-props.vue
index 5051291d7..6658a71b4 100644
--- a/docs/demos/layout/aside-slot-props.vue
+++ b/docs/demos/layout/aside-slot-props.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
-import type { LayoutAsideProps, LayoutAsideOpenDetail, LayoutAsideResizeDetail } from '@opentiny/tiny-robot'
+import type { LayoutAsideProps, LayoutAsideOpenValue, LayoutAsideResizeValue } from '@opentiny/tiny-robot'
 
 const leftOpen = ref(true)
 const leftExpandedWidth = ref(220)
@@ -23,15 +23,15 @@ const rightAside = computed<LayoutAsideProps>(() => ({
   open: rightOpen.value,
 }))
 
-function updateLeftAsideOpen(detail: LayoutAsideOpenDetail) {
+function updateLeftAsideOpen(detail: LayoutAsideOpenValue) {
   leftOpen.value = detail.open
 }
 
-function updateLeftAsideWidth(detail: LayoutAsideResizeDetail) {
+function updateLeftAsideWidth(detail: LayoutAsideResizeValue) {
   leftExpandedWidth.value = detail.expandedWidth
 }
 
-function updateRightAsideOpen(detail: LayoutAsideOpenDetail) {
+function updateRightAsideOpen(detail: LayoutAsideOpenValue) {
   rightOpen.value = detail.open
 }
 </script>
@@ -84,14 +84,6 @@ function updateRightAsideOpen(detail: LayoutAsideOpenDetail) {
             </template>
           </TrLayout.AsideToggle>
         </div>
-
-        <div v-else class="layout-slot-props-demo__rail">
-          <TrLayout.AsideToggle side="left" class="layout-slot-props-demo__button">
-            <template #default="{ isOpen }">
-              {{ isOpen ? '收起' : '展开' }}
-            </template>
-          </TrLayout.AsideToggle>
-        </div>
       </template>
 
       <template #header>
@@ -184,12 +176,6 @@ function updateRightAsideOpen(detail: LayoutAsideOpenDetail) {
   background: var(--vp-c-bg, #ffffff);
 }
 
-.layout-slot-props-demo__rail {
-  display: grid;
-  place-items: center;
-  height: 100%;
-}
-
 .layout-slot-props-demo__aside p,
 .layout-slot-props-demo__drawer p {
   margin: 0;
diff --git a/docs/demos/layout/floating-panels.vue b/docs/demos/layout/floating-panels.vue
index 26d4bbb78..f328700a5 100644
--- a/docs/demos/layout/floating-panels.vue
+++ b/docs/demos/layout/floating-panels.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
-import type { LayoutAsideOpenDetail, LayoutFloatingOptions, LayoutFloatingState } from '@opentiny/tiny-robot'
+import type { LayoutAsideOpenValue, LayoutFloatingOptions, LayoutFloatingState } from '@opentiny/tiny-robot'
 
 const open = ref(false)
 const leftOpen = ref(false)
@@ -23,11 +23,11 @@ const floatingOptions: LayoutFloatingOptions = {
   minHeight: 320,
 }
 
-function updateLeftAside(detail: LayoutAsideOpenDetail) {
+function updateLeftAside(detail: LayoutAsideOpenValue) {
   leftOpen.value = detail.open
 }
 
-function updateRightAside(detail: LayoutAsideOpenDetail) {
+function updateRightAside(detail: LayoutAsideOpenValue) {
   rightOpen.value = detail.open
 }
 </script>

From 1aaee79e4b7f5fc33110671d624dfc6f6a1b7304 Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Tue, 7 Jul 2026 03:00:12 -0700
Subject: [PATCH 03/12] feat: enhance layout demos and documentation

---
 docs/demos/layout/aside-collapse-effect.vue   |  16 +-
 docs/demos/layout/aside-modes.vue             |   9 +-
 docs/demos/layout/aside-slot-props.vue        |  40 +++--
 docs/demos/layout/floating-controlled.vue     | 103 +++++++++++
 docs/demos/layout/floating-panels.vue         |  21 +--
 docs/demos/layout/floating.vue                | 104 ++++++++---
 docs/demos/layout/main-scroll-bubble.vue      |  28 +--
 docs/demos/layout/main-scroll-div.vue         |  24 +--
 docs/demos/layout/main-scroll.vue             |  48 +----
 docs/src/components/layout.md                 | 170 +++++++++++++-----
 .../src/layout/components/LayoutSurface.vue   |   3 +-
 11 files changed, 383 insertions(+), 183 deletions(-)
 create mode 100644 docs/demos/layout/floating-controlled.vue

diff --git a/docs/demos/layout/aside-collapse-effect.vue b/docs/demos/layout/aside-collapse-effect.vue
index 28d3b902e..82df2fabe 100644
--- a/docs/demos/layout/aside-collapse-effect.vue
+++ b/docs/demos/layout/aside-collapse-effect.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
-import { TinyRadio, TinyRadioGroup, TinySwitch } from '@opentiny/vue'
+import { TinyRadio, TinyRadioGroup, TinySlider, TinySwitch } from '@opentiny/vue'
 import type { LayoutAsideCollapseEffect, LayoutAsideProps } from '@opentiny/tiny-robot'
 
 const collapseEffect = ref<LayoutAsideCollapseEffect>('overlay')
@@ -44,13 +44,12 @@ const collapsedHint = computed(() =>
 
       <label class="layout-collapse-effect-demo__field layout-collapse-effect-demo__field--range">
         <span class="layout-collapse-effect-demo__range-label">收起宽度</span>
-        <input
+        <TinySlider
           v-model.number="collapsedWidth"
           class="layout-collapse-effect-demo__range"
-          type="range"
-          min="0"
-          max="120"
-          step="4"
+          :min="0"
+          :max="120"
+          :step="4"
         />
         <strong>{{ collapsedWidth }}px</strong>
       </label>
@@ -128,7 +127,6 @@ const collapsedHint = computed(() =>
 }
 
 .layout-collapse-effect-demo__field--range {
-  min-width: min(320px, 100%);
   flex: 1 1 280px;
 }
 
@@ -137,8 +135,8 @@ const collapsedHint = computed(() =>
 }
 
 .layout-collapse-effect-demo__range {
-  width: 100%;
-  min-width: 120px;
+  min-width: 160px;
+  flex: 1;
 }
 
 .layout-collapse-effect-demo__aside {
diff --git a/docs/demos/layout/aside-modes.vue b/docs/demos/layout/aside-modes.vue
index 960c7a1e7..ebcb6dd68 100644
--- a/docs/demos/layout/aside-modes.vue
+++ b/docs/demos/layout/aside-modes.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
+import { TinyButton } from '@opentiny/vue'
 import type { LayoutAsideOpenValue } from '@opentiny/tiny-robot'
 
 const leftOpen = ref(true)
@@ -29,7 +30,9 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
           <div class="layout-aside-demo__chip">collapsedWidth: 56px</div>
         </div>
         <div v-else class="layout-aside-demo__rail">
-          <TrLayout.AsideToggle side="left" class="layout-aside-demo__rail-chip">栏</TrLayout.AsideToggle>
+          <TrLayout.AsideToggle side="left" class="layout-aside-demo__rail-chip" aria-label="展开左侧栏">
+            栏
+          </TrLayout.AsideToggle>
           <div class="layout-aside-demo__rail-chip">56</div>
         </div>
       </template>
@@ -37,7 +40,7 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
       <template #header>
         <div class="layout-aside-demo__header">
           <span>侧栏模式</span>
-          <button type="button" class="layout-aside-demo__chip" @click="rightOpen = true">打开抽屉</button>
+          <TinyButton :reset-time="0" @click="rightOpen = true">打开抽屉</TinyButton>
         </div>
       </template>
 
@@ -48,7 +51,7 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
       <template #right-aside>
         <div class="layout-aside-demo__drawer layout-aside-demo__drawer-panel">
           <div>Drawer</div>
-          <div>点击遮罩、按 `Esc` 或按钮关闭。</div>
+          <div>点击遮罩或按钮关闭。</div>
           <TrLayout.AsideToggle side="right" class="layout-aside-demo__chip">关闭抽屉</TrLayout.AsideToggle>
         </div>
       </template>
diff --git a/docs/demos/layout/aside-slot-props.vue b/docs/demos/layout/aside-slot-props.vue
index 6658a71b4..59296c8bb 100644
--- a/docs/demos/layout/aside-slot-props.vue
+++ b/docs/demos/layout/aside-slot-props.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
+import { TinyButton, TinySlider } from '@opentiny/vue'
 import type { LayoutAsideProps, LayoutAsideOpenValue, LayoutAsideResizeValue } from '@opentiny/tiny-robot'
 
 const leftOpen = ref(true)
@@ -41,19 +42,18 @@ function updateRightAsideOpen(detail: LayoutAsideOpenValue) {
     <div class="layout-slot-props-demo__controls">
       <div class="layout-slot-props-demo__group">
         <span class="layout-slot-props-demo__group-label">左侧栏</span>
-        <button type="button" class="layout-slot-props-demo__button" @click="leftOpen = !leftOpen">
+        <TinyButton :reset-time="0" @click="leftOpen = !leftOpen">
           {{ leftOpen ? '收起侧栏' : '展开侧栏' }}
-        </button>
+        </TinyButton>
         <label class="layout-slot-props-demo__range-wrap">
           <span class="layout-slot-props-demo__range-label">宽度</span>
-          <input
+          <TinySlider
             v-model.number="leftExpandedWidth"
             class="layout-slot-props-demo__range"
-            type="range"
             :min="leftWidthMin"
             :max="leftWidthMax"
-            step="4"
-            @input="leftOpen = true"
+            :step="4"
+            @change="leftOpen = true"
           />
           <strong>{{ leftExpandedWidth }}px</strong>
         </label>
@@ -61,9 +61,9 @@ function updateRightAsideOpen(detail: LayoutAsideOpenValue) {
 
       <div class="layout-slot-props-demo__group">
         <span class="layout-slot-props-demo__group-label">右侧栏</span>
-        <button type="button" class="layout-slot-props-demo__button" @click="rightOpen = !rightOpen">
+        <TinyButton :reset-time="0" @click="rightOpen = !rightOpen">
           {{ rightOpen ? '关闭抽屉' : '打开抽屉' }}
-        </button>
+        </TinyButton>
       </div>
     </div>
 
@@ -76,22 +76,25 @@ function updateRightAsideOpen(detail: LayoutAsideOpenValue) {
       @right-aside-open-change="updateRightAsideOpen"
     >
       <template #left-aside>
-        <div v-if="leftOpen" class="layout-slot-props-demo__aside">
-          <p>左侧栏宽度：{{ leftExpandedWidth }}px</p>
-          <TrLayout.AsideToggle side="left" class="layout-slot-props-demo__button">
-            <template #default="{ isOpen }">
-              {{ isOpen ? '收起侧栏' : '展开侧栏' }}
-            </template>
-          </TrLayout.AsideToggle>
+        <div class="layout-slot-props-demo__aside">
+          <template v-if="leftOpen">
+            <p>左侧栏宽度：{{ leftExpandedWidth }}px</p>
+            <TrLayout.AsideToggle side="left" class="layout-slot-props-demo__button">
+              <template #default="{ isOpen }">
+                {{ isOpen ? '收起侧栏' : '展开侧栏' }}
+              </template>
+            </TrLayout.AsideToggle>
+          </template>
+          <p v-else>左侧栏已关闭，请通过外部按钮重新展开。</p>
         </div>
       </template>
 
       <template #header>
-        <div class="layout-slot-props-demo__header">外层更新 leftAside / rightAside，并通过事件回写状态。</div>
+        <div class="layout-slot-props-demo__header">外层更新 leftAside / rightAside，并通过事件同步外部状态。</div>
       </template>
 
       <template #main>
-        <div class="layout-slot-props-demo__main">外层控制 open 和 expandedWidth，状态变化后通过事件回写。</div>
+        <div class="layout-slot-props-demo__main">外层控制 open 和 expandedWidth，状态变化后通过事件同步。</div>
       </template>
 
       <template #right-aside>
@@ -156,7 +159,8 @@ function updateRightAsideOpen(detail: LayoutAsideOpenValue) {
 }
 
 .layout-slot-props-demo__range {
-  width: 180px;
+  min-width: 160px;
+  flex: 1;
 }
 
 .layout-slot-props-demo__header {
diff --git a/docs/demos/layout/floating-controlled.vue b/docs/demos/layout/floating-controlled.vue
new file mode 100644
index 000000000..133879db9
--- /dev/null
+++ b/docs/demos/layout/floating-controlled.vue
@@ -0,0 +1,103 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+import { TinyButton } from '@opentiny/vue'
+import type { LayoutFloatingState } from '@opentiny/tiny-robot'
+
+const open = ref(false)
+const floatingState = ref<LayoutFloatingState>({
+  placement: 'top-right',
+  offsetX: 0,
+  offsetY: 0,
+  width: 520,
+  height: 360,
+})
+
+const stateText = computed(() => JSON.stringify(floatingState.value, null, 2))
+
+function updateFloatingState(nextState: LayoutFloatingState) {
+  floatingState.value = nextState
+}
+</script>
+
+<template>
+  <div class="layout-floating-controlled-demo">
+    <div class="layout-floating-controlled-demo__toolbar">
+      <TinyButton :reset-time="0" @click="open = !open">
+        {{ open ? '关闭浮层' : '打开浮层' }}
+      </TinyButton>
+      <span class="layout-floating-controlled-demo__tip">组件按 floatingState 渲染，变化通过事件通知外部。</span>
+    </div>
+
+    <TrLayout
+      v-if="open"
+      class="layout-floating-controlled-demo__layout"
+      mode="floating"
+      :floating-state="floatingState"
+      :floating-options="{ draggable: false, resizable: true, minWidth: 360, maxWidth: 720, minHeight: 260 }"
+      @update:floating-state="updateFloatingState"
+    >
+      <template #header>
+        <div class="layout-floating-controlled-demo__header">
+          <strong>受控浮层</strong>
+          <TinyButton :reset-time="0" size="small" @click="open = false">关闭</TinyButton>
+        </div>
+      </template>
+
+      <template #main>
+        <div class="layout-floating-controlled-demo__main">
+          <pre class="layout-floating-controlled-demo__state">{{ stateText }}</pre>
+        </div>
+      </template>
+    </TrLayout>
+  </div>
+</template>
+
+<style>
+.layout-floating-controlled-demo__layout {
+  --tr-layout-floating-radius: 12px;
+}
+</style>
+
+<style scoped>
+.layout-floating-controlled-demo {
+  display: grid;
+  gap: 8px;
+}
+
+.layout-floating-controlled-demo__toolbar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.layout-floating-controlled-demo__tip {
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
+.layout-floating-controlled-demo__header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
+}
+
+.layout-floating-controlled-demo__main {
+  padding: 16px;
+}
+
+.layout-floating-controlled-demo__state {
+  box-sizing: border-box;
+  margin: 0;
+  min-height: 100%;
+  padding: 12px;
+  border-radius: 8px;
+  overflow: auto;
+  background: var(--vp-c-bg-soft, #f6f8fa);
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+</style>
diff --git a/docs/demos/layout/floating-panels.vue b/docs/demos/layout/floating-panels.vue
index f328700a5..3814d39bb 100644
--- a/docs/demos/layout/floating-panels.vue
+++ b/docs/demos/layout/floating-panels.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
+import { TinyButton } from '@opentiny/vue'
 import type { LayoutAsideOpenValue, LayoutFloatingOptions, LayoutFloatingState } from '@opentiny/tiny-robot'
 
 const open = ref(false)
@@ -35,9 +36,9 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
 <template>
   <div class="layout-floating-panels-demo">
     <div class="layout-floating-panels-demo__toolbar">
-      <button type="button" class="layout-floating-panels-demo__button" @click="open = !open">
+      <TinyButton :reset-time="0" @click="open = !open">
         {{ open ? '关闭浮层' : '打开浮层' }}
-      </button>
+      </TinyButton>
     </div>
 
     <TrLayout
@@ -63,12 +64,8 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
         <div class="layout-floating-panels-demo__header">
           <strong>浮层工作区</strong>
           <div class="layout-floating-panels-demo__actions">
-            <button type="button" class="layout-floating-panels-demo__button" @click="leftOpen = true">
-              打开左抽屉
-            </button>
-            <button type="button" class="layout-floating-panels-demo__button" @click="rightOpen = true">
-              打开右抽屉
-            </button>
+            <TinyButton :reset-time="0" @click="leftOpen = true">打开左抽屉</TinyButton>
+            <TinyButton :reset-time="0" @click="rightOpen = true">打开右抽屉</TinyButton>
           </div>
         </div>
       </template>
@@ -83,7 +80,7 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
       <template #right-aside>
         <div class="layout-floating-panels-demo__drawer">
           <div class="layout-floating-panels-demo__drawer-title">右侧抽屉</div>
-          <div>点击遮罩、按 `Esc` 或按钮都可以关闭。</div>
+          <div>点击遮罩或按钮都可以关闭。</div>
           <TrLayout.AsideToggle side="right" class="layout-floating-panels-demo__chip">关闭抽屉</TrLayout.AsideToggle>
         </div>
       </template>
@@ -117,20 +114,16 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
   gap: 8px;
 }
 
-.layout-floating-panels-demo__button,
-.layout-floating-panels-demo__chip,
-.layout-floating-panels-demo__rail-chip {
+.layout-floating-panels-demo__chip {
   border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
   background: var(--vp-c-bg, #ffffff);
   color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
 }
 
-.layout-floating-panels-demo__button,
 .layout-floating-panels-demo__chip {
   min-height: 36px;
   padding: 0 12px;
   border-radius: 8px;
-  cursor: pointer;
 }
 
 .layout-floating-panels-demo__header {
diff --git a/docs/demos/layout/floating.vue b/docs/demos/layout/floating.vue
index e85bfff6e..22ac49636 100644
--- a/docs/demos/layout/floating.vue
+++ b/docs/demos/layout/floating.vue
@@ -1,37 +1,79 @@
 <script setup lang="ts">
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
+import { TinyBaseSelect, TinyButton, TinyNumeric, TinyOption, TinySwitch } from '@opentiny/vue'
 import type { LayoutFloatingOptions, LayoutFloatingState } from '@opentiny/tiny-robot'
 
+type FloatingPlacement = LayoutFloatingState['placement']
+
 const open = ref(false)
+const placement = ref<FloatingPlacement>('top-right')
+const offsetX = ref(0)
+const offsetY = ref(0)
+const draggable = ref(true)
+const resizable = ref(true)
+
+const placements: FloatingPlacement[] = ['top-left', 'top-right', 'bottom-left', 'bottom-right', 'center']
 
-const defaultFloatingState: LayoutFloatingState = {
-  placement: 'top-right',
-  offsetX: 24,
-  offsetY: 32,
+const defaultFloatingState = computed<LayoutFloatingState>(() => ({
+  placement: placement.value,
+  offsetX: offsetX.value,
+  offsetY: offsetY.value,
   width: 520,
   height: 360,
-}
+}))
 
-const floatingOptions: LayoutFloatingOptions = {
-  draggable: true,
-  resizable: true,
+const floatingStateKey = computed(() => `${placement.value}-${offsetX.value}-${offsetY.value}`)
+
+const floatingOptions = computed<LayoutFloatingOptions>(() => ({
+  draggable: draggable.value,
+  resizable: resizable.value,
   minWidth: 360,
   maxWidth: 680,
-}
+}))
 </script>
 
 <template>
   <div class="layout-floating-demo">
     <div class="layout-floating-demo__toolbar">
-      <button type="button" class="layout-floating-demo__trigger" @click="open = !open">
+      <TinyButton :reset-time="0" @click="open = !open">
         {{ open ? '关闭浮层' : '打开浮层' }}
-      </button>
-      <span class="layout-floating-demo__tip">拖动顶部横条或边缘手柄调整位置和大小。</span>
+      </TinyButton>
+      <span class="layout-floating-demo__tip">非受控浮层会在内部维护拖拽和缩放后的状态。</span>
+    </div>
+
+    <div class="layout-floating-demo__controls">
+      <label class="layout-floating-demo__field">
+        <span>placement</span>
+        <TinyBaseSelect v-model="placement" class="layout-floating-demo__select">
+          <TinyOption v-for="item in placements" :key="item" :label="item" :value="item" />
+        </TinyBaseSelect>
+      </label>
+
+      <label class="layout-floating-demo__field">
+        <span>offsetX</span>
+        <TinyNumeric v-model="offsetX" class="layout-floating-demo__numeric" />
+      </label>
+
+      <label class="layout-floating-demo__field">
+        <span>offsetY</span>
+        <TinyNumeric v-model="offsetY" class="layout-floating-demo__numeric" />
+      </label>
+
+      <label class="layout-floating-demo__field">
+        <span>draggable</span>
+        <TinySwitch v-model="draggable" />
+      </label>
+
+      <label class="layout-floating-demo__field">
+        <span>resizable</span>
+        <TinySwitch v-model="resizable" />
+      </label>
     </div>
 
     <TrLayout
       v-if="open"
+      :key="floatingStateKey"
       class="layout-floating-demo__layout"
       mode="floating"
       :default-floating-state="defaultFloatingState"
@@ -40,14 +82,15 @@ const floatingOptions: LayoutFloatingOptions = {
       <template #header>
         <div class="layout-floating-demo__header">
           <strong>浮层布局</strong>
-          <button type="button" class="layout-floating-demo__close" @click="open = false">关闭</button>
+          <TinyButton :reset-time="0" size="small" @click="open = false">关闭</TinyButton>
         </div>
       </template>
 
       <template #main>
         <div class="layout-floating-demo__main">
-          <div class="layout-floating-demo__card">`defaultFloatingState` 设置初始位置和大小。</div>
-          <div class="layout-floating-demo__card">`floatingOptions` 控制拖动、缩放和尺寸范围。</div>
+          <div class="layout-floating-demo__card">`defaultFloatingState` 只设置初始位置和大小。</div>
+          <div class="layout-floating-demo__card">拖动顶部横条可移动浮层，拖动边缘手柄可调整大小。</div>
+          <div class="layout-floating-demo__card">切换 placement 或 offset 会重置初始位置，方便观察定位效果。</div>
         </div>
       </template>
     </TrLayout>
@@ -73,21 +116,32 @@ const floatingOptions: LayoutFloatingOptions = {
   gap: 8px;
 }
 
-.layout-floating-demo__trigger,
-.layout-floating-demo__close {
-  height: 36px;
-  padding: 0 12px;
-  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
-  border-radius: 8px;
-  background: var(--vp-c-bg, #ffffff);
-  color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
-  cursor: pointer;
+.layout-floating-demo__controls {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
 }
 
 .layout-floating-demo__tip {
   color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
 }
 
+.layout-floating-demo__field {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
+.layout-floating-demo__select {
+  width: 148px;
+}
+
+.layout-floating-demo__numeric {
+  width: 104px;
+}
+
 .layout-floating-demo__main {
   display: grid;
   gap: 12px;
diff --git a/docs/demos/layout/main-scroll-bubble.vue b/docs/demos/layout/main-scroll-bubble.vue
index f0219e49c..f232dde0a 100644
--- a/docs/demos/layout/main-scroll-bubble.vue
+++ b/docs/demos/layout/main-scroll-bubble.vue
@@ -1,13 +1,13 @@
 <script setup lang="ts">
 import { ref } from 'vue'
 import { BubbleList, TrLayout } from '@opentiny/tiny-robot'
-import type { BubbleListProps, BubbleRoleConfig, LayoutScrollTarget } from '@opentiny/tiny-robot'
+import type { BubbleListProps, BubbleRoleConfig } from '@opentiny/tiny-robot'
 
 const props = defineProps<{
   centered: boolean
 }>()
 
-const scrollTargetRef = ref<LayoutScrollTarget>(null)
+const scrollTargetRef = ref<HTMLElement | null>(null)
 
 const roles: Record<string, BubbleRoleConfig> = {
   user: { placement: 'end' },
@@ -29,32 +29,32 @@ const messages: BubbleListProps['messages'] = Array.from({ length: 12 }, (_, ind
 <template>
   <TrLayout>
     <template #main>
-      <BubbleList
-        ref="scrollTargetRef"
-        class="layout-main-scroll-bubble"
-        :class="{ 'is-centered': props.centered }"
-        :messages="messages"
-        :role-configs="roles"
-      />
+      <div ref="scrollTargetRef" class="layout-main-scroll-bubble-host">
+        <div class="layout-main-scroll-bubble-host__content" :class="{ 'is-centered': props.centered }">
+          <BubbleList class="layout-main-scroll-bubble" :messages="messages" :role-configs="roles" />
+        </div>
+      </div>
       <TrLayout.ProxyScrollbar :scroll-target="scrollTargetRef" />
     </template>
   </TrLayout>
 </template>
 
 <style scoped>
-.layout-main-scroll-bubble {
-  --tr-bubble-list-padding: 16px;
-  width: 100%;
+.layout-main-scroll-bubble-host {
   height: 100%;
-  box-sizing: border-box;
   overflow: auto;
 }
 
-.layout-main-scroll-bubble.is-centered {
+.layout-main-scroll-bubble-host__content.is-centered {
   max-width: 450px;
   margin: 0 auto;
 }
 
+.layout-main-scroll-bubble {
+  --tr-bubble-list-padding: 16px;
+  overflow: visible;
+}
+
 :deep([data-role='user']) {
   --tr-bubble-box-bg: var(--tr-color-primary-light);
 }
diff --git a/docs/demos/layout/main-scroll-div.vue b/docs/demos/layout/main-scroll-div.vue
index 2698c7ebf..06d5e2dc9 100644
--- a/docs/demos/layout/main-scroll-div.vue
+++ b/docs/demos/layout/main-scroll-div.vue
@@ -1,13 +1,12 @@
 <script setup lang="ts">
 import { ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
-import type { LayoutScrollTarget } from '@opentiny/tiny-robot'
 
 const props = defineProps<{
   centered: boolean
 }>()
 
-const scrollTargetRef = ref<LayoutScrollTarget>(null)
+const scrollTargetRef = ref<HTMLElement | null>(null)
 
 const sections = Array.from({ length: 12 }, (_, index) => index + 1)
 </script>
@@ -15,11 +14,13 @@ const sections = Array.from({ length: 12 }, (_, index) => index + 1)
 <template>
   <TrLayout>
     <template #main>
-      <div ref="scrollTargetRef" class="layout-main-scroll-div" :class="{ 'is-centered': props.centered }">
-        <section v-for="section in sections" :key="section" class="layout-main-scroll-div__item">
-          <strong>Section {{ section }}</strong>
-          <p>普通内容区也可以把滚动容器交给 Layout.ProxyScrollbar。</p>
-        </section>
+      <div ref="scrollTargetRef" class="layout-main-scroll-div">
+        <div class="layout-main-scroll-div__content" :class="{ 'is-centered': props.centered }">
+          <section v-for="section in sections" :key="section" class="layout-main-scroll-div__item">
+            <strong>Section {{ section }}</strong>
+            <p>普通内容区也可以把滚动容器交给 Layout.ProxyScrollbar。</p>
+          </section>
+        </div>
       </div>
       <TrLayout.ProxyScrollbar :scroll-target="scrollTargetRef" />
     </template>
@@ -28,16 +29,17 @@ const sections = Array.from({ length: 12 }, (_, index) => index + 1)
 
 <style scoped>
 .layout-main-scroll-div {
-  width: 100%;
   height: 100%;
-  box-sizing: border-box;
+  overflow: auto;
+}
+
+.layout-main-scroll-div__content {
   display: grid;
   gap: 12px;
   padding: 16px;
-  overflow: auto;
 }
 
-.layout-main-scroll-div.is-centered {
+.layout-main-scroll-div__content.is-centered {
   max-width: 550px;
   margin: 0 auto;
 }
diff --git a/docs/demos/layout/main-scroll.vue b/docs/demos/layout/main-scroll.vue
index 9df127122..61b126377 100644
--- a/docs/demos/layout/main-scroll.vue
+++ b/docs/demos/layout/main-scroll.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { ref } from 'vue'
-import { TinySwitch } from '@opentiny/vue'
+import { TinyRadio, TinyRadioGroup, TinySwitch } from '@opentiny/vue'
 import MainScrollBubble from './main-scroll-bubble.vue'
 import MainScrollDiv from './main-scroll-div.vue'
 
@@ -11,33 +11,17 @@ const isCentered = ref(true)
 <template>
   <div class="layout-main-scroll-demo">
     <div class="layout-main-scroll-demo__toolbar">
-      <div class="layout-main-scroll-demo__switcher" aria-label="主区滚动示例切换">
-        <button
-          type="button"
-          class="layout-main-scroll-demo__switch"
-          :class="{ 'is-active': activeExample === 'bubble' }"
-          :aria-pressed="activeExample === 'bubble'"
-          @click="activeExample = 'bubble'"
-        >
-          BubbleList
-        </button>
-
-        <button
-          type="button"
-          class="layout-main-scroll-demo__switch"
-          :class="{ 'is-active': activeExample === 'div' }"
-          :aria-pressed="activeExample === 'div'"
-          @click="activeExample = 'div'"
-        >
-          普通 div
-        </button>
-      </div>
+      <tiny-radio-group v-model="activeExample" aria-label="主区滚动示例切换">
+        <tiny-radio label="bubble">BubbleList</tiny-radio>
+        <tiny-radio label="div">普通 div</tiny-radio>
+      </tiny-radio-group>
 
       <label class="layout-main-scroll-demo__field">
         <span>内容居中</span>
         <tiny-switch v-model="isCentered"></tiny-switch>
       </label>
     </div>
+    <p class="layout-main-scroll-demo__tip">外层作为滚动宿主，内层只负责居中和限宽。</p>
 
     <div class="layout-main-scroll-demo__stage">
       <MainScrollBubble v-if="activeExample === 'bubble'" :centered="isCentered" />
@@ -58,12 +42,6 @@ const isCentered = ref(true)
   gap: 12px;
 }
 
-.layout-main-scroll-demo__switcher {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-}
-
 .layout-main-scroll-demo__field {
   display: inline-flex;
   align-items: center;
@@ -71,19 +49,9 @@ const isCentered = ref(true)
   color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
 }
 
-.layout-main-scroll-demo__switch {
-  height: 34px;
-  padding: 0 12px;
-  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
-  border-radius: 8px;
-  background: var(--vp-c-bg, #ffffff);
+.layout-main-scroll-demo__tip {
+  margin: 0;
   color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
-  cursor: pointer;
-}
-
-.layout-main-scroll-demo__switch.is-active {
-  border-color: var(--vp-c-brand-1, var(--tr-color-primary, #5e7ce0));
-  color: var(--vp-c-brand-1, var(--tr-color-primary, #5e7ce0));
 }
 
 .layout-main-scroll-demo__stage {
diff --git a/docs/src/components/layout.md b/docs/src/components/layout.md
index 79434c3e3..36596d308 100644
--- a/docs/src/components/layout.md
+++ b/docs/src/components/layout.md
@@ -6,23 +6,36 @@ outline: [1, 3]
 
 `Layout` 用来组织带有头部、主内容区、底部和左右侧栏的页面。
 
-它覆盖三类核心场景：
+它覆盖五类核心使用模型：
 
-- 标准页面骨架
-- 可收起的左右侧栏
-- 可拖动、可缩放的浮层布局
+- 页面骨架：通过 `left-aside`、`header`、`main`、`footer`、`right-aside` 组织区域内容
+- 布局模式：通过 `mode` 在普通布局和浮层布局之间切换
+- 侧栏配置：通过 `leftAside` / `rightAside` 控制侧栏行为
+- 浮层状态：通过 `defaultFloatingState` 或 `floatingState` 控制浮层位置和尺寸
+- 主区滚动：通过 `Layout.ProxyScrollbar` 将滚动条固定在主区边界
 
 ## 基础布局
 
-`Layout` 用于定义页面结构，区域中的具体内容可按需配置。
+`Layout` 用于定义页面结构，各区域的具体内容通过插槽提供。
 
 <demo vue="../../demos/layout/basic.vue" title="基础布局" description="最小布局示例。" />
 
+## 布局模式
+
+`mode` 控制 `Layout` 的整体形态。
+
+- `normal`：普通页面骨架，参与原始页面布局
+- `floating`：悬浮工作区，脱离原始页面布局并挂载到 `body`
+
+普通页面不需要显式传 `mode`。需要临时面板、悬浮工作台或可拖拽窗口时，再使用 `mode="floating"`。
+
 ## 侧栏
 
-### 展示形态
+侧栏由 `leftAside` / `rightAside` 控制，类型为 [`LayoutAsideProps`](#layout-aside-props)。
 
-用 `leftAside` / `rightAside` 配置侧栏。
+侧栏内容通过 `left-aside` / `right-aside` 插槽提供。配置和内容分开后，业务可以只调整行为配置，而不影响插槽里的渲染结构。
+
+### 展示形态
 
 - `dock`：占据页面空间
 - `drawer`：覆盖在内容上方
@@ -46,13 +59,17 @@ outline: [1, 3]
   description="对比 overlay 和 slide 两种收起动画。"
 />
 
-### 状态控制
+### 宽度调整
 
-用 `leftAside` / `rightAside` 控制开关和宽度。
+`resizable` 可以开启 `dock` 侧栏的拖拽改宽，宽度范围由 `minExpandedWidth` 和 `maxExpandedWidth` 控制。
 
-侧栏内容通过 `left-aside` / `right-aside` 提供。
+<demo vue="../../demos/layout/aside-resizable.vue" title="宽度调整" description="拖动分隔线查看当前宽度和边界。" />
+
+### 状态控制
 
-受控用法下，状态变化后需要同步回写。侧栏内部切换可使用 `Layout.AsideToggle`，默认插槽提供 `{ isOpen }`。
+`open` 和 `expandedWidth` 是受控值，状态变化后需要通过事件同步外部状态。
+
+`defaultOpen` 和 `defaultExpandedWidth` 只提供初始值，适合不需要外部持续控制的场景。
 
 <demo
   vue="../../demos/layout/aside-slot-props.vue"
@@ -60,21 +77,54 @@ outline: [1, 3]
   description="用开关和滑块展示 leftAside、rightAside 和事件同步。"
 />
 
-### 宽度调整
+## 浮层
 
-`resizable` 可以开启 `dock` 侧栏的拖拽改宽，宽度范围由 `minExpandedWidth` 和 `maxExpandedWidth` 控制。
+浮层只在 `mode="floating"` 时生效，适合临时面板、悬浮工作区或对话面板。
 
-<demo vue="../../demos/layout/aside-resizable.vue" title="宽度调整" description="拖动分隔线查看当前宽度和边界。" />
+`defaultFloatingState` 和 `floatingState` 不要同时传入：
+
+- `defaultFloatingState`：非受控初始状态，只在首次挂载时读取
+- `floatingState`：受控状态，由外部维护当前位置和尺寸
+
+### 非受控浮层
+
+非受控浮层通过 `defaultFloatingState` 设置初始位置和尺寸。拖动或缩放后，状态由组件内部维护，适合展示 `placement`、`offsetX`、`offsetY`、`draggable` 和 `resizable`。
+
+<demo
+  vue="../../demos/layout/floating.vue"
+  title="非受控浮层"
+  description="打开时通过 defaultFloatingState 设置初始位置和大小。"
+/>
+
+### 受控浮层
+
+受控浮层以 `floatingState` 作为唯一状态源，组件按传入状态渲染；拖拽或缩放产生变化时，通过 `update:floatingState` 通知外部同步。位置固定或由外部规则决定时，建议关闭 `draggable`。
+
+<demo
+  vue="../../demos/layout/floating-controlled.vue"
+  title="受控浮层"
+  description="通过 floatingState 控制位置和大小，并回显当前状态。"
+/>
+
+### 浮层工作区
+
+浮层里同样可以放入侧栏、头部和主区。常见用法是把左右两侧都做成按需展开的 drawer。
+
+<demo
+  vue="../../demos/layout/floating-panels.vue"
+  title="浮层工作区"
+  description="在浮层里组合左右 drawer，适合临时工作区、对话面板或侧边操作台。"
+/>
 
 ## 主区滚动
 
-`Layout.ProxyScrollbar` 用来显示主区滚动条，`scrollTarget` 指向实际滚动的内容区域。
+`Layout.ProxyScrollbar` 用来代理主区滚动条，适合消息流、长内容阅读流和工作台主区。
 
-> 适合消息区居中的对话页：内容可以居中，滚动条仍固定在主区右侧，视觉更整齐。
+它解决的是“内容列居中后，原生滚动条跟着内容列移动，不再贴近主区右边界”的问题。使用时应让外层作为真实滚动宿主；如果内容需要居中或限宽，再交给内层容器处理。
 
 - `scrollTarget` 传实际滚动元素，或对应组件实例的 `ref`
-- 该元素需自行设置尺寸、`box-sizing` 和滚动样式
-- `Layout.ProxyScrollbar` 会自动隐藏该元素的原生滚动条
+- 滚动宿主需自行设置尺寸、`box-sizing` 和滚动样式
+- `Layout.ProxyScrollbar` 会自动隐藏滚动宿主的原生滚动条
 
 ```css
 .scroll-host {
@@ -96,34 +146,11 @@ outline: [1, 3]
   description="演示内容区居中后，滚动条仍固定在主区右侧。"
 />
 
-## 浮层
-
-适合临时面板或悬浮工作区，只在 `mode="floating"` 时生效。
+## Layout.AsideToggle
 
-### 基本用法
+`Layout.AsideToggle` 是内置侧栏开关按钮，只能在 `Layout` 内部使用，通常放在 `left-aside` / `right-aside` 插槽中。
 
-`defaultFloatingState` 设置初始位置和大小，`floatingOptions` 设置拖动、缩放和尺寸范围。
-
-- `defaultFloatingState`：只设置初始值
-- `floatingState`：由外部控制位置和大小
-
-传 `floatingState` 时，需要在 `update:floatingState` 中同步最新值。
-
-<demo
-  vue="../../demos/layout/floating.vue"
-  title="基本用法"
-  description="打开时通过 defaultFloatingState 设置初始位置和大小。"
-/>
-
-### 浮层工作区
-
-浮层里同样可以放入侧栏、头部和主区。常见用法是把左右两侧都做成按需展开的 drawer。
-
-<demo
-  vue="../../demos/layout/floating-panels.vue"
-  title="浮层工作区"
-  description="在浮层里组合左右 drawer，适合临时工作区、对话面板或侧边操作台。"
-/>
+它适合让侧栏内容自己控制展开和收起，默认插槽提供 `{ isOpen }`。自定义按钮内容时，应保留可读文本或补充 `aria-label`。
 
 ## Props
 
@@ -134,8 +161,8 @@ outline: [1, 3]
 | `mode` | 布局模式；`normal` 参与普通布局，`floating` 会脱离普通布局，不占原来的位置空间 | `'normal' \| 'floating'` | `'normal'` |
 | `leftAside` | 左侧栏配置 | [`LayoutAsideProps`](#layout-aside-props) | `-` |
 | `rightAside` | 右侧栏配置 | [`LayoutAsideProps`](#layout-aside-props) | `-` |
-| `floatingState` | 受控浮层状态，需配合 `update:floatingState` 回写 | [`LayoutFloatingState`](#layout-floating-state) | `-` |
-| `defaultFloatingState` | 非受控浮层初始状态，仅首次挂载读取一次 | [`LayoutFloatingState`](#layout-floating-state) | `-` |
+| `floatingState` | 受控浮层状态，需配合 `update:floatingState` 同步外部状态；不要和 `defaultFloatingState` 同时传入 | [`LayoutFloatingState`](#layout-floating-state) | `-` |
+| `defaultFloatingState` | 非受控浮层初始状态，仅首次挂载读取一次；不要和 `floatingState` 同时传入 | [`LayoutFloatingState`](#layout-floating-state) | `-` |
 | `floatingOptions` | 浮层拖拽、缩放和尺寸约束配置 | [`LayoutFloatingOptions`](#layout-floating-options) | `-` |
 
 ### Layout.ProxyScrollbar {#layout-proxy-scrollbar-props}
@@ -150,8 +177,6 @@ outline: [1, 3]
 | ------ | ---- | ---- | ------ |
 | `side` | 控制的侧栏位置 | `'left' \| 'right'` | `-` |
 
-它是一个现成的开关按钮，只能在 `Layout` 内部使用，通常放在 `left-aside` / `right-aside` 插槽中。
-
 ## Slots
 
 ### Layout {#layout-slots}
@@ -172,6 +197,33 @@ outline: [1, 3]
 
 ## Events
 
+单侧状态同步优先使用 `left/right-*` 事件；统一埋点、日志或聚合处理可使用 `aside-*` 事件；浮层受控同步只使用 `update:floatingState`。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+
+const leftOpen = ref(true)
+
+function syncLeftAside(detail: { open: boolean }) {
+  leftOpen.value = detail.open
+}
+
+function trackAsideChange(detail: { side: 'left' | 'right'; open: boolean }) {
+  console.log(detail.side, detail.open)
+}
+</script>
+
+<template>
+  <TrLayout
+    :left-aside="{ open: leftOpen }"
+    @left-aside-open-change="syncLeftAside"
+    @aside-open-change="trackAsideChange"
+  />
+</template>
+```
+
 ### Layout {#layout-layout-events}
 
 | 事件名 | 说明 | 回调参数 |
@@ -243,6 +295,26 @@ outline: [1, 3]
 
 `HTMLElement | Pick<ComponentPublicInstance, '$el'> | null | undefined`
 
+优先传真实 DOM ref。只有组件根节点本身就是滚动宿主时，才传组件 ref；组件 ref 会被解析为 `$el`。
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+
+const scrollEl = ref<HTMLElement | null>(null)
+</script>
+
+<template>
+  <TrLayout>
+    <template #main>
+      <div ref="scrollEl" class="scroll-host"></div>
+      <TrLayout.ProxyScrollbar :scroll-target="scrollEl" />
+    </template>
+  </TrLayout>
+</template>
+```
+
 ### LayoutFloatingState {#layout-floating-state}
 
 | 字段 | 说明 | 类型 | 默认值 |
@@ -298,6 +370,8 @@ outline: [1, 3]
 
 ### 内容与交互 {#layout-css-content}
 
+`Layout` 嵌入卡片、小容器或文档 demo 时，常需要把 `--tr-layout-main-min-width` 设为 `0`，否则主区默认最小宽度 `320px` 可能撑开布局。
+
 | 变量名 | 说明 |
 | ------ | ---- |
 | `--tr-layout-main-min-width` | 主区最小宽度 |
diff --git a/packages/components/src/layout/components/LayoutSurface.vue b/packages/components/src/layout/components/LayoutSurface.vue
index 8ec87e02f..a556fe1ca 100644
--- a/packages/components/src/layout/components/LayoutSurface.vue
+++ b/packages/components/src/layout/components/LayoutSurface.vue
@@ -82,6 +82,7 @@ const isFloatingDragging = computed(() => activeDragRect.value !== null)
 const isFloatingResizing = computed(() => activeResizeRect.value !== null)
 const isFloatingInteracting = computed(() => isFloatingDragging.value || isFloatingResizing.value)
 const canDragFloating = computed(() => isFloating.value && isFloatingDraggable.value && !isFloatingResizing.value)
+const shouldShowFloatingDragBar = computed(() => isFloating.value && isFloatingDraggable.value)
 const resizeHandles = computed<LayoutFloatingResizeHandle[]>(() => {
   if (!isFloating.value || !isFloatingResizable.value) {
     return []
@@ -250,7 +251,7 @@ defineExpose({
       :style="floatingStyle"
     >
       <FloatingDragBar
-        v-if="isFloating"
+        v-if="shouldShowFloatingDragBar"
         :x="floatingRect.x"
         :y="floatingRect.y"
         :can-drag="canDragFloating"

From 10e6b2b5b267b2fcd740f7b689572b4067cd3161 Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Tue, 7 Jul 2026 04:40:21 -0700
Subject: [PATCH 04/12] feat(docs): update layout documentation for clarity and
 accuracy

---
 docs/demos/layout/aside-collapse-effect.vue |  2 +-
 docs/demos/layout/aside-slot-props.vue      |  4 +-
 docs/demos/layout/floating-controlled.vue   |  5 ---
 docs/demos/layout/floating.vue              |  2 +-
 docs/src/components/layout.md               | 45 ++++++++++-----------
 5 files changed, 25 insertions(+), 33 deletions(-)

diff --git a/docs/demos/layout/aside-collapse-effect.vue b/docs/demos/layout/aside-collapse-effect.vue
index 82df2fabe..14ff3f606 100644
--- a/docs/demos/layout/aside-collapse-effect.vue
+++ b/docs/demos/layout/aside-collapse-effect.vue
@@ -16,7 +16,7 @@ const leftAside = computed<LayoutAsideProps>(() => ({
 }))
 
 const hint = computed(() =>
-  collapseEffect.value === 'overlay' ? '收起时更像把内容盖住，内容留在原位' : '收起时更像整块一起滑走',
+  collapseEffect.value === 'overlay' ? '收起时内容层不跟随宽度滑动' : '收起时内容层随宽度一起滑动',
 )
 
 const collapsedHint = computed(() =>
diff --git a/docs/demos/layout/aside-slot-props.vue b/docs/demos/layout/aside-slot-props.vue
index 59296c8bb..8779256f8 100644
--- a/docs/demos/layout/aside-slot-props.vue
+++ b/docs/demos/layout/aside-slot-props.vue
@@ -90,11 +90,11 @@ function updateRightAsideOpen(detail: LayoutAsideOpenValue) {
       </template>
 
       <template #header>
-        <div class="layout-slot-props-demo__header">外层更新 leftAside / rightAside，并通过事件同步外部状态。</div>
+        <div class="layout-slot-props-demo__header">Header 区域</div>
       </template>
 
       <template #main>
-        <div class="layout-slot-props-demo__main">外层控制 open 和 expandedWidth，状态变化后通过事件同步。</div>
+        <div class="layout-slot-props-demo__main">Main 区域</div>
       </template>
 
       <template #right-aside>
diff --git a/docs/demos/layout/floating-controlled.vue b/docs/demos/layout/floating-controlled.vue
index 133879db9..bb15afb98 100644
--- a/docs/demos/layout/floating-controlled.vue
+++ b/docs/demos/layout/floating-controlled.vue
@@ -26,7 +26,6 @@ function updateFloatingState(nextState: LayoutFloatingState) {
       <TinyButton :reset-time="0" @click="open = !open">
         {{ open ? '关闭浮层' : '打开浮层' }}
       </TinyButton>
-      <span class="layout-floating-controlled-demo__tip">组件按 floatingState 渲染，变化通过事件通知外部。</span>
     </div>
 
     <TrLayout
@@ -72,10 +71,6 @@ function updateFloatingState(nextState: LayoutFloatingState) {
   gap: 8px;
 }
 
-.layout-floating-controlled-demo__tip {
-  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
-}
-
 .layout-floating-controlled-demo__header {
   display: flex;
   align-items: center;
diff --git a/docs/demos/layout/floating.vue b/docs/demos/layout/floating.vue
index 22ac49636..aad926f87 100644
--- a/docs/demos/layout/floating.vue
+++ b/docs/demos/layout/floating.vue
@@ -90,7 +90,7 @@ const floatingOptions = computed<LayoutFloatingOptions>(() => ({
         <div class="layout-floating-demo__main">
           <div class="layout-floating-demo__card">`defaultFloatingState` 只设置初始位置和大小。</div>
           <div class="layout-floating-demo__card">拖动顶部横条可移动浮层，拖动边缘手柄可调整大小。</div>
-          <div class="layout-floating-demo__card">切换 placement 或 offset 会重置初始位置，方便观察定位效果。</div>
+          <div class="layout-floating-demo__card">切换 placement 或 offset 后，浮层会按新的初始状态重新定位。</div>
         </div>
       </template>
     </TrLayout>
diff --git a/docs/src/components/layout.md b/docs/src/components/layout.md
index 36596d308..4ff96ce6d 100644
--- a/docs/src/components/layout.md
+++ b/docs/src/components/layout.md
@@ -6,13 +6,12 @@ outline: [1, 3]
 
 `Layout` 用来组织带有头部、主内容区、底部和左右侧栏的页面。
 
-它覆盖五类核心使用模型：
+它主要解决这些布局问题：
 
-- 页面骨架：通过 `left-aside`、`header`、`main`、`footer`、`right-aside` 组织区域内容
-- 布局模式：通过 `mode` 在普通布局和浮层布局之间切换
-- 侧栏配置：通过 `leftAside` / `rightAside` 控制侧栏行为
-- 浮层状态：通过 `defaultFloatingState` 或 `floatingState` 控制浮层位置和尺寸
-- 主区滚动：通过 `Layout.ProxyScrollbar` 将滚动条固定在主区边界
+- 页面结构分散，头部、主区、底部和左右侧栏需要反复拼装
+- 侧栏展开、收起、拖拽改宽和抽屉覆盖逻辑容易重复实现
+- 临时面板需要脱离文档流，并支持定位、拖拽和缩放
+- 主区内容很长时，原生滚动条位置不稳定，容易影响阅读和操作
 
 ## 基础布局
 
@@ -33,7 +32,7 @@ outline: [1, 3]
 
 侧栏由 `leftAside` / `rightAside` 控制，类型为 [`LayoutAsideProps`](#layout-aside-props)。
 
-侧栏内容通过 `left-aside` / `right-aside` 插槽提供。配置和内容分开后，业务可以只调整行为配置，而不影响插槽里的渲染结构。
+侧栏内容通过 `left-aside` / `right-aside` 插槽提供。配置和内容分开后，可以只调整行为配置，而不影响插槽里的渲染结构。
 
 ### 展示形态
 
@@ -46,12 +45,12 @@ outline: [1, 3]
 
 ### 收起行为
 
-`collapsedWidth` 控制收起后还保留多少宽度，`collapseEffect` 控制收起时的动画效果。
+`collapsedWidth` 控制收起后还保留多少宽度，仅 `dock` 模式生效；`collapseEffect` 控制收起时的动画效果。
 
 - `collapsedWidth > 0`：收起后保留一条窄栏
 - `collapsedWidth = 0`：收起后完全隐藏
-- `overlay`：内容留在原位
-- `slide`：内容跟着一起移动
+- `overlay`：侧栏外框保留，内容层不跟随宽度滑动
+- `slide`：侧栏内容随宽度一起滑出
 
 <demo
   vue="../../demos/layout/aside-collapse-effect.vue"
@@ -65,7 +64,7 @@ outline: [1, 3]
 
 <demo vue="../../demos/layout/aside-resizable.vue" title="宽度调整" description="拖动分隔线查看当前宽度和边界。" />
 
-### 状态控制
+### 侧栏受控状态
 
 `open` 和 `expandedWidth` 是受控值，状态变化后需要通过事件同步外部状态。
 
@@ -73,8 +72,8 @@ outline: [1, 3]
 
 <demo
   vue="../../demos/layout/aside-slot-props.vue"
-  title="状态控制"
-  description="用开关和滑块展示 leftAside、rightAside 和事件同步。"
+  title="侧栏受控状态"
+  description="外部控制侧栏开关和宽度。"
 />
 
 ## 浮层
@@ -88,22 +87,22 @@ outline: [1, 3]
 
 ### 非受控浮层
 
-非受控浮层通过 `defaultFloatingState` 设置初始位置和尺寸。拖动或缩放后，状态由组件内部维护，适合展示 `placement`、`offsetX`、`offsetY`、`draggable` 和 `resizable`。
+非受控浮层通过 `defaultFloatingState` 设置初始位置和尺寸。拖动或缩放后，状态由组件内部维护。
 
 <demo
   vue="../../demos/layout/floating.vue"
   title="非受控浮层"
-  description="打开时通过 defaultFloatingState 设置初始位置和大小。"
+  description="使用 defaultFloatingState 设置初始位置和大小。"
 />
 
 ### 受控浮层
 
-受控浮层以 `floatingState` 作为唯一状态源，组件按传入状态渲染；拖拽或缩放产生变化时，通过 `update:floatingState` 通知外部同步。位置固定或由外部规则决定时，建议关闭 `draggable`。
+受控浮层以 `floatingState` 作为唯一状态源，组件按传入状态渲染；内部交互产生变化时，通过 `update:floatingState` 通知外部同步。
 
 <demo
   vue="../../demos/layout/floating-controlled.vue"
   title="受控浮层"
-  description="通过 floatingState 控制位置和大小，并回显当前状态。"
+  description="由外部维护 floatingState。"
 />
 
 ### 浮层工作区
@@ -120,11 +119,11 @@ outline: [1, 3]
 
 `Layout.ProxyScrollbar` 用来代理主区滚动条，适合消息流、长内容阅读流和工作台主区。
 
-它解决的是“内容列居中后，原生滚动条跟着内容列移动，不再贴近主区右边界”的问题。使用时应让外层作为真实滚动宿主；如果内容需要居中或限宽，再交给内层容器处理。
+常见于内容列居中或限宽后，原生滚动条偏离主区右边界的场景。
 
-- `scrollTarget` 传实际滚动元素，或对应组件实例的 `ref`
-- 滚动宿主需自行设置尺寸、`box-sizing` 和滚动样式
-- `Layout.ProxyScrollbar` 会自动隐藏滚动宿主的原生滚动条
+- 外层作为真实滚动宿主，负责尺寸、`box-sizing` 和滚动样式
+- 内层负责内容居中、限宽和留白
+- `scrollTarget` 传真实滚动元素，`Layout.ProxyScrollbar` 会隐藏其原生滚动条
 
 ```css
 .scroll-host {
@@ -143,7 +142,7 @@ outline: [1, 3]
     '../../demos/layout/main-scroll-div.vue'
   ]"
   title="主区滚动"
-  description="演示内容区居中后，滚动条仍固定在主区右侧。"
+  description="内容区居中后，滚动条仍固定在主区右侧。"
 />
 
 ## Layout.AsideToggle
@@ -370,8 +369,6 @@ const scrollEl = ref<HTMLElement | null>(null)
 
 ### 内容与交互 {#layout-css-content}
 
-`Layout` 嵌入卡片、小容器或文档 demo 时，常需要把 `--tr-layout-main-min-width` 设为 `0`，否则主区默认最小宽度 `320px` 可能撑开布局。
-
 | 变量名 | 说明 |
 | ------ | ---- |
 | `--tr-layout-main-min-width` | 主区最小宽度 |

From 260ede91791ed0fa4947255cd07bd826ab474413 Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Tue, 7 Jul 2026 23:46:46 -0700
Subject: [PATCH 05/12] feat(docs): add layout mode and aside control demos to
 documentation

---
 ...de-slot-props.vue => aside-controlled.vue} |  20 +---
 docs/demos/layout/aside-modes.vue             |  56 ++--------
 docs/demos/layout/aside-toggle.vue            | 104 ++++++++++++++++++
 docs/demos/layout/mode.vue                    |  73 ++++++++++++
 docs/src/components/layout.md                 |  14 ++-
 5 files changed, 201 insertions(+), 66 deletions(-)
 rename docs/demos/layout/{aside-slot-props.vue => aside-controlled.vue} (85%)
 create mode 100644 docs/demos/layout/aside-toggle.vue
 create mode 100644 docs/demos/layout/mode.vue

diff --git a/docs/demos/layout/aside-slot-props.vue b/docs/demos/layout/aside-controlled.vue
similarity index 85%
rename from docs/demos/layout/aside-slot-props.vue
rename to docs/demos/layout/aside-controlled.vue
index 8779256f8..f506f2e80 100644
--- a/docs/demos/layout/aside-slot-props.vue
+++ b/docs/demos/layout/aside-controlled.vue
@@ -77,14 +77,7 @@ function updateRightAsideOpen(detail: LayoutAsideOpenValue) {
     >
       <template #left-aside>
         <div class="layout-slot-props-demo__aside">
-          <template v-if="leftOpen">
-            <p>左侧栏宽度：{{ leftExpandedWidth }}px</p>
-            <TrLayout.AsideToggle side="left" class="layout-slot-props-demo__button">
-              <template #default="{ isOpen }">
-                {{ isOpen ? '收起侧栏' : '展开侧栏' }}
-              </template>
-            </TrLayout.AsideToggle>
-          </template>
+          <p v-if="leftOpen">左侧栏宽度：{{ leftExpandedWidth }}px</p>
           <p v-else>左侧栏已关闭，请通过外部按钮重新展开。</p>
         </div>
       </template>
@@ -100,7 +93,7 @@ function updateRightAsideOpen(detail: LayoutAsideOpenValue) {
       <template #right-aside>
         <div class="layout-slot-props-demo__drawer">
           <p>右侧抽屉</p>
-          <TrLayout.AsideToggle side="right" class="layout-slot-props-demo__button"> 关闭抽屉 </TrLayout.AsideToggle>
+          <p>由外部按钮控制开关。</p>
         </div>
       </template>
     </TrLayout>
@@ -138,15 +131,6 @@ function updateRightAsideOpen(detail: LayoutAsideOpenValue) {
   font-weight: 600;
 }
 
-.layout-slot-props-demo__button {
-  min-height: 36px;
-  padding: 0 12px;
-  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
-  border-radius: 8px;
-  background: var(--vp-c-bg, #ffffff);
-  cursor: pointer;
-}
-
 .layout-slot-props-demo__range-wrap {
   display: inline-flex;
   align-items: center;
diff --git a/docs/demos/layout/aside-modes.vue b/docs/demos/layout/aside-modes.vue
index ebcb6dd68..bb5c2129c 100644
--- a/docs/demos/layout/aside-modes.vue
+++ b/docs/demos/layout/aside-modes.vue
@@ -4,13 +4,8 @@ import { TrLayout } from '@opentiny/tiny-robot'
 import { TinyButton } from '@opentiny/vue'
 import type { LayoutAsideOpenValue } from '@opentiny/tiny-robot'
 
-const leftOpen = ref(true)
 const rightOpen = ref(false)
 
-function updateLeftAside(detail: LayoutAsideOpenValue) {
-  leftOpen.value = detail.open
-}
-
 function updateRightAside(detail: LayoutAsideOpenValue) {
   rightOpen.value = detail.open
 }
@@ -19,40 +14,32 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
 <template>
   <div class="layout-aside-demo">
     <TrLayout
-      :left-aside="{ open: leftOpen, expandedWidth: 156, collapsedWidth: 56 }"
+      :left-aside="{ defaultOpen: true, defaultExpandedWidth: 156 }"
       :right-aside="{ mode: 'drawer', open: rightOpen }"
-      @left-aside-open-change="updateLeftAside"
       @right-aside-open-change="updateRightAside"
     >
       <template #left-aside>
-        <div v-if="leftOpen" class="layout-aside-demo__aside">
-          <TrLayout.AsideToggle side="left" class="layout-aside-demo__chip">收起侧栏</TrLayout.AsideToggle>
-          <div class="layout-aside-demo__chip">collapsedWidth: 56px</div>
-        </div>
-        <div v-else class="layout-aside-demo__rail">
-          <TrLayout.AsideToggle side="left" class="layout-aside-demo__rail-chip" aria-label="展开左侧栏">
-            栏
-          </TrLayout.AsideToggle>
-          <div class="layout-aside-demo__rail-chip">56</div>
-        </div>
+        <div class="layout-aside-demo__aside">Dock 区域</div>
       </template>
 
       <template #header>
         <div class="layout-aside-demo__header">
-          <span>侧栏模式</span>
-          <TinyButton :reset-time="0" @click="rightOpen = true">打开抽屉</TinyButton>
+          <span>Header 区域</span>
+          <TinyButton :reset-time="0" @click="rightOpen = !rightOpen">
+            {{ rightOpen ? '关闭抽屉' : '打开抽屉' }}
+          </TinyButton>
         </div>
       </template>
 
       <template #main>
-        <div class="layout-aside-demo__main">左侧是 `dock + collapsedWidth`，右侧是 `drawer`。</div>
+        <div class="layout-aside-demo__main">左侧 `dock` 始终参与布局，右侧 `drawer` 按需覆盖主区。</div>
       </template>
 
       <template #right-aside>
         <div class="layout-aside-demo__drawer layout-aside-demo__drawer-panel">
           <div>Drawer</div>
-          <div>点击遮罩或按钮关闭。</div>
-          <TrLayout.AsideToggle side="right" class="layout-aside-demo__chip">关闭抽屉</TrLayout.AsideToggle>
+          <div>打开后覆盖内容区，不占主布局宽度。</div>
+          <div>点击遮罩或顶部按钮关闭。</div>
         </div>
       </template>
     </TrLayout>
@@ -99,18 +86,10 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
 }
 
 .layout-aside-demo__aside,
-.layout-aside-demo__drawer,
-.layout-aside-demo__rail {
+.layout-aside-demo__drawer {
   display: grid;
   gap: 8px;
-}
-
-.layout-aside-demo__rail {
-  width: 56px;
-  height: 100%;
-  padding: 12px 8px;
-  box-sizing: border-box;
-  justify-items: center;
+  justify-content: center;
 }
 
 .layout-aside-demo__drawer {
@@ -122,25 +101,14 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
   color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
 }
 
-.layout-aside-demo__chip,
-.layout-aside-demo__rail-chip {
+.layout-aside-demo__chip {
   display: grid;
   place-items: center;
   border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
   background: var(--vp-c-bg, #ffffff);
   color: inherit;
-}
-
-.layout-aside-demo__chip {
   min-height: 36px;
   padding: 0 12px;
   border-radius: 8px;
 }
-
-.layout-aside-demo__rail-chip {
-  width: 40px;
-  min-height: 40px;
-  padding: 0;
-  border-radius: 8px;
-}
 </style>
diff --git a/docs/demos/layout/aside-toggle.vue b/docs/demos/layout/aside-toggle.vue
new file mode 100644
index 000000000..84fe58e45
--- /dev/null
+++ b/docs/demos/layout/aside-toggle.vue
@@ -0,0 +1,104 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+import type { LayoutAsideOpenValue } from '@opentiny/tiny-robot'
+
+const leftOpen = ref(true)
+
+function updateLeftAside(detail: LayoutAsideOpenValue) {
+  leftOpen.value = detail.open
+}
+</script>
+
+<template>
+  <div class="layout-aside-toggle-demo">
+    <TrLayout
+      :left-aside="{ defaultOpen: true, defaultExpandedWidth: 168, collapsedWidth: 56 }"
+      @left-aside-open-change="updateLeftAside"
+    >
+      <template #left-aside>
+        <div class="layout-aside-toggle-demo__aside" :class="{ 'is-rail': !leftOpen }">
+          <TrLayout.AsideToggle side="left" class="layout-aside-toggle-demo__toggle" aria-label="切换左侧栏">
+            <template #default="{ isOpen }">
+              <div :class="isOpen ? 'layout-aside-toggle-demo__chip' : 'layout-aside-toggle-demo__rail-chip'">
+                {{ isOpen ? '收起' : '展开' }}
+              </div>
+            </template>
+          </TrLayout.AsideToggle>
+        </div>
+      </template>
+
+      <template #main>
+        <div class="layout-aside-toggle-demo__main">按钮文案和形态直接使用 `isOpen` 插槽状态切换。</div>
+      </template>
+    </TrLayout>
+  </div>
+</template>
+
+<style scoped>
+.layout-aside-toggle-demo {
+  --tr-layout-height: 280px;
+  --tr-layout-main-min-width: 0;
+  --tr-layout-left-aside-bg: var(--vp-c-bg-alt, #f8fafc);
+  overflow: hidden;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 16px;
+}
+
+.layout-aside-toggle-demo__aside {
+  display: grid;
+  align-content: center;
+  gap: 8px;
+  height: 100%;
+  padding: 12px;
+  box-sizing: border-box;
+}
+
+.layout-aside-toggle-demo__toggle {
+  width: 100%;
+}
+
+.layout-aside-toggle-demo__chip,
+.layout-aside-toggle-demo__rail-chip {
+  display: grid;
+  place-items: center;
+  width: 100%;
+  box-sizing: border-box;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  background: var(--vp-c-bg, #ffffff);
+  color: inherit;
+}
+
+.layout-aside-toggle-demo__chip {
+  min-height: 36px;
+  padding: 0 12px;
+  border-radius: 8px;
+}
+
+.layout-aside-toggle-demo__rail-chip {
+  width: 40px;
+  min-height: 40px;
+  padding: 0;
+  border-radius: 8px;
+}
+
+.layout-aside-toggle-demo__aside.is-rail {
+  width: 56px;
+  padding: 12px 8px;
+  justify-items: center;
+}
+
+.layout-aside-toggle-demo__aside.is-rail .layout-aside-toggle-demo__toggle {
+  width: auto;
+}
+
+.layout-aside-toggle-demo__main {
+  display: grid;
+  place-items: center;
+  height: 100%;
+  background: var(--vp-c-bg, #ffffff);
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+  padding: 16px;
+  box-sizing: border-box;
+}
+</style>
diff --git a/docs/demos/layout/mode.vue b/docs/demos/layout/mode.vue
new file mode 100644
index 000000000..e2e3a7700
--- /dev/null
+++ b/docs/demos/layout/mode.vue
@@ -0,0 +1,73 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+import { TinyRadio, TinyRadioGroup } from '@opentiny/vue'
+import type { LayoutMode } from '@opentiny/tiny-robot'
+
+const mode = ref<LayoutMode>('normal')
+</script>
+
+<template>
+  <div class="layout-mode-demo">
+    <tiny-radio-group v-model="mode">
+      <tiny-radio label="normal">normal</tiny-radio>
+      <tiny-radio label="floating">floating</tiny-radio>
+    </tiny-radio-group>
+
+    <div class="layout-mode-demo__stage">
+      <TrLayout
+        class="layout-mode-demo__layout"
+        :mode="mode"
+        :default-floating-state="{ placement: 'center', width: 360, height: 220 }"
+        :floating-options="{ draggable: true, resizable: false }"
+      >
+        <template #header>
+          <div class="layout-mode-demo__header">{{ mode }}</div>
+        </template>
+
+        <template #main>
+          <div class="layout-mode-demo__main">
+            {{ mode === 'normal' ? '参与页面布局' : '挂载到 body 并悬浮显示' }}
+          </div>
+        </template>
+      </TrLayout>
+    </div>
+  </div>
+</template>
+
+<style>
+.layout-mode-demo__layout {
+  --tr-layout-height: 220px;
+  --tr-layout-main-min-width: 0;
+  --tr-layout-floating-radius: 12px;
+}
+</style>
+
+<style scoped>
+.layout-mode-demo {
+  display: grid;
+  gap: 12px;
+}
+
+.layout-mode-demo__stage {
+  position: relative;
+  height: 260px;
+  overflow: hidden;
+  border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  border-radius: 16px;
+}
+
+.layout-mode-demo__header {
+  padding: 12px 16px;
+  border-bottom: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
+  background: var(--vp-c-bg-soft, #f6f8fa);
+  font-weight: 600;
+}
+
+.layout-mode-demo__main {
+  display: grid;
+  place-items: center;
+  height: 100%;
+  background: var(--vp-c-bg, #ffffff);
+}
+</style>
diff --git a/docs/src/components/layout.md b/docs/src/components/layout.md
index 4ff96ce6d..6f4addfaf 100644
--- a/docs/src/components/layout.md
+++ b/docs/src/components/layout.md
@@ -28,6 +28,8 @@ outline: [1, 3]
 
 普通页面不需要显式传 `mode`。需要临时面板、悬浮工作台或可拖拽窗口时，再使用 `mode="floating"`。
 
+<demo vue="../../demos/layout/mode.vue" title="布局模式" description="切换 normal 和 floating 查看布局形态差异。" />
+
 ## 侧栏
 
 侧栏由 `leftAside` / `rightAside` 控制，类型为 [`LayoutAsideProps`](#layout-aside-props)。
@@ -36,6 +38,8 @@ outline: [1, 3]
 
 ### 展示形态
 
+`LayoutAsideProps.mode` 控制侧栏展示形态。
+
 - `dock`：占据页面空间
 - `drawer`：覆盖在内容上方
 
@@ -64,15 +68,15 @@ outline: [1, 3]
 
 <demo vue="../../demos/layout/aside-resizable.vue" title="宽度调整" description="拖动分隔线查看当前宽度和边界。" />
 
-### 侧栏受控状态
+### 侧栏受控
 
 `open` 和 `expandedWidth` 是受控值，状态变化后需要通过事件同步外部状态。
 
 `defaultOpen` 和 `defaultExpandedWidth` 只提供初始值，适合不需要外部持续控制的场景。
 
 <demo
-  vue="../../demos/layout/aside-slot-props.vue"
-  title="侧栏受控状态"
+  vue="../../demos/layout/aside-controlled.vue"
+  title="侧栏受控"
   description="外部控制侧栏开关和宽度。"
 />
 
@@ -145,12 +149,14 @@ outline: [1, 3]
   description="内容区居中后，滚动条仍固定在主区右侧。"
 />
 
-## Layout.AsideToggle
+## 侧栏内控制
 
 `Layout.AsideToggle` 是内置侧栏开关按钮，只能在 `Layout` 内部使用，通常放在 `left-aside` / `right-aside` 插槽中。
 
 它适合让侧栏内容自己控制展开和收起，默认插槽提供 `{ isOpen }`。自定义按钮内容时，应保留可读文本或补充 `aria-label`。
 
+<demo vue="../../demos/layout/aside-toggle.vue" title="侧栏内控制" description="在侧栏内容中使用 AsideToggle 触发当前侧栏开关。" />
+
 ## Props
 
 ### Layout {#layout-props}

From 19b48e1fc70ffc365f818c0a2f06b3171951ab4d Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Wed, 8 Jul 2026 00:51:57 -0700
Subject: [PATCH 06/12] feat(docs): enhance layout mode demo and update
 documentation for clarity

---
 docs/demos/layout/mode.vue    | 28 +++++++++++++++++++++-------
 docs/src/components/layout.md | 12 ++++++------
 2 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/docs/demos/layout/mode.vue b/docs/demos/layout/mode.vue
index e2e3a7700..2b2f786c9 100644
--- a/docs/demos/layout/mode.vue
+++ b/docs/demos/layout/mode.vue
@@ -1,10 +1,29 @@
 <script setup lang="ts">
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
 import { TinyRadio, TinyRadioGroup } from '@opentiny/vue'
 import type { LayoutMode } from '@opentiny/tiny-robot'
 
 const mode = ref<LayoutMode>('normal')
+
+const layoutProps = computed(() =>
+  mode.value === 'floating'
+    ? {
+        mode: 'floating' as const,
+        defaultFloatingState: {
+          placement: 'center' as const,
+          width: 220,
+          height: 200,
+        },
+        floatingOptions: {
+          draggable: true,
+          resizable: true,
+        },
+      }
+    : {
+        mode: 'normal' as const,
+      },
+)
 </script>
 
 <template>
@@ -15,12 +34,7 @@ const mode = ref<LayoutMode>('normal')
     </tiny-radio-group>
 
     <div class="layout-mode-demo__stage">
-      <TrLayout
-        class="layout-mode-demo__layout"
-        :mode="mode"
-        :default-floating-state="{ placement: 'center', width: 360, height: 220 }"
-        :floating-options="{ draggable: true, resizable: false }"
-      >
+      <TrLayout :key="mode" v-bind="layoutProps" class="layout-mode-demo__layout">
         <template #header>
           <div class="layout-mode-demo__header">{{ mode }}</div>
         </template>
diff --git a/docs/src/components/layout.md b/docs/src/components/layout.md
index 6f4addfaf..cec4e7c2d 100644
--- a/docs/src/components/layout.md
+++ b/docs/src/components/layout.md
@@ -119,9 +119,9 @@ outline: [1, 3]
   description="在浮层里组合左右 drawer，适合临时工作区、对话面板或侧边操作台。"
 />
 
-## 主区滚动
+## 代理滚动条
 
-`Layout.ProxyScrollbar` 用来代理主区滚动条，适合消息流、长内容阅读流和工作台主区。
+`Layout.ProxyScrollbar` 是代理滚动条，适合消息流、长内容阅读流和工作台主区。
 
 常见于内容列居中或限宽后，原生滚动条偏离主区右边界的场景。
 
@@ -145,17 +145,17 @@ outline: [1, 3]
     '../../demos/layout/main-scroll-bubble.vue',
     '../../demos/layout/main-scroll-div.vue'
   ]"
-  title="主区滚动"
+  title="代理滚动条"
   description="内容区居中后，滚动条仍固定在主区右侧。"
 />
 
-## 侧栏内控制
+## 侧栏开关
 
-`Layout.AsideToggle` 是内置侧栏开关按钮，只能在 `Layout` 内部使用，通常放在 `left-aside` / `right-aside` 插槽中。
+`Layout.AsideToggle` 是内置侧栏开关按钮，可以在 `Layout` 内部任意区域使用。
 
 它适合让侧栏内容自己控制展开和收起，默认插槽提供 `{ isOpen }`。自定义按钮内容时，应保留可读文本或补充 `aria-label`。
 
-<demo vue="../../demos/layout/aside-toggle.vue" title="侧栏内控制" description="在侧栏内容中使用 AsideToggle 触发当前侧栏开关。" />
+<demo vue="../../demos/layout/aside-toggle.vue" title="侧栏开关" description="在侧栏内容中使用 AsideToggle 触发当前侧栏开关。" />
 
 ## Props
 

From 9133b1816e4771dba620ab01fc451a9d2e140ddc Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Wed, 8 Jul 2026 04:11:45 -0700
Subject: [PATCH 07/12] feat(docs): update layout documentation and types to
 use LayoutAsideOptions

---
 docs/demos/layout/aside-collapse-effect.vue   |  4 +-
 docs/demos/layout/aside-controlled.vue        |  6 +-
 docs/demos/layout/aside-resizable.vue         |  4 +-
 docs/demos/layout/floating-controlled.vue     | 86 +++++++++++++++-
 docs/demos/layout/floating-panels.vue         | 34 +++----
 docs/demos/layout/floating.vue                | 98 +++----------------
 docs/src/components/layout.md                 | 66 ++++++-------
 .../composables/useLayoutAsideStates.ts       |  8 +-
 packages/components/src/layout/index.type.ts  |  6 +-
 9 files changed, 155 insertions(+), 157 deletions(-)

diff --git a/docs/demos/layout/aside-collapse-effect.vue b/docs/demos/layout/aside-collapse-effect.vue
index 14ff3f606..42ae11658 100644
--- a/docs/demos/layout/aside-collapse-effect.vue
+++ b/docs/demos/layout/aside-collapse-effect.vue
@@ -2,13 +2,13 @@
 import { computed, ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
 import { TinyRadio, TinyRadioGroup, TinySlider, TinySwitch } from '@opentiny/vue'
-import type { LayoutAsideCollapseEffect, LayoutAsideProps } from '@opentiny/tiny-robot'
+import type { LayoutAsideCollapseEffect, LayoutAsideOptions } from '@opentiny/tiny-robot'
 
 const collapseEffect = ref<LayoutAsideCollapseEffect>('overlay')
 const collapsedWidth = ref(72)
 const open = ref(true)
 
-const leftAside = computed<LayoutAsideProps>(() => ({
+const leftAside = computed<LayoutAsideOptions>(() => ({
   open: open.value,
   expandedWidth: 176,
   collapsedWidth: collapsedWidth.value,
diff --git a/docs/demos/layout/aside-controlled.vue b/docs/demos/layout/aside-controlled.vue
index f506f2e80..22f5babbc 100644
--- a/docs/demos/layout/aside-controlled.vue
+++ b/docs/demos/layout/aside-controlled.vue
@@ -2,7 +2,7 @@
 import { computed, ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
 import { TinyButton, TinySlider } from '@opentiny/vue'
-import type { LayoutAsideProps, LayoutAsideOpenValue, LayoutAsideResizeValue } from '@opentiny/tiny-robot'
+import type { LayoutAsideOptions, LayoutAsideOpenValue, LayoutAsideResizeValue } from '@opentiny/tiny-robot'
 
 const leftOpen = ref(true)
 const leftExpandedWidth = ref(220)
@@ -10,7 +10,7 @@ const leftWidthMin = 160
 const leftWidthMax = 320
 const rightOpen = ref(false)
 
-const leftAside = computed<LayoutAsideProps>(() => ({
+const leftAside = computed<LayoutAsideOptions>(() => ({
   open: leftOpen.value,
   expandedWidth: leftExpandedWidth.value,
   collapsedWidth: 0,
@@ -19,7 +19,7 @@ const leftAside = computed<LayoutAsideProps>(() => ({
   resizable: true,
 }))
 
-const rightAside = computed<LayoutAsideProps>(() => ({
+const rightAside = computed<LayoutAsideOptions>(() => ({
   mode: 'drawer',
   open: rightOpen.value,
 }))
diff --git a/docs/demos/layout/aside-resizable.vue b/docs/demos/layout/aside-resizable.vue
index 06c8c38d9..cadcca616 100644
--- a/docs/demos/layout/aside-resizable.vue
+++ b/docs/demos/layout/aside-resizable.vue
@@ -1,13 +1,13 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
-import type { LayoutAsideProps, LayoutAsideResizeValue } from '@opentiny/tiny-robot'
+import type { LayoutAsideOptions, LayoutAsideResizeValue } from '@opentiny/tiny-robot'
 
 const minExpandedWidth = 160
 const maxExpandedWidth = 320
 const expandedWidth = ref(220)
 
-const leftAside = computed<LayoutAsideProps>(() => ({
+const leftAside = computed<LayoutAsideOptions>(() => ({
   defaultOpen: true,
   expandedWidth: expandedWidth.value,
   minExpandedWidth,
diff --git a/docs/demos/layout/floating-controlled.vue b/docs/demos/layout/floating-controlled.vue
index bb15afb98..b50363924 100644
--- a/docs/demos/layout/floating-controlled.vue
+++ b/docs/demos/layout/floating-controlled.vue
@@ -1,10 +1,14 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
-import { TinyButton } from '@opentiny/vue'
-import type { LayoutFloatingState } from '@opentiny/tiny-robot'
+import { TinyBaseSelect, TinyButton, TinyNumeric, TinyOption } from '@opentiny/vue'
+import type { LayoutFloatingOptions, LayoutFloatingState } from '@opentiny/tiny-robot'
+
+type FloatingPlacement = LayoutFloatingState['placement']
 
 const open = ref(false)
+const placements: FloatingPlacement[] = ['top-left', 'top-right', 'bottom-left', 'bottom-right', 'center']
+
 const floatingState = ref<LayoutFloatingState>({
   placement: 'top-right',
   offsetX: 0,
@@ -13,6 +17,14 @@ const floatingState = ref<LayoutFloatingState>({
   height: 360,
 })
 
+const floatingOptions: LayoutFloatingOptions = {
+  draggable: true,
+  resizable: true,
+  minWidth: 360,
+  maxWidth: 720,
+  minHeight: 260,
+}
+
 const stateText = computed(() => JSON.stringify(floatingState.value, null, 2))
 
 function updateFloatingState(nextState: LayoutFloatingState) {
@@ -28,12 +40,43 @@ function updateFloatingState(nextState: LayoutFloatingState) {
       </TinyButton>
     </div>
 
+    <div class="layout-floating-controlled-demo__controls">
+      <label class="layout-floating-controlled-demo__field">
+        <span>placement</span>
+        <TinyBaseSelect v-model="floatingState.placement" class="layout-floating-controlled-demo__select">
+          <TinyOption v-for="item in placements" :key="item" :label="item" :value="item" />
+        </TinyBaseSelect>
+      </label>
+
+      <label class="layout-floating-controlled-demo__field">
+        <span>offsetX</span>
+        <TinyNumeric v-model="floatingState.offsetX" class="layout-floating-controlled-demo__numeric" />
+      </label>
+
+      <label class="layout-floating-controlled-demo__field">
+        <span>offsetY</span>
+        <TinyNumeric v-model="floatingState.offsetY" class="layout-floating-controlled-demo__numeric" />
+      </label>
+
+      <label class="layout-floating-controlled-demo__field">
+        <span>width</span>
+        <TinyNumeric v-model="floatingState.width" class="layout-floating-controlled-demo__numeric" />
+      </label>
+
+      <label class="layout-floating-controlled-demo__field">
+        <span>height</span>
+        <TinyNumeric v-model="floatingState.height" class="layout-floating-controlled-demo__numeric" />
+      </label>
+    </div>
+
+    <pre class="layout-floating-controlled-demo__state">{{ stateText }}</pre>
+
     <TrLayout
       v-if="open"
       class="layout-floating-controlled-demo__layout"
       mode="floating"
       :floating-state="floatingState"
-      :floating-options="{ draggable: false, resizable: true, minWidth: 360, maxWidth: 720, minHeight: 260 }"
+      :floating-options="floatingOptions"
       @update:floating-state="updateFloatingState"
     >
       <template #header>
@@ -45,7 +88,10 @@ function updateFloatingState(nextState: LayoutFloatingState) {
 
       <template #main>
         <div class="layout-floating-controlled-demo__main">
-          <pre class="layout-floating-controlled-demo__state">{{ stateText }}</pre>
+          <div class="layout-floating-controlled-demo__card">当前示例由外部维护 <code>floatingState</code>。</div>
+          <div class="layout-floating-controlled-demo__card">
+            拖拽或缩放后，变化会通过 <code>update:floatingState</code> 回传到外部状态。
+          </div>
         </div>
       </template>
     </TrLayout>
@@ -71,6 +117,28 @@ function updateFloatingState(nextState: LayoutFloatingState) {
   gap: 8px;
 }
 
+.layout-floating-controlled-demo__controls {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.layout-floating-controlled-demo__field {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
+.layout-floating-controlled-demo__select {
+  width: 148px;
+}
+
+.layout-floating-controlled-demo__numeric {
+  width: 104px;
+}
+
 .layout-floating-controlled-demo__header {
   display: flex;
   align-items: center;
@@ -82,13 +150,21 @@ function updateFloatingState(nextState: LayoutFloatingState) {
 }
 
 .layout-floating-controlled-demo__main {
+  display: grid;
+  gap: 12px;
   padding: 16px;
 }
 
+.layout-floating-controlled-demo__card {
+  padding: 12px 14px;
+  border-radius: 12px;
+  background: var(--vp-c-bg-soft, #f6f8fa);
+  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
+}
+
 .layout-floating-controlled-demo__state {
   box-sizing: border-box;
   margin: 0;
-  min-height: 100%;
   padding: 12px;
   border-radius: 8px;
   overflow: auto;
diff --git a/docs/demos/layout/floating-panels.vue b/docs/demos/layout/floating-panels.vue
index 3814d39bb..46c3e935d 100644
--- a/docs/demos/layout/floating-panels.vue
+++ b/docs/demos/layout/floating-panels.vue
@@ -5,7 +5,6 @@ import { TinyButton } from '@opentiny/vue'
 import type { LayoutAsideOpenValue, LayoutFloatingOptions, LayoutFloatingState } from '@opentiny/tiny-robot'
 
 const open = ref(false)
-const leftOpen = ref(false)
 const rightOpen = ref(false)
 
 const defaultFloatingState: LayoutFloatingState = {
@@ -24,10 +23,6 @@ const floatingOptions: LayoutFloatingOptions = {
   minHeight: 320,
 }
 
-function updateLeftAside(detail: LayoutAsideOpenValue) {
-  leftOpen.value = detail.open
-}
-
 function updateRightAside(detail: LayoutAsideOpenValue) {
   rightOpen.value = detail.open
 }
@@ -47,16 +42,14 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
       mode="floating"
       :default-floating-state="defaultFloatingState"
       :floating-options="floatingOptions"
-      :left-aside="{ mode: 'drawer', open: leftOpen }"
+      :left-aside="{ mode: 'dock', defaultOpen: true, defaultExpandedWidth: 208 }"
       :right-aside="{ mode: 'drawer', open: rightOpen }"
-      @left-aside-open-change="updateLeftAside"
       @right-aside-open-change="updateRightAside"
     >
       <template #left-aside>
-        <div class="layout-floating-panels-demo__drawer">
-          <div class="layout-floating-panels-demo__drawer-title">左侧抽屉</div>
-          <div>适合放筛选、导航或补充信息。</div>
-          <TrLayout.AsideToggle side="left" class="layout-floating-panels-demo__chip">关闭抽屉</TrLayout.AsideToggle>
+        <div class="layout-floating-panels-demo__aside">
+          <div class="layout-floating-panels-demo__aside-title">左侧导航栏</div>
+          <div>使用 dock 常驻显示，适合放目录、导航或上下文信息。</div>
         </div>
       </template>
 
@@ -64,7 +57,6 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
         <div class="layout-floating-panels-demo__header">
           <strong>浮层工作区</strong>
           <div class="layout-floating-panels-demo__actions">
-            <TinyButton :reset-time="0" @click="leftOpen = true">打开左抽屉</TinyButton>
             <TinyButton :reset-time="0" @click="rightOpen = true">打开右抽屉</TinyButton>
           </div>
         </div>
@@ -72,15 +64,16 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
 
       <template #main>
         <div class="layout-floating-panels-demo__main">
-          <div class="layout-floating-panels-demo__card">左右两侧都使用 drawer，需要时再展开，不占主区宽度。</div>
-          <div class="layout-floating-panels-demo__card">整个浮层仍可拖拽、缩放，适合临时工作区或对话面板。</div>
+          <div class="layout-floating-panels-demo__card">左侧使用 dock，保留常驻导航区并占据浮层宽度。</div>
+          <div class="layout-floating-panels-demo__card">右侧使用 drawer，需要时展开，不占主区宽度。</div>
+          <div class="layout-floating-panels-demo__card">整个浮层仍可拖拽、缩放，适合组合常驻导航和临时操作面板。</div>
         </div>
       </template>
 
       <template #right-aside>
-        <div class="layout-floating-panels-demo__drawer">
-          <div class="layout-floating-panels-demo__drawer-title">右侧抽屉</div>
-          <div>点击遮罩或按钮都可以关闭。</div>
+        <div class="layout-floating-panels-demo__aside">
+          <div class="layout-floating-panels-demo__aside-title">右侧操作抽屉</div>
+          <div>按需展开，不占主区宽度，适合放操作表单或补充面板。</div>
           <TrLayout.AsideToggle side="right" class="layout-floating-panels-demo__chip">关闭抽屉</TrLayout.AsideToggle>
         </div>
       </template>
@@ -118,9 +111,6 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
   border: 1px solid var(--vp-c-divider, var(--tr-border-color, #dcdfe6));
   background: var(--vp-c-bg, #ffffff);
   color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
-}
-
-.layout-floating-panels-demo__chip {
   min-height: 36px;
   padding: 0 12px;
   border-radius: 8px;
@@ -136,7 +126,7 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
 }
 
 .layout-floating-panels-demo__main,
-.layout-floating-panels-demo__drawer {
+.layout-floating-panels-demo__aside {
   display: grid;
   align-content: start;
   gap: 12px;
@@ -156,7 +146,7 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
   background: var(--vp-c-bg-soft, #f6f8fa);
 }
 
-.layout-floating-panels-demo__drawer-title {
+.layout-floating-panels-demo__aside-title {
   font-weight: 600;
   color: var(--vp-c-text-1, var(--tr-text-primary, #1f2329));
 }
diff --git a/docs/demos/layout/floating.vue b/docs/demos/layout/floating.vue
index aad926f87..c9a4ca5bb 100644
--- a/docs/demos/layout/floating.vue
+++ b/docs/demos/layout/floating.vue
@@ -1,36 +1,26 @@
 <script setup lang="ts">
-import { computed, ref } from 'vue'
+import { ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
-import { TinyBaseSelect, TinyButton, TinyNumeric, TinyOption, TinySwitch } from '@opentiny/vue'
+import { TinyButton } from '@opentiny/vue'
 import type { LayoutFloatingOptions, LayoutFloatingState } from '@opentiny/tiny-robot'
 
-type FloatingPlacement = LayoutFloatingState['placement']
-
 const open = ref(false)
-const placement = ref<FloatingPlacement>('top-right')
-const offsetX = ref(0)
-const offsetY = ref(0)
-const draggable = ref(true)
-const resizable = ref(true)
-
-const placements: FloatingPlacement[] = ['top-left', 'top-right', 'bottom-left', 'bottom-right', 'center']
 
-const defaultFloatingState = computed<LayoutFloatingState>(() => ({
-  placement: placement.value,
-  offsetX: offsetX.value,
-  offsetY: offsetY.value,
+const defaultFloatingState: LayoutFloatingState = {
+  placement: 'top-right',
+  offsetX: 0,
+  offsetY: 0,
   width: 520,
   height: 360,
-}))
-
-const floatingStateKey = computed(() => `${placement.value}-${offsetX.value}-${offsetY.value}`)
+}
 
-const floatingOptions = computed<LayoutFloatingOptions>(() => ({
-  draggable: draggable.value,
-  resizable: resizable.value,
+const floatingOptions: LayoutFloatingOptions = {
+  draggable: true,
+  resizable: true,
   minWidth: 360,
   maxWidth: 680,
-}))
+  minHeight: 260,
+}
 </script>
 
 <template>
@@ -39,41 +29,10 @@ const floatingOptions = computed<LayoutFloatingOptions>(() => ({
       <TinyButton :reset-time="0" @click="open = !open">
         {{ open ? '关闭浮层' : '打开浮层' }}
       </TinyButton>
-      <span class="layout-floating-demo__tip">非受控浮层会在内部维护拖拽和缩放后的状态。</span>
-    </div>
-
-    <div class="layout-floating-demo__controls">
-      <label class="layout-floating-demo__field">
-        <span>placement</span>
-        <TinyBaseSelect v-model="placement" class="layout-floating-demo__select">
-          <TinyOption v-for="item in placements" :key="item" :label="item" :value="item" />
-        </TinyBaseSelect>
-      </label>
-
-      <label class="layout-floating-demo__field">
-        <span>offsetX</span>
-        <TinyNumeric v-model="offsetX" class="layout-floating-demo__numeric" />
-      </label>
-
-      <label class="layout-floating-demo__field">
-        <span>offsetY</span>
-        <TinyNumeric v-model="offsetY" class="layout-floating-demo__numeric" />
-      </label>
-
-      <label class="layout-floating-demo__field">
-        <span>draggable</span>
-        <TinySwitch v-model="draggable" />
-      </label>
-
-      <label class="layout-floating-demo__field">
-        <span>resizable</span>
-        <TinySwitch v-model="resizable" />
-      </label>
     </div>
 
     <TrLayout
       v-if="open"
-      :key="floatingStateKey"
       class="layout-floating-demo__layout"
       mode="floating"
       :default-floating-state="defaultFloatingState"
@@ -81,16 +40,15 @@ const floatingOptions = computed<LayoutFloatingOptions>(() => ({
     >
       <template #header>
         <div class="layout-floating-demo__header">
-          <strong>浮层布局</strong>
+          <strong>非受控浮层</strong>
           <TinyButton :reset-time="0" size="small" @click="open = false">关闭</TinyButton>
         </div>
       </template>
 
       <template #main>
         <div class="layout-floating-demo__main">
-          <div class="layout-floating-demo__card">`defaultFloatingState` 只设置初始位置和大小。</div>
-          <div class="layout-floating-demo__card">拖动顶部横条可移动浮层，拖动边缘手柄可调整大小。</div>
-          <div class="layout-floating-demo__card">切换 placement 或 offset 后，浮层会按新的初始状态重新定位。</div>
+          <div class="layout-floating-demo__card">当前示例只设置初始位置和尺寸。</div>
+          <div class="layout-floating-demo__card">拖拽或缩放后，位置和尺寸由组件内部维护。</div>
         </div>
       </template>
     </TrLayout>
@@ -116,32 +74,6 @@ const floatingOptions = computed<LayoutFloatingOptions>(() => ({
   gap: 8px;
 }
 
-.layout-floating-demo__controls {
-  display: flex;
-  align-items: center;
-  flex-wrap: wrap;
-  gap: 8px;
-}
-
-.layout-floating-demo__tip {
-  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
-}
-
-.layout-floating-demo__field {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  color: var(--vp-c-text-2, var(--tr-text-secondary, #4e5969));
-}
-
-.layout-floating-demo__select {
-  width: 148px;
-}
-
-.layout-floating-demo__numeric {
-  width: 104px;
-}
-
 .layout-floating-demo__main {
   display: grid;
   gap: 12px;
diff --git a/docs/src/components/layout.md b/docs/src/components/layout.md
index cec4e7c2d..e89c6e02b 100644
--- a/docs/src/components/layout.md
+++ b/docs/src/components/layout.md
@@ -4,41 +4,39 @@ outline: [1, 3]
 
 # Layout 布局
 
-`Layout` 用来组织带有头部、主内容区、底部和左右侧栏的页面。
+`Layout` 是面向 AI 应用页面的通用布局组件，适合搭建聊天页、工作台和多面板操作界面。
 
-它主要解决这些布局问题：
+它提供以下能力：
 
-- 页面结构分散，头部、主区、底部和左右侧栏需要反复拼装
-- 侧栏展开、收起、拖拽改宽和抽屉覆盖逻辑容易重复实现
-- 临时面板需要脱离文档流，并支持定位、拖拽和缩放
-- 主区内容很长时，原生滚动条位置不稳定，容易影响阅读和操作
+- 页面骨架：统一组织头部、主区、底部与左右侧栏
+- 侧栏交互：支持展开、收起、拖拽改宽和 `drawer` 覆盖
+- 浮层布局：支持定位、拖拽和缩放
+- 主区滚动代理：适用于内容列居中或限宽后，原生滚动条偏离主区右边界的场景
 
 ## 基础布局
 
-`Layout` 用于定义页面结构，各区域的具体内容通过插槽提供。
+`Layout` 提供 `left-aside`、`header`、`main`、`footer` 和 `right-aside` 五个区域插槽，用于编排页面结构。
 
 <demo vue="../../demos/layout/basic.vue" title="基础布局" description="最小布局示例。" />
 
 ## 布局模式
 
-`mode` 控制 `Layout` 的整体形态。
+`mode` 控制 `Layout` 的整体形态，默认值为 `normal`。
 
-- `normal`：普通页面骨架，参与原始页面布局
-- `floating`：悬浮工作区，脱离原始页面布局并挂载到 `body`
-
-普通页面不需要显式传 `mode`。需要临时面板、悬浮工作台或可拖拽窗口时，再使用 `mode="floating"`。
+- `normal`：普通页面骨架，参与文档流布局
+- `floating`：悬浮布局，脱离文档流，支持用作悬浮工作区或可拖拽窗口
 
 <demo vue="../../demos/layout/mode.vue" title="布局模式" description="切换 normal 和 floating 查看布局形态差异。" />
 
 ## 侧栏
 
-侧栏由 `leftAside` / `rightAside` 控制，类型为 [`LayoutAsideProps`](#layout-aside-props)。
+侧栏由 `leftAside` / `rightAside` 控制，类型为 [`LayoutAsideOptions`](#layout-aside-options)。
 
 侧栏内容通过 `left-aside` / `right-aside` 插槽提供。配置和内容分开后，可以只调整行为配置，而不影响插槽里的渲染结构。
 
 ### 展示形态
 
-`LayoutAsideProps.mode` 控制侧栏展示形态。
+`LayoutAsideOptions.mode` 控制侧栏展示形态，默认值为 `dock`。
 
 - `dock`：占据页面空间
 - `drawer`：覆盖在内容上方
@@ -82,41 +80,44 @@ outline: [1, 3]
 
 ## 浮层
 
-浮层只在 `mode="floating"` 时生效，适合临时面板、悬浮工作区或对话面板。
-
-`defaultFloatingState` 和 `floatingState` 不要同时传入：
+浮层相关配置和交互只在浮层模式下生效。
 
 - `defaultFloatingState`：非受控初始状态，只在首次挂载时读取
 - `floatingState`：受控状态，由外部维护当前位置和尺寸
+- `floatingOptions`：浮层行为配置，用于拖拽、缩放和尺寸约束，不参与状态控制
+
+> `defaultFloatingState` 和 `floatingState` 不要同时传入
 
 ### 非受控浮层
 
-非受控浮层通过 `defaultFloatingState` 设置初始位置和尺寸。拖动或缩放后，状态由组件内部维护。
+非受控浮层通过 `defaultFloatingState` 设置初始位置和尺寸。
 
 <demo
   vue="../../demos/layout/floating.vue"
   title="非受控浮层"
-  description="使用 defaultFloatingState 设置初始位置和大小。"
+  description="只设置初始位置和大小，后续由组件内部维护。"
 />
 
 ### 受控浮层
 
-受控浮层以 `floatingState` 作为唯一状态源，组件按传入状态渲染；内部交互产生变化时，通过 `update:floatingState` 通知外部同步。
+受控浮层以 `floatingState` 作为唯一状态源，组件始终按外部状态渲染；
+
+后续通过 `update:floatingState` 通知外部同步。
 
 <demo
   vue="../../demos/layout/floating-controlled.vue"
   title="受控浮层"
-  description="由外部维护 floatingState。"
+  description="由外部维护位置和尺寸状态。"
 />
 
-### 浮层工作区
+### 浮层模式下的侧栏
 
-浮层里同样可以放入侧栏、头部和主区。常见用法是把左右两侧都做成按需展开的 drawer。
+浮层里同样可以放入侧栏、头部和主区。
 
 <demo
   vue="../../demos/layout/floating-panels.vue"
-  title="浮层工作区"
-  description="在浮层里组合左右 drawer，适合临时工作区、对话面板或侧边操作台。"
+  title="浮层模式下的侧栏"
+  description="在浮层里组合常驻侧栏和按需抽屉。"
 />
 
 ## 代理滚动条
@@ -125,9 +126,8 @@ outline: [1, 3]
 
 常见于内容列居中或限宽后，原生滚动条偏离主区右边界的场景。
 
-- 外层作为真实滚动宿主，负责尺寸、`box-sizing` 和滚动样式
-- 内层负责内容居中、限宽和留白
-- `scrollTarget` 传真实滚动元素，`Layout.ProxyScrollbar` 会隐藏其原生滚动条
+- 将实际承担滚动的元素传给 `scrollTarget`。
+- 为使代理滚动条正确生效，该滚动元素需要具备以下基础样式。
 
 ```css
 .scroll-host {
@@ -153,7 +153,7 @@ outline: [1, 3]
 
 `Layout.AsideToggle` 是内置侧栏开关按钮，可以在 `Layout` 内部任意区域使用。
 
-它适合让侧栏内容自己控制展开和收起，默认插槽提供 `{ isOpen }`。自定义按钮内容时，应保留可读文本或补充 `aria-label`。
+它给侧栏内容提供控制展开和收起的能力，默认插槽提供 `{ isOpen }`。
 
 <demo vue="../../demos/layout/aside-toggle.vue" title="侧栏开关" description="在侧栏内容中使用 AsideToggle 触发当前侧栏开关。" />
 
@@ -164,11 +164,11 @@ outline: [1, 3]
 | 属性名 | 说明 | 类型 | 默认值 |
 | ------ | ---- | ---- | ------ |
 | `mode` | 布局模式；`normal` 参与普通布局，`floating` 会脱离普通布局，不占原来的位置空间 | `'normal' \| 'floating'` | `'normal'` |
-| `leftAside` | 左侧栏配置 | [`LayoutAsideProps`](#layout-aside-props) | `-` |
-| `rightAside` | 右侧栏配置 | [`LayoutAsideProps`](#layout-aside-props) | `-` |
+| `leftAside` | 左侧栏配置 | [`LayoutAsideOptions`](#layout-aside-options) | `-` |
+| `rightAside` | 右侧栏配置 | [`LayoutAsideOptions`](#layout-aside-options) | `-` |
 | `floatingState` | 受控浮层状态，需配合 `update:floatingState` 同步外部状态；不要和 `defaultFloatingState` 同时传入 | [`LayoutFloatingState`](#layout-floating-state) | `-` |
 | `defaultFloatingState` | 非受控浮层初始状态，仅首次挂载读取一次；不要和 `floatingState` 同时传入 | [`LayoutFloatingState`](#layout-floating-state) | `-` |
-| `floatingOptions` | 浮层拖拽、缩放和尺寸约束配置 | [`LayoutFloatingOptions`](#layout-floating-options) | `-` |
+| `floatingOptions` | 浮层行为配置，包括拖拽、缩放和尺寸约束；不参与状态控制 | [`LayoutFloatingOptions`](#layout-floating-options) | `-` |
 
 ### Layout.ProxyScrollbar {#layout-proxy-scrollbar-props}
 
@@ -255,7 +255,7 @@ function trackAsideChange(detail: { side: 'left' | 'right'; open: boolean }) {
 
 ## Types {#types}
 
-### LayoutAsideProps {#layout-aside-props}
+### LayoutAsideOptions {#layout-aside-options}
 
 | 字段 | 说明 | 类型 | 默认值 |
 | ---- | ---- | ---- | ------ |
diff --git a/packages/components/src/layout/composables/useLayoutAsideStates.ts b/packages/components/src/layout/composables/useLayoutAsideStates.ts
index 7b7deeb2f..98bcfcac3 100644
--- a/packages/components/src/layout/composables/useLayoutAsideStates.ts
+++ b/packages/components/src/layout/composables/useLayoutAsideStates.ts
@@ -1,6 +1,6 @@
 import type { MaybeRefOrGetter } from '@vueuse/core'
 import { computed, toValue } from 'vue'
-import type { LayoutAsideOpenDetail, LayoutAsideProps, LayoutAsideResizeDetail, LayoutSide } from '../index.type'
+import type { LayoutAsideOpenDetail, LayoutAsideOptions, LayoutAsideResizeDetail, LayoutSide } from '../index.type'
 import type { LayoutAsideState } from '../internal.type'
 import { clamp } from '../utils/number'
 import {
@@ -13,14 +13,14 @@ import { useControllableState } from '../../shared/composables/useControllableSt
 
 interface UseLayoutAsideStateOptions {
   side: LayoutSide
-  config: MaybeRefOrGetter<LayoutAsideProps | undefined>
+  config: MaybeRefOrGetter<LayoutAsideOptions | undefined>
   onOpenChange?: (detail: LayoutAsideOpenDetail) => void
   onExpandedWidthChange?: (detail: LayoutAsideResizeDetail) => void
 }
 
 interface UseLayoutAsideStatesOptions {
-  leftConfig: MaybeRefOrGetter<LayoutAsideProps | undefined>
-  rightConfig: MaybeRefOrGetter<LayoutAsideProps | undefined>
+  leftConfig: MaybeRefOrGetter<LayoutAsideOptions | undefined>
+  rightConfig: MaybeRefOrGetter<LayoutAsideOptions | undefined>
   onOpenChange?: (detail: LayoutAsideOpenDetail) => void
   onExpandedWidthChange?: (detail: LayoutAsideResizeDetail) => void
 }
diff --git a/packages/components/src/layout/index.type.ts b/packages/components/src/layout/index.type.ts
index 65e21ec2d..0f08f2b00 100644
--- a/packages/components/src/layout/index.type.ts
+++ b/packages/components/src/layout/index.type.ts
@@ -49,7 +49,7 @@ export type LayoutFloatingResizeDetail = LayoutFloatingState & {
   handle: LayoutFloatingResizeHandle
 }
 
-export interface LayoutAsideProps {
+export interface LayoutAsideOptions {
   mode?: LayoutAsideMode
   open?: boolean
   defaultOpen?: boolean
@@ -63,8 +63,8 @@ export interface LayoutAsideProps {
 }
 
 export interface LayoutAsidePanelsProps {
-  leftAside?: LayoutAsideProps
-  rightAside?: LayoutAsideProps
+  leftAside?: LayoutAsideOptions
+  rightAside?: LayoutAsideOptions
 }
 
 export interface LayoutNormalProps extends LayoutAsidePanelsProps {

From 3cda7373a1679ec8ab6c63c7b6a1a1dd875f0019 Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Wed, 8 Jul 2026 19:05:54 -0700
Subject: [PATCH 08/12] feat(docs): update layout documentation and demo labels
 for consistency

---
 docs/demos/layout/aside-controlled.vue |  4 ++--
 docs/demos/layout/aside-modes.vue      |  2 +-
 docs/demos/layout/basic.vue            |  4 ++--
 docs/demos/layout/floating-panels.vue  |  8 ++++----
 docs/src/components/layout.md          | 16 ++++++++--------
 5 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/docs/demos/layout/aside-controlled.vue b/docs/demos/layout/aside-controlled.vue
index 22f5babbc..8f5cc0b5c 100644
--- a/docs/demos/layout/aside-controlled.vue
+++ b/docs/demos/layout/aside-controlled.vue
@@ -62,7 +62,7 @@ function updateRightAsideOpen(detail: LayoutAsideOpenValue) {
       <div class="layout-slot-props-demo__group">
         <span class="layout-slot-props-demo__group-label">右侧栏</span>
         <TinyButton :reset-time="0" @click="rightOpen = !rightOpen">
-          {{ rightOpen ? '关闭抽屉' : '打开抽屉' }}
+          {{ rightOpen ? '关闭 Drawer' : '打开 Drawer' }}
         </TinyButton>
       </div>
     </div>
@@ -92,7 +92,7 @@ function updateRightAsideOpen(detail: LayoutAsideOpenValue) {
 
       <template #right-aside>
         <div class="layout-slot-props-demo__drawer">
-          <p>右侧抽屉</p>
+          <p>Drawer</p>
           <p>由外部按钮控制开关。</p>
         </div>
       </template>
diff --git a/docs/demos/layout/aside-modes.vue b/docs/demos/layout/aside-modes.vue
index bb5c2129c..17251e8ba 100644
--- a/docs/demos/layout/aside-modes.vue
+++ b/docs/demos/layout/aside-modes.vue
@@ -26,7 +26,7 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
         <div class="layout-aside-demo__header">
           <span>Header 区域</span>
           <TinyButton :reset-time="0" @click="rightOpen = !rightOpen">
-            {{ rightOpen ? '关闭抽屉' : '打开抽屉' }}
+            {{ rightOpen ? '关闭 Drawer' : '打开 Drawer' }}
           </TinyButton>
         </div>
       </template>
diff --git a/docs/demos/layout/basic.vue b/docs/demos/layout/basic.vue
index 2b4af0607..762782ed9 100644
--- a/docs/demos/layout/basic.vue
+++ b/docs/demos/layout/basic.vue
@@ -9,7 +9,7 @@ import { TrLayout } from '@opentiny/tiny-robot'
       :right-aside="{ defaultOpen: true, defaultExpandedWidth: 160 }"
     >
       <template #left-aside>
-        <div class="layout-basic-demo__aside">导航</div>
+        <div class="layout-basic-demo__aside">Left-Aside</div>
       </template>
 
       <template #header>
@@ -25,7 +25,7 @@ import { TrLayout } from '@opentiny/tiny-robot'
       </template>
 
       <template #right-aside>
-        <div class="layout-basic-demo__aside">信息栏</div>
+        <div class="layout-basic-demo__aside">Right-Aside</div>
       </template>
     </TrLayout>
   </div>
diff --git a/docs/demos/layout/floating-panels.vue b/docs/demos/layout/floating-panels.vue
index 46c3e935d..e96ddcc42 100644
--- a/docs/demos/layout/floating-panels.vue
+++ b/docs/demos/layout/floating-panels.vue
@@ -57,7 +57,7 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
         <div class="layout-floating-panels-demo__header">
           <strong>浮层工作区</strong>
           <div class="layout-floating-panels-demo__actions">
-            <TinyButton :reset-time="0" @click="rightOpen = true">打开右抽屉</TinyButton>
+            <TinyButton :reset-time="0" @click="rightOpen = true">右侧面板</TinyButton>
           </div>
         </div>
       </template>
@@ -66,15 +66,15 @@ function updateRightAside(detail: LayoutAsideOpenValue) {
         <div class="layout-floating-panels-demo__main">
           <div class="layout-floating-panels-demo__card">左侧使用 dock，保留常驻导航区并占据浮层宽度。</div>
           <div class="layout-floating-panels-demo__card">右侧使用 drawer，需要时展开，不占主区宽度。</div>
-          <div class="layout-floating-panels-demo__card">整个浮层仍可拖拽、缩放，适合组合常驻导航和临时操作面板。</div>
+          <div class="layout-floating-panels-demo__card">整个浮层仍可拖拽、缩放</div>
         </div>
       </template>
 
       <template #right-aside>
         <div class="layout-floating-panels-demo__aside">
-          <div class="layout-floating-panels-demo__aside-title">右侧操作抽屉</div>
+          <div class="layout-floating-panels-demo__aside-title">右侧面板</div>
           <div>按需展开，不占主区宽度，适合放操作表单或补充面板。</div>
-          <TrLayout.AsideToggle side="right" class="layout-floating-panels-demo__chip">关闭抽屉</TrLayout.AsideToggle>
+          <TrLayout.AsideToggle side="right" class="layout-floating-panels-demo__chip">关闭面板</TrLayout.AsideToggle>
         </div>
       </template>
     </TrLayout>
diff --git a/docs/src/components/layout.md b/docs/src/components/layout.md
index e89c6e02b..6b49c735a 100644
--- a/docs/src/components/layout.md
+++ b/docs/src/components/layout.md
@@ -4,7 +4,7 @@ outline: [1, 3]
 
 # Layout 布局
 
-`Layout` 是面向 AI 应用页面的通用布局组件，适合搭建聊天页、工作台和多面板操作界面。
+`Layout` 是 AI 应用页面的通用布局组件，可用于搭建聊天页、工作台和多面板操作界面。
 
 它提供以下能力：
 
@@ -24,7 +24,7 @@ outline: [1, 3]
 `mode` 控制 `Layout` 的整体形态，默认值为 `normal`。
 
 - `normal`：普通页面骨架，参与文档流布局
-- `floating`：悬浮布局，脱离文档流，支持用作悬浮工作区或可拖拽窗口
+- `floating`：悬浮布局，脱离文档流，可用于构建悬浮工作区或拖拽窗口
 
 <demo vue="../../demos/layout/mode.vue" title="布局模式" description="切换 normal 和 floating 查看布局形态差异。" />
 
@@ -32,7 +32,7 @@ outline: [1, 3]
 
 侧栏由 `leftAside` / `rightAside` 控制，类型为 [`LayoutAsideOptions`](#layout-aside-options)。
 
-侧栏内容通过 `left-aside` / `right-aside` 插槽提供。配置和内容分开后，可以只调整行为配置，而不影响插槽里的渲染结构。
+侧栏内容通过 `left-aside` / `right-aside` 插槽提供。
 
 ### 展示形态
 
@@ -80,11 +80,11 @@ outline: [1, 3]
 
 ## 浮层
 
-浮层相关配置和交互只在浮层模式下生效。
+浮层相关配置和交互只在浮层模式(`mode="floating"`)下生效。
 
-- `defaultFloatingState`：非受控初始状态，只在首次挂载时读取
+- `defaultFloatingState`：非受控初始状态，只在首次加载时读取
 - `floatingState`：受控状态，由外部维护当前位置和尺寸
-- `floatingOptions`：浮层行为配置，用于拖拽、缩放和尺寸约束，不参与状态控制
+- `floatingOptions`：浮层行为配置，用于拖拽、缩放和尺寸约束
 
 > `defaultFloatingState` 和 `floatingState` 不要同时传入
 
@@ -100,7 +100,7 @@ outline: [1, 3]
 
 ### 受控浮层
 
-受控浮层以 `floatingState` 作为唯一状态源，组件始终按外部状态渲染；
+受控浮层以 `floatingState` 作为唯一状态源，组件始终按外部状态渲染。
 
 后续通过 `update:floatingState` 通知外部同步。
 
@@ -122,7 +122,7 @@ outline: [1, 3]
 
 ## 代理滚动条
 
-`Layout.ProxyScrollbar` 是代理滚动条，适合消息流、长内容阅读流和工作台主区。
+`Layout.ProxyScrollbar` 是代理滚动条，可用于消息流、长内容阅读流和工作台主区。
 
 常见于内容列居中或限宽后，原生滚动条偏离主区右边界的场景。
 

From 365932dbda34a6ec5cb0ad29ca06b95ddfd8e3ed Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Wed, 8 Jul 2026 20:20:59 -0700
Subject: [PATCH 09/12] feat(docs): refine layout documentation and improve
 content clarity

---
 docs/demos/layout/main-scroll-bubble.vue |  2 +-
 docs/demos/layout/main-scroll-div.vue    |  2 +-
 docs/demos/layout/main-scroll.vue        |  2 +-
 docs/src/components/layout.md            | 38 ++++++++++++++++++++++--
 4 files changed, 38 insertions(+), 6 deletions(-)

diff --git a/docs/demos/layout/main-scroll-bubble.vue b/docs/demos/layout/main-scroll-bubble.vue
index f232dde0a..341bbd1d7 100644
--- a/docs/demos/layout/main-scroll-bubble.vue
+++ b/docs/demos/layout/main-scroll-bubble.vue
@@ -21,7 +21,7 @@ const messages: BubbleListProps['messages'] = Array.from({ length: 12 }, (_, ind
   },
   {
     role: 'assistant',
-    content: '可以。内容区可以居中显示，滚动条仍然贴着 Layout 主区右侧。',
+    content: '可以。内容区可以居中显示，滚动条仍然固定在 Layout 主区右侧。',
   },
 ]).flat()
 </script>
diff --git a/docs/demos/layout/main-scroll-div.vue b/docs/demos/layout/main-scroll-div.vue
index 06d5e2dc9..d101bed5b 100644
--- a/docs/demos/layout/main-scroll-div.vue
+++ b/docs/demos/layout/main-scroll-div.vue
@@ -18,7 +18,7 @@ const sections = Array.from({ length: 12 }, (_, index) => index + 1)
         <div class="layout-main-scroll-div__content" :class="{ 'is-centered': props.centered }">
           <section v-for="section in sections" :key="section" class="layout-main-scroll-div__item">
             <strong>Section {{ section }}</strong>
-            <p>普通内容区也可以把滚动容器交给 Layout.ProxyScrollbar。</p>
+            <p>普通内容区也可以把滚动宿主交给 Layout.ProxyScrollbar 代理滚动条。</p>
           </section>
         </div>
       </div>
diff --git a/docs/demos/layout/main-scroll.vue b/docs/demos/layout/main-scroll.vue
index 61b126377..9d8d62259 100644
--- a/docs/demos/layout/main-scroll.vue
+++ b/docs/demos/layout/main-scroll.vue
@@ -21,7 +21,7 @@ const isCentered = ref(true)
         <tiny-switch v-model="isCentered"></tiny-switch>
       </label>
     </div>
-    <p class="layout-main-scroll-demo__tip">外层作为滚动宿主，内层只负责居中和限宽。</p>
+    <p class="layout-main-scroll-demo__tip">外层作为滚动宿主，内层只负责内容居中和限宽。</p>
 
     <div class="layout-main-scroll-demo__stage">
       <MainScrollBubble v-if="activeExample === 'bubble'" :centered="isCentered" />
diff --git a/docs/src/components/layout.md b/docs/src/components/layout.md
index 6b49c735a..ecc38d9f5 100644
--- a/docs/src/components/layout.md
+++ b/docs/src/components/layout.md
@@ -122,12 +122,14 @@ outline: [1, 3]
 
 ## 代理滚动条
 
-`Layout.ProxyScrollbar` 是代理滚动条，可用于消息流、长内容阅读流和工作台主区。
+代理滚动条(`Layout.ProxyScrollbar`)适用于内容列居中或限宽后，原生滚动条偏离主区右边界的场景。真实滚动仍然发生在 `scrollTarget` 指向的元素上。它只负责同步滚动状态，并代理滚动条的显示与拖拽。
 
-常见于内容列居中或限宽后，原生滚动条偏离主区右边界的场景。
+### 使用要求
 
 - 将实际承担滚动的元素传给 `scrollTarget`。
-- 为使代理滚动条正确生效，该滚动元素需要具备以下基础样式。
+- 为使 `Layout.ProxyScrollbar` 正常生效，传给 `scrollTarget` 的滚动容器需要具备明确高度，并通过 `overflow: auto` 或 `overflow: scroll` 承担真实滚动。
+
+> 推荐的基础样式如下：
 
 ```css
 .scroll-host {
@@ -138,6 +140,32 @@ outline: [1, 3]
 }
 ```
 
+### 基本结构
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { TrLayout } from '@opentiny/tiny-robot'
+
+const scrollTargetRef = ref<HTMLElement | null>(null)
+</script>
+
+<template>
+  <TrLayout>
+    <template #main>
+      <div ref="scrollTargetRef" class="scroll-host">
+        <div class="content-shell">
+          <!-- content -->
+        </div>
+      </div>
+      <TrLayout.ProxyScrollbar :scroll-target="scrollTargetRef" />
+    </template>
+  </TrLayout>
+</template>
+```
+
+### 使用示例
+
 <demo
   vue="../../demos/layout/main-scroll.vue"
   :vueFiles="[
@@ -149,6 +177,10 @@ outline: [1, 3]
   description="内容区居中后，滚动条仍固定在主区右侧。"
 />
 
+### 注意事项
+
+`Layout.ProxyScrollbar` 仅用于代理滚动条显示与拖拽，不负责内容渲染或性能优化。
+
 ## 侧栏开关
 
 `Layout.AsideToggle` 是内置侧栏开关按钮，可以在 `Layout` 内部任意区域使用。

From 1ff6e2052aabdf99f3f2dcea9692632907e1b348 Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Wed, 8 Jul 2026 23:49:25 -0700
Subject: [PATCH 10/12] feat(docs): clarify ProxyScrollbar usage and improve
 layout documentation

---
 docs/src/components/layout.md | 249 ++++++++++++++++++----------------
 1 file changed, 130 insertions(+), 119 deletions(-)

diff --git a/docs/src/components/layout.md b/docs/src/components/layout.md
index ecc38d9f5..c1064313b 100644
--- a/docs/src/components/layout.md
+++ b/docs/src/components/layout.md
@@ -11,7 +11,7 @@ outline: [1, 3]
 - 页面骨架：统一组织头部、主区、底部与左右侧栏
 - 侧栏交互：支持展开、收起、拖拽改宽和 `drawer` 覆盖
 - 浮层布局：支持定位、拖拽和缩放
-- 主区滚动代理：适用于内容列居中或限宽后，原生滚动条偏离主区右边界的场景
+- 代理滚动条：适用于内容列居中或限宽后，原生滚动条偏离主区右边界的场景
 
 ## 基础布局
 
@@ -122,20 +122,20 @@ outline: [1, 3]
 
 ## 代理滚动条
 
-代理滚动条(`Layout.ProxyScrollbar`)适用于内容列居中或限宽后，原生滚动条偏离主区右边界的场景。真实滚动仍然发生在 `scrollTarget` 指向的元素上。它只负责同步滚动状态，并代理滚动条的显示与拖拽。
+在布局组件中，消息列表通常作为内部滚动区域存在。但当消息列表的宽度小于外层容器宽度时，浏览器原生滚动条会出现在消息列表自身的右侧，而不是外层容器的右侧。
+
+为了解决这个布局问题，布局组件内部使用 ProxyScrollbar 渲染代理滚动条。代理滚动条与消息列表平级，通过接收消息列表的 DOM 引用来同步真实滚动状态，并将滚动条视觉上渲染到外层容器右侧。
 
 ### 使用要求
 
 - 将实际承担滚动的元素传给 `scrollTarget`。
 - 为使 `Layout.ProxyScrollbar` 正常生效，传给 `scrollTarget` 的滚动容器需要具备明确高度，并通过 `overflow: auto` 或 `overflow: scroll` 承担真实滚动。
 
-> 推荐的基础样式如下：
+> scrollTarget 推荐的样式如下：
 
 ```css
 .scroll-host {
-  width: 100%;
   height: 100%;
-  box-sizing: border-box;
   overflow: auto;
 }
 ```
@@ -147,18 +147,16 @@ outline: [1, 3]
 import { ref } from 'vue'
 import { TrLayout } from '@opentiny/tiny-robot'
 
-const scrollTargetRef = ref<HTMLElement | null>(null)
+const messageListRef = ref<HTMLElement | null>(null)
 </script>
 
 <template>
   <TrLayout>
     <template #main>
-      <div ref="scrollTargetRef" class="scroll-host">
-        <div class="content-shell">
-          <!-- content -->
-        </div>
+      <div ref="messageListRef" class="message-list">
+        <!-- messages -->
       </div>
-      <TrLayout.ProxyScrollbar :scroll-target="scrollTargetRef" />
+      <TrLayout.ProxyScrollbar :scroll-target="messageListRef" />
     </template>
   </TrLayout>
 </template>
@@ -179,7 +177,20 @@ const scrollTargetRef = ref<HTMLElement | null>(null)
 
 ### 注意事项
 
-`Layout.ProxyScrollbar` 仅用于代理滚动条显示与拖拽，不负责内容渲染或性能优化。
+- 代理滚动条会默认给滚动元素加上如下样式，用于隐藏原生滚动条
+
+```css
+.tr-layout-proxy-scrollbar-target {
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+}
+```
+
+- `Layout.ProxyScrollbar` 仅用于代理滚动条显示与拖拽，不负责内容渲染或性能优化。传入 `ProxyScrollbar` 的 `scrollTarget` 必须是真正产生滚动的 DOM 元素。
 
 ## 侧栏开关
 
@@ -193,43 +204,43 @@ const scrollTargetRef = ref<HTMLElement | null>(null)
 
 ### Layout {#layout-props}
 
-| 属性名 | 说明 | 类型 | 默认值 |
-| ------ | ---- | ---- | ------ |
-| `mode` | 布局模式；`normal` 参与普通布局，`floating` 会脱离普通布局，不占原来的位置空间 | `'normal' \| 'floating'` | `'normal'` |
-| `leftAside` | 左侧栏配置 | [`LayoutAsideOptions`](#layout-aside-options) | `-` |
-| `rightAside` | 右侧栏配置 | [`LayoutAsideOptions`](#layout-aside-options) | `-` |
-| `floatingState` | 受控浮层状态，需配合 `update:floatingState` 同步外部状态；不要和 `defaultFloatingState` 同时传入 | [`LayoutFloatingState`](#layout-floating-state) | `-` |
-| `defaultFloatingState` | 非受控浮层初始状态，仅首次挂载读取一次；不要和 `floatingState` 同时传入 | [`LayoutFloatingState`](#layout-floating-state) | `-` |
-| `floatingOptions` | 浮层行为配置，包括拖拽、缩放和尺寸约束；不参与状态控制 | [`LayoutFloatingOptions`](#layout-floating-options) | `-` |
+| 属性名                 | 说明                                                                                             | 类型                                                | 默认值     |
+| ---------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------- | ---------- |
+| `mode`                 | 布局模式；`normal` 参与普通布局，`floating` 会脱离普通布局，不占原来的位置空间                   | `'normal' \| 'floating'`                            | `'normal'` |
+| `leftAside`            | 左侧栏配置                                                                                       | [`LayoutAsideOptions`](#layout-aside-options)       | `-`        |
+| `rightAside`           | 右侧栏配置                                                                                       | [`LayoutAsideOptions`](#layout-aside-options)       | `-`        |
+| `floatingState`        | 受控浮层状态，需配合 `update:floatingState` 同步外部状态；不要和 `defaultFloatingState` 同时传入 | [`LayoutFloatingState`](#layout-floating-state)     | `-`        |
+| `defaultFloatingState` | 非受控浮层初始状态，仅首次挂载读取一次；不要和 `floatingState` 同时传入                          | [`LayoutFloatingState`](#layout-floating-state)     | `-`        |
+| `floatingOptions`      | 浮层行为配置，包括拖拽、缩放和尺寸约束；不参与状态控制                                           | [`LayoutFloatingOptions`](#layout-floating-options) | `-`        |
 
 ### Layout.ProxyScrollbar {#layout-proxy-scrollbar-props}
 
-| 属性名 | 说明 | 类型 | 默认值 |
-| ------ | ---- | ---- | ------ |
-| `scrollTarget` | 真实滚动容器的元素，或对应组件实例的 ref | [`LayoutScrollTarget`](#layout-scroll-target) | `-` |
+| 属性名         | 说明                                     | 类型                                          | 默认值 |
+| -------------- | ---------------------------------------- | --------------------------------------------- | ------ |
+| `scrollTarget` | 真实滚动容器的元素，或对应组件实例的 ref | [`LayoutScrollTarget`](#layout-scroll-target) | `-`    |
 
 ### Layout.AsideToggle {#layout-aside-toggle-props}
 
-| 属性名 | 说明 | 类型 | 默认值 |
-| ------ | ---- | ---- | ------ |
-| `side` | 控制的侧栏位置 | `'left' \| 'right'` | `-` |
+| 属性名 | 说明           | 类型                | 默认值 |
+| ------ | -------------- | ------------------- | ------ |
+| `side` | 控制的侧栏位置 | `'left' \| 'right'` | `-`    |
 
 ## Slots
 
 ### Layout {#layout-slots}
 
-| 插槽名 | 说明 | 作用域参数 |
-| ------ | ---- | ---------- |
-| `left-aside` | 左侧栏内容 | `-` |
-| `header` | 顶部区域 | `-` |
-| `main` | 主区内容 | `-` |
-| `footer` | 底部区域 | `-` |
-| `right-aside` | 右侧栏内容 | `-` |
+| 插槽名        | 说明       | 作用域参数 |
+| ------------- | ---------- | ---------- |
+| `left-aside`  | 左侧栏内容 | `-`        |
+| `header`      | 顶部区域   | `-`        |
+| `main`        | 主区内容   | `-`        |
+| `footer`      | 底部区域   | `-`        |
+| `right-aside` | 右侧栏内容 | `-`        |
 
 ### Layout.AsideToggle
 
-| 插槽名 | 说明 | 作用域参数 |
-| ------ | ---- | ---------- |
+| 插槽名    | 说明               | 作用域参数            |
+| --------- | ------------------ | --------------------- |
 | `default` | 自定义切换按钮内容 | `{ isOpen: boolean }` |
 
 ## Events
@@ -263,69 +274,69 @@ function trackAsideChange(detail: { side: 'left' | 'right'; open: boolean }) {
 
 ### Layout {#layout-layout-events}
 
-| 事件名 | 说明 | 回调参数 |
-| ------ | ---- | -------- |
-| `update:floatingState` | 浮层位置或尺寸变化 | (value: [`LayoutFloatingState`](#layout-floating-state)) |
-| `aside-open-change` | 侧栏开关变化 | (detail: [`LayoutAsideOpenDetail`](#layout-aside-open-detail)) |
-| `left-aside-open-change` | 左侧栏开关变化 | (detail: [`LayoutAsideOpenValue`](#layout-aside-open-value)) |
-| `right-aside-open-change` | 右侧栏开关变化 | (detail: [`LayoutAsideOpenValue`](#layout-aside-open-value)) |
-| `aside-resize-start` | 开始调整侧栏宽度 | (detail: [`LayoutAsideResizeDetail`](#layout-aside-resize-detail)) |
-| `aside-resize` | 调整侧栏宽度时持续触发 | (detail: [`LayoutAsideResizeDetail`](#layout-aside-resize-detail)) |
-| `aside-resize-end` | 结束调整侧栏宽度 | (detail: [`LayoutAsideResizeDetail`](#layout-aside-resize-detail)) |
-| `left-aside-resize-start` | 开始调整左侧栏宽度 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
-| `left-aside-resize` | 调整左侧栏宽度时持续触发 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
-| `left-aside-resize-end` | 结束调整左侧栏宽度 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
-| `right-aside-resize-start` | 开始调整右侧栏宽度 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
-| `right-aside-resize` | 调整右侧栏宽度时持续触发 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
-| `right-aside-resize-end` | 结束调整右侧栏宽度 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value)) |
-| `floating-drag-start` | 开始拖动浮层 | (detail: [`LayoutFloatingDragDetail`](#layout-floating-drag-detail)) |
-| `floating-drag` | 拖动浮层时持续触发 | (detail: [`LayoutFloatingDragDetail`](#layout-floating-drag-detail)) |
-| `floating-drag-end` | 结束拖动浮层 | (detail: [`LayoutFloatingDragDetail`](#layout-floating-drag-detail)) |
-| `floating-resize-start` | 开始调整浮层尺寸 | (detail: [`LayoutFloatingResizeDetail`](#layout-floating-resize-detail)) |
-| `floating-resize` | 调整浮层尺寸时持续触发 | (detail: [`LayoutFloatingResizeDetail`](#layout-floating-resize-detail)) |
-| `floating-resize-end` | 结束调整浮层尺寸 | (detail: [`LayoutFloatingResizeDetail`](#layout-floating-resize-detail)) |
+| 事件名                     | 说明                     | 回调参数                                                                 |
+| -------------------------- | ------------------------ | ------------------------------------------------------------------------ |
+| `update:floatingState`     | 浮层位置或尺寸变化       | (value: [`LayoutFloatingState`](#layout-floating-state))                 |
+| `aside-open-change`        | 侧栏开关变化             | (detail: [`LayoutAsideOpenDetail`](#layout-aside-open-detail))           |
+| `left-aside-open-change`   | 左侧栏开关变化           | (detail: [`LayoutAsideOpenValue`](#layout-aside-open-value))             |
+| `right-aside-open-change`  | 右侧栏开关变化           | (detail: [`LayoutAsideOpenValue`](#layout-aside-open-value))             |
+| `aside-resize-start`       | 开始调整侧栏宽度         | (detail: [`LayoutAsideResizeDetail`](#layout-aside-resize-detail))       |
+| `aside-resize`             | 调整侧栏宽度时持续触发   | (detail: [`LayoutAsideResizeDetail`](#layout-aside-resize-detail))       |
+| `aside-resize-end`         | 结束调整侧栏宽度         | (detail: [`LayoutAsideResizeDetail`](#layout-aside-resize-detail))       |
+| `left-aside-resize-start`  | 开始调整左侧栏宽度       | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value))         |
+| `left-aside-resize`        | 调整左侧栏宽度时持续触发 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value))         |
+| `left-aside-resize-end`    | 结束调整左侧栏宽度       | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value))         |
+| `right-aside-resize-start` | 开始调整右侧栏宽度       | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value))         |
+| `right-aside-resize`       | 调整右侧栏宽度时持续触发 | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value))         |
+| `right-aside-resize-end`   | 结束调整右侧栏宽度       | (detail: [`LayoutAsideResizeValue`](#layout-aside-resize-value))         |
+| `floating-drag-start`      | 开始拖动浮层             | (detail: [`LayoutFloatingDragDetail`](#layout-floating-drag-detail))     |
+| `floating-drag`            | 拖动浮层时持续触发       | (detail: [`LayoutFloatingDragDetail`](#layout-floating-drag-detail))     |
+| `floating-drag-end`        | 结束拖动浮层             | (detail: [`LayoutFloatingDragDetail`](#layout-floating-drag-detail))     |
+| `floating-resize-start`    | 开始调整浮层尺寸         | (detail: [`LayoutFloatingResizeDetail`](#layout-floating-resize-detail)) |
+| `floating-resize`          | 调整浮层尺寸时持续触发   | (detail: [`LayoutFloatingResizeDetail`](#layout-floating-resize-detail)) |
+| `floating-resize-end`      | 结束调整浮层尺寸         | (detail: [`LayoutFloatingResizeDetail`](#layout-floating-resize-detail)) |
 
 ## Types {#types}
 
 ### LayoutAsideOptions {#layout-aside-options}
 
-| 字段 | 说明 | 类型 | 默认值 |
-| ---- | ---- | ---- | ------ |
-| `mode` | 侧栏模式 | `'dock' \| 'drawer'` | `'dock'` |
-| `open` | 受控开关状态 | `boolean` | `-` |
-| `defaultOpen` | 非受控初始开关状态 | `boolean` | `left: true` / `right: false` |
-| `expandedWidth` | 受控展开宽度；`drawer` 未设置 `--tr-layout-drawer-width` 时会回退使用该宽度 | `number` | `-` |
-| `defaultExpandedWidth` | 非受控初始展开宽度；`drawer` 宽度回退值 | `number` | `left: 300` / `right: 320` |
-| `minExpandedWidth` | 最小展开宽度边界 | `number` | `left: 200` / `right: 240` |
-| `maxExpandedWidth` | 最大展开宽度边界 | `number` | `left: 560` / `right: 640` |
-| `collapsedWidth` | 收起后保留的窄栏宽度，仅 `dock` 生效 | `number` | `0` |
-| `collapseEffect` | `dock` 收起到窄栏时的内容动画 | `'overlay' \| 'slide'` | `'overlay'` |
-| `resizable` | 是否允许拖拽改宽，仅 `dock` 生效 | `boolean` | `false` |
+| 字段                   | 说明                                                                        | 类型                   | 默认值                        |
+| ---------------------- | --------------------------------------------------------------------------- | ---------------------- | ----------------------------- |
+| `mode`                 | 侧栏模式                                                                    | `'dock' \| 'drawer'`   | `'dock'`                      |
+| `open`                 | 受控开关状态                                                                | `boolean`              | `-`                           |
+| `defaultOpen`          | 非受控初始开关状态                                                          | `boolean`              | `left: true` / `right: false` |
+| `expandedWidth`        | 受控展开宽度；`drawer` 未设置 `--tr-layout-drawer-width` 时会回退使用该宽度 | `number`               | `-`                           |
+| `defaultExpandedWidth` | 非受控初始展开宽度；`drawer` 宽度回退值                                     | `number`               | `left: 300` / `right: 320`    |
+| `minExpandedWidth`     | 最小展开宽度边界                                                            | `number`               | `left: 200` / `right: 240`    |
+| `maxExpandedWidth`     | 最大展开宽度边界                                                            | `number`               | `left: 560` / `right: 640`    |
+| `collapsedWidth`       | 收起后保留的窄栏宽度，仅 `dock` 生效                                        | `number`               | `0`                           |
+| `collapseEffect`       | `dock` 收起到窄栏时的内容动画                                               | `'overlay' \| 'slide'` | `'overlay'`                   |
+| `resizable`            | 是否允许拖拽改宽，仅 `dock` 生效                                            | `boolean`              | `false`                       |
 
 ### LayoutAsideOpenDetail {#layout-aside-open-detail}
 
-| 字段 | 说明 | 类型 |
-| ---- | ---- | ---- |
+| 字段   | 说明         | 类型                |
+| ------ | ------------ | ------------------- |
 | `side` | 当前侧栏位置 | `'left' \| 'right'` |
-| `open` | 当前是否展开 | `boolean` |
+| `open` | 当前是否展开 | `boolean`           |
 
 ### LayoutAsideOpenValue {#layout-aside-open-value}
 
-| 字段 | 说明 | 类型 |
-| ---- | ---- | ---- |
+| 字段   | 说明         | 类型      |
+| ------ | ------------ | --------- |
 | `open` | 当前是否展开 | `boolean` |
 
 ### LayoutAsideResizeDetail {#layout-aside-resize-detail}
 
-| 字段 | 说明 | 类型 |
-| ---- | ---- | ---- |
-| `side` | 当前侧栏位置 | `'left' \| 'right'` |
-| `expandedWidth` | 当前侧栏宽度 | `number` |
+| 字段            | 说明         | 类型                |
+| --------------- | ------------ | ------------------- |
+| `side`          | 当前侧栏位置 | `'left' \| 'right'` |
+| `expandedWidth` | 当前侧栏宽度 | `number`            |
 
 ### LayoutAsideResizeValue {#layout-aside-resize-value}
 
-| 字段 | 说明 | 类型 |
-| ---- | ---- | ---- |
+| 字段            | 说明         | 类型     |
+| --------------- | ------------ | -------- |
 | `expandedWidth` | 当前侧栏宽度 | `number` |
 
 ### LayoutScrollTarget {#layout-scroll-target}
@@ -354,24 +365,24 @@ const scrollEl = ref<HTMLElement | null>(null)
 
 ### LayoutFloatingState {#layout-floating-state}
 
-| 字段 | 说明 | 类型 | 默认值 |
-| ---- | ---- | ---- | ------ |
-| `placement` | 浮层位置 | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' \| 'center'` | `'center'` |
-| `offsetX` | 横向偏移；`placement` 为 `center` 时不生效 | `number` | `24` |
-| `offsetY` | 纵向偏移；`placement` 为 `center` 时不生效 | `number` | `24` |
-| `width` | 浮层宽度；非受控时表示初始值，受控时表示当前值 | `number` | `420` |
-| `height` | 浮层高度；非受控时表示初始值，受控时表示当前值 | `number` | `560` |
+| 字段        | 说明                                           | 类型                                                                       | 默认值     |
+| ----------- | ---------------------------------------------- | -------------------------------------------------------------------------- | ---------- |
+| `placement` | 浮层位置                                       | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' \| 'center'` | `'center'` |
+| `offsetX`   | 横向偏移；`placement` 为 `center` 时不生效     | `number`                                                                   | `24`       |
+| `offsetY`   | 纵向偏移；`placement` 为 `center` 时不生效     | `number`                                                                   | `24`       |
+| `width`     | 浮层宽度；非受控时表示初始值，受控时表示当前值 | `number`                                                                   | `420`      |
+| `height`    | 浮层高度；非受控时表示初始值，受控时表示当前值 | `number`                                                                   | `560`      |
 
 ### LayoutFloatingOptions {#layout-floating-options}
 
-| 字段 | 说明 | 类型 | 默认值 |
-| ---- | ---- | ---- | ------ |
-| `draggable` | 是否允许拖动浮层 | `boolean` | `true` |
-| `resizable` | 是否允许通过浮层边缘手柄调整尺寸 | `boolean` | `false` |
-| `minWidth` | 最小宽度 | `number` | `320` |
-| `maxWidth` | 最大宽度 | `number` | `视口宽度` |
-| `minHeight` | 最小高度 | `number` | `240` |
-| `maxHeight` | 最大高度 | `number` | `视口高度` |
+| 字段        | 说明                             | 类型      | 默认值     |
+| ----------- | -------------------------------- | --------- | ---------- |
+| `draggable` | 是否允许拖动浮层                 | `boolean` | `true`     |
+| `resizable` | 是否允许通过浮层边缘手柄调整尺寸 | `boolean` | `false`    |
+| `minWidth`  | 最小宽度                         | `number`  | `320`      |
+| `maxWidth`  | 最大宽度                         | `number`  | `视口宽度` |
+| `minHeight` | 最小高度                         | `number`  | `240`      |
+| `maxHeight` | 最大高度                         | `number`  | `视口高度` |
 
 ### LayoutFloatingDragDetail {#layout-floating-drag-detail}
 
@@ -381,37 +392,37 @@ const scrollEl = ref<HTMLElement | null>(null)
 
 在 [`LayoutFloatingState`](#layout-floating-state) 基础上增加以下字段：
 
-| 字段 | 说明 | 类型 |
-| ---- | ---- | ---- |
+| 字段     | 说明             | 类型                                                |
+| -------- | ---------------- | --------------------------------------------------- |
 | `handle` | 当前拖动的边或角 | `'s' \| 'e' \| 'w' \| 'ne' \| 'nw' \| 'se' \| 'sw'` |
 
 ## CSS 变量
 
 ### 布局基础 {#layout-css-basics}
 
-| 变量名 | 说明 |
-| ------ | ---- |
-| `--tr-layout-height` | 布局高度 |
-| `--tr-layout-bg` | 容器背景 |
-| `--tr-layout-left-aside-bg` | 左侧栏背景 |
-| `--tr-layout-right-aside-bg` | 右侧栏背景 |
-| `--tr-layout-header-bg` | 顶部背景 |
-| `--tr-layout-main-bg` | 主区背景 |
-| `--tr-layout-footer-bg` | 底部背景 |
-| `--tr-layout-divider-color` | 分隔线颜色 |
-| `--tr-layout-overlay-bg` | drawer 遮罩颜色 |
-| `--tr-layout-panel-shadow` | drawer 阴影 |
-| `--tr-layout-floating-radius` | 浮层圆角 |
-| `--tr-layout-floating-shadow` | 浮层阴影 |
-| `--tr-layout-floating-z-index` | 浮层层级 |
+| 变量名                         | 说明            |
+| ------------------------------ | --------------- |
+| `--tr-layout-height`           | 布局高度        |
+| `--tr-layout-bg`               | 容器背景        |
+| `--tr-layout-left-aside-bg`    | 左侧栏背景      |
+| `--tr-layout-right-aside-bg`   | 右侧栏背景      |
+| `--tr-layout-header-bg`        | 顶部背景        |
+| `--tr-layout-main-bg`          | 主区背景        |
+| `--tr-layout-footer-bg`        | 底部背景        |
+| `--tr-layout-divider-color`    | 分隔线颜色      |
+| `--tr-layout-overlay-bg`       | drawer 遮罩颜色 |
+| `--tr-layout-panel-shadow`     | drawer 阴影     |
+| `--tr-layout-floating-radius`  | 浮层圆角        |
+| `--tr-layout-floating-shadow`  | 浮层阴影        |
+| `--tr-layout-floating-z-index` | 浮层层级        |
 
 ### 内容与交互 {#layout-css-content}
 
-| 变量名 | 说明 |
-| ------ | ---- |
-| `--tr-layout-main-min-width` | 主区最小宽度 |
-| `--tr-layout-drawer-width` | drawer 展示宽度 |
-| `--tr-layout-main-scrollbar-width` | 滚动条宽度 |
-| `--tr-layout-main-scrollbar-thumb-bg` | 滚动条滑块颜色 |
-| `--tr-layout-main-scrollbar-thumb-bg-hover` | 滑块悬停颜色 |
-| `--tr-layout-main-scrollbar-thumb-bg-active` | 滑块激活颜色 |
+| 变量名                                       | 说明            |
+| -------------------------------------------- | --------------- |
+| `--tr-layout-main-min-width`                 | 主区最小宽度    |
+| `--tr-layout-drawer-width`                   | drawer 展示宽度 |
+| `--tr-layout-main-scrollbar-width`           | 滚动条宽度      |
+| `--tr-layout-main-scrollbar-thumb-bg`        | 滚动条滑块颜色  |
+| `--tr-layout-main-scrollbar-thumb-bg-hover`  | 滑块悬停颜色    |
+| `--tr-layout-main-scrollbar-thumb-bg-active` | 滑块激活颜色    |

From 88eefa0607baad789bf60713ba596f177944768c Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Thu, 9 Jul 2026 00:46:45 -0700
Subject: [PATCH 11/12] feat(docs): remove redundant event synchronization
 examples from layout documentation

---
 docs/src/components/layout.md | 47 -----------------------------------
 1 file changed, 47 deletions(-)

diff --git a/docs/src/components/layout.md b/docs/src/components/layout.md
index c1064313b..d0b251cad 100644
--- a/docs/src/components/layout.md
+++ b/docs/src/components/layout.md
@@ -245,33 +245,6 @@ const messageListRef = ref<HTMLElement | null>(null)
 
 ## Events
 
-单侧状态同步优先使用 `left/right-*` 事件；统一埋点、日志或聚合处理可使用 `aside-*` 事件；浮层受控同步只使用 `update:floatingState`。
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { TrLayout } from '@opentiny/tiny-robot'
-
-const leftOpen = ref(true)
-
-function syncLeftAside(detail: { open: boolean }) {
-  leftOpen.value = detail.open
-}
-
-function trackAsideChange(detail: { side: 'left' | 'right'; open: boolean }) {
-  console.log(detail.side, detail.open)
-}
-</script>
-
-<template>
-  <TrLayout
-    :left-aside="{ open: leftOpen }"
-    @left-aside-open-change="syncLeftAside"
-    @aside-open-change="trackAsideChange"
-  />
-</template>
-```
-
 ### Layout {#layout-layout-events}
 
 | 事件名                     | 说明                     | 回调参数                                                                 |
@@ -343,26 +316,6 @@ function trackAsideChange(detail: { side: 'left' | 'right'; open: boolean }) {
 
 `HTMLElement | Pick<ComponentPublicInstance, '$el'> | null | undefined`
 
-优先传真实 DOM ref。只有组件根节点本身就是滚动宿主时，才传组件 ref；组件 ref 会被解析为 `$el`。
-
-```vue
-<script setup lang="ts">
-import { ref } from 'vue'
-import { TrLayout } from '@opentiny/tiny-robot'
-
-const scrollEl = ref<HTMLElement | null>(null)
-</script>
-
-<template>
-  <TrLayout>
-    <template #main>
-      <div ref="scrollEl" class="scroll-host"></div>
-      <TrLayout.ProxyScrollbar :scroll-target="scrollEl" />
-    </template>
-  </TrLayout>
-</template>
-```
-
 ### LayoutFloatingState {#layout-floating-state}
 
 | 字段        | 说明                                           | 类型                                                                       | 默认值     |

From 339bc6c6744cc5bb7ebd0c90e8b22935b390a0dc Mon Sep 17 00:00:00 2001
From: SonyLeo <746591437@qq.com>
Date: Thu, 9 Jul 2026 00:56:54 -0700
Subject: [PATCH 12/12] feat(docs): improve clarity in layout documentation
 regarding proxy scrollbar styles

---
 docs/src/components/layout.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/src/components/layout.md b/docs/src/components/layout.md
index d0b251cad..ad0871ee3 100644
--- a/docs/src/components/layout.md
+++ b/docs/src/components/layout.md
@@ -177,7 +177,7 @@ const messageListRef = ref<HTMLElement | null>(null)
 
 ### 注意事项
 
-- 代理滚动条会默认给滚动元素加上如下样式，用于隐藏原生滚动条
+- 代理滚动条会默认给目标滚动元素添加以下样式，用于隐藏原生滚动条
 
 ```css
 .tr-layout-proxy-scrollbar-target {