chore: update docs

Author: wangdicoder

apps/docs/src/hooks/use-headings.ts

@@ -1,5 +1,6 @@
 import { useState, useEffect } from 'react';
 import { useLocation } from 'react-router-dom';
+import { useLocaleContext } from '../context/locale-context';
 
 export interface HeadingItem {
   id: string;
@@ -18,34 +19,31 @@ const queryHeadings = (): HeadingItem[] => {
 
 export const useHeadings = (): HeadingItem[] => {
   const { pathname } = useLocation();
+  const { locale } = useLocaleContext();
   const [headings, setHeadings] = useState<HeadingItem[]>([]);
 
   useEffect(() => {
     setHeadings([]);
 
-    // Try immediately in case content is already rendered
-    const initial = queryHeadings();
-    if (initial.length > 0) {
-      setHeadings(initial);
-      return;
-    }
-
-    // Otherwise observe DOM changes until headings appear
     const container = document.querySelector('.doc-container__layout');
     if (!container) return;
 
-    const observer = new MutationObserver(() => {
+    const update = () => {
       const found = queryHeadings();
       if (found.length > 0) {
         setHeadings(found);
-        observer.disconnect();
       }
-    });
+    };
+
+    // Try immediately in case content is already rendered
+    update();
 
+    // Also observe DOM changes to catch async content swaps (e.g. locale toggle)
+    const observer = new MutationObserver(update);
     observer.observe(container, { childList: true, subtree: true });
 
     return () => observer.disconnect();
-  }, [pathname]);
+  }, [pathname, locale]);
 
   return headings;
 };

packages/react/src/alert/index.zh_CN.md

@@ -10,6 +10,8 @@ import TitleDemo from './demo/Title';
 import TitleSource from './demo/Title.tsx?raw';
 import TypeDemo from './demo/Type';
 import TypeSource from './demo/Type.tsx?raw';
+import LoopBannerDemo from './demo/LoopBanner';
+import LoopBannerSource from './demo/LoopBanner.tsx?raw';
 
 # Alert 警告提示
 
@@ -85,6 +87,15 @@ import { Alert } from 'tiny-design';
 
 <DemoBlock component={CloseBtnDemo} source={CloseBtnSource} />
 
+    </Demo>
+    <Demo>
+
+### 循环横幅
+
+结合 `Marquee` 组件创建滚动横幅警告。文本在鼠标悬停时会暂停滚动。
+
+<DemoBlock component={LoopBannerDemo} source={LoopBannerSource} />
+
     </Demo>
   </Column>
 </Layout>

packages/react/src/flex/index.md

@@ -11,9 +11,23 @@ import WrapSource from './demo/Wrap.tsx?raw';
 
 A flexbox container component using CSS `gap` for spacing with no child wrapping.
 
-## Scenario
+## When To Use
 
-Use Flex when you need a lightweight flexbox layout without wrapping each child in additional elements.
+Flex is a one-dimensional layout container best suited for arranging items in a single row or column.
+
+- **Toolbars & action bars** — align a group of buttons, icons, or controls horizontally with consistent spacing.
+- **Navigation menus** — lay out nav items in a row or a vertical sidebar list.
+- **Form field rows** — place a label, input, and helper text side by side.
+- **Card footers / headers** — push actions to opposite ends with `justify="space-between"`.
+- **Vertical stacking** — use `vertical` to stack content like a list of cards or settings sections.
+- **Inline tag / badge groups** — render a wrapping set of tags with `wrap="wrap"` and a uniform `gap`.
+
+### Flex vs Row
+
+Both use flexbox under the hood, but they serve different purposes:
+
+- Choose **Flex** when you need a general-purpose flexbox container with CSS `gap` and no column semantics.
+- Choose **Row / Col** when you need a 24-column grid structure with `span`, `offset`, and responsive breakpoints (`xs` through `xxl`).
 
 ## Usage
 

packages/react/src/flex/index.zh_CN.md

@@ -13,7 +13,21 @@ import WrapSource from './demo/Wrap.tsx?raw';
 
 ## 使用场景
 
-需要轻量级弹性布局时使用，无需为每个子元素添加额外的包裹元素。
+Flex 是一个一维布局容器，适合将元素排列在一行或一列中。
+
+- **工具栏与操作栏** — 将一组按钮、图标或控件水平排列，间距一致。
+- **导航菜单** — 水平排列导航项，或构建垂直侧边栏列表。
+- **表单字段行** — 将标签、输入框和提示文字并排放置。
+- **卡片头部 / 底部** — 使用 `justify="space-between"` 将操作按钮推到两端。
+- **垂直堆叠** — 使用 `vertical` 纵向堆叠内容，如卡片列表或设置分组。
+- **标签 / 徽标组** — 配合 `wrap="wrap"` 和统一的 `gap` 渲染可自动换行的标签集合。
+
+### Flex 与 Row 的区别
+
+两者底层都使用 Flexbox，但适用场景不同：
+
+- 选择 **Flex** — 需要一个通用的弹性盒子容器，使用 CSS `gap` 控制间距，不涉及栏数语义。
+- 选择 **Row / Col** — 需要 24 栏栅格结构，使用 `span`、`offset` 和响应式断点（`xs` 到 `xxl`）。
 
 ## 使用方式
 

packages/react/src/grid/index.md

@@ -25,9 +25,24 @@ import { Grid } from 'tiny-design';
 
 ## When To Use
 
-- Use `Grid System` (`Row` / `Col`) for classic page columns, marketing layouts, and 24-column responsive structure.
-- Use `Grid` for dashboard shells, editor workbenches, card walls, named areas, row spanning, and two-dimensional composition.
-- If you are migrating from MUI `Grid`, start with `spacing`, `rowSpacing`, `columnSpacing`, `size`, and `offset`, then adopt `areas` or `rowSpan` when you need layouts that flex grids cannot express.
+Grid is a two-dimensional layout component built on CSS Grid. It excels when you need control over both rows **and** columns simultaneously.
+
+- **Dashboard shells** — define named `areas` like `"sidebar header" "sidebar main"` for application-level page structure.
+- **Card walls / galleries** — use `minColumnWidth` with `autoFit` to create responsive card grids that reflow without manual breakpoints.
+- **Data-dense UIs** — use explicit `columns` and `rows` to build spreadsheet-like or calendar-like layouts where items span multiple rows or columns.
+- **Asymmetric layouts** — use `Grid.Item colSpan` and `rowSpan` to create hero sections or featured cards that span across tracks.
+- **Responsive rearrangement** — pass responsive objects to `columns`, `gap`, and `areas` to radically change the layout across breakpoints (e.g. stacking sidebar below content on mobile).
+
+### Grid vs Grid System (Row / Col)
+
+| | Grid | Grid System (Row / Col) |
+|---|---|---|
+| CSS technology | CSS Grid | Flexbox + 24-column math |
+| Dimensions | Two-dimensional (rows + columns) | One-dimensional (columns only) |
+| Best for | Dashboards, card walls, named areas, row spanning | Classic page columns, form layouts, marketing pages |
+| Responsive | Responsive props on any value | Breakpoint props (`xs`–`xxl`) on Col |
+
+- If you are migrating from **MUI Grid**, start with `spacing`, `rowSpacing`, `columnSpacing`, `size`, and `offset`, then adopt `areas` or `rowSpan` when you need layouts that flex grids cannot express.
 
 ## Examples
 

packages/react/src/grid/index.zh_CN.md

@@ -25,9 +25,24 @@ import { Grid } from 'tiny-design';
 
 ## 适用场景
 
-- `Grid System`（`Row` / `Col`）更适合经典页面分栏、营销页和 24 栅格结构。
-- `Grid` 更适合 dashboard 壳层、编辑器工作台、卡片墙、命名区域、跨行布局和二维组合。
-- 如果你是从 MUI `Grid` 迁移过来，可以先使用 `spacing`、`rowSpacing`、`columnSpacing`、`size`、`offset`，再逐步使用 `areas` 和 `rowSpan` 这些更强的 CSS Grid 能力。
+Grid 是一个基于 CSS Grid 的二维布局组件，适合同时控制行**和**列的场景。
+
+- **Dashboard 壳层** — 使用 `areas` 定义命名区域，如 `"sidebar header" "sidebar main"`，构建应用级页面骨架。
+- **卡片墙 / 图库** — 使用 `minColumnWidth` 配合 `autoFit`，创建无需手动断点即可自动回流的响应式卡片网格。
+- **数据密集型界面** — 使用显式 `columns` 和 `rows`，构建类似表格或日历的布局，子项可跨越多行多列。
+- **非对称布局** — 使用 `Grid.Item` 的 `colSpan` 和 `rowSpan`，创建跨轨道的 Hero 区域或特色卡片。
+- **响应式重排** — 向 `columns`、`gap`、`areas` 传入响应式对象，在不同断点下彻底改变布局（如移动端将侧边栏堆叠到内容下方）。
+
+### Grid 与 Grid System（Row / Col）对比
+
+| | Grid | Grid System（Row / Col） |
+|---|---|---|
+| CSS 技术 | CSS Grid | Flexbox + 24 栏数学计算 |
+| 布局维度 | 二维（行 + 列） | 一维（仅列） |
+| 最佳场景 | Dashboard、卡片墙、命名区域、跨行布局 | 经典页面分栏、表单布局、营销页 |
+| 响应式方式 | 任意属性均支持响应式对象 | Col 上的断点属性（`xs`–`xxl`） |
+
+- 如果你是从 **MUI Grid** 迁移过来，可以先使用 `spacing`、`rowSpacing`、`columnSpacing`、`size`、`offset`，再逐步使用 `areas` 和 `rowSpan` 这些更强的 CSS Grid 能力。
 
 ## 代码示例
 

packages/react/src/row/index.md

@@ -21,6 +21,24 @@ Use `Row` and `Col` to build classic 24-column page grids with responsive breakp
 import { Row, Col } from 'tiny-design';
 ```
 
+## When To Use
+
+Grid System provides a familiar 24-column grid powered by Flexbox — the same mental model used by Bootstrap and Ant Design.
+
+- **Page-level content columns** — split a page into sidebar (6 columns) and main content (18 columns) with a single `gutter`.
+- **Form layouts** — align labels and inputs into consistent columns across different form sections.
+- **Marketing / landing pages** — create hero sections, feature grids, and pricing tables with predictable column math.
+- **Responsive column shifting** — use breakpoint props (`xs` through `xxl`) on `Col` to stack columns on mobile and spread them on desktop.
+- **Column offset & reordering** — use `offset` to create whitespace and `order` to rearrange columns visually without changing DOM order.
+
+### Choosing between layout components
+
+| Scenario | Recommended |
+|---|---|
+| Toolbar, button group, inline tags | **Flex** |
+| Page columns, form grid, marketing layout | **Grid System** (Row / Col) |
+| Dashboard shell, card wall, named areas, row spanning | **Grid** |
+
 ## Examples
 
 <Demo>

packages/react/src/row/index.zh_CN.md

@@ -21,6 +21,24 @@ import ResponsiveSource from '../grid/demo/Responsive.tsx?raw';
 import { Row, Col } from 'tiny-design';
 ```
 
+## 使用场景
+
+Grid System 提供基于 Flexbox 的 24 栏栅格系统，与 Bootstrap 和 Ant Design 的心智模型一致。
+
+- **页面级内容分栏** — 将页面拆分为侧边栏（6 栏）和主内容区（18 栏），通过 `gutter` 统一控制间距。
+- **表单布局** — 将标签和输入框对齐到一致的列中，保证不同表单区域的视觉统一。
+- **营销 / 落地页** — 创建 Hero 区域、功能网格和价格表，列数计算直观可预测。
+- **响应式列变化** — 在 `Col` 上使用断点属性（`xs` 到 `xxl`），实现移动端堆叠、桌面端展开。
+- **列偏移与重排** — 使用 `offset` 创建留白，使用 `order` 在不改变 DOM 顺序的情况下调整视觉排列。
+
+### 布局组件选择指南
+
+| 场景 | 推荐组件 |
+|---|---|
+| 工具栏、按钮组、内联标签 | **Flex** |
+| 页面分栏、表单栅格、营销页 | **Grid System**（Row / Col） |
+| Dashboard 壳层、卡片墙、命名区域、跨行布局 | **Grid** |
+
 ## 代码示例
 
 <Demo>