react-extjs 0.0.1

package/src/components/ImageOrganizerService.ts

@@ -0,0 +1,361 @@
+/**
+ * Image Organizer 服务端能力模拟层（Mock Backend / Service Layer）。
+ *
+ * 原始 `examples/image-organizer` 是一个完整的服务端应用：PHP + SQLite，通过
+ * Ext.Direct（命名空间 `Imgorg.ss`）暴露 `Albums` / `Images` / `Tags` 三组 action。
+ * 本文件用内存数组模拟这套 SQLite 表，并以**完全一致的异步 Promise 接口**暴露，
+ * 使得前端组件无需关心数据来自内存还是真实 HTTP 后端——日后只需提供一个实现了
+ * `ImageOrganizerService` 接口的实例（例如基于 fetch/axios 的 HTTP 实现），
+ * 即可无缝对接真实后端，组件层零改动。
+ *
+ * ┌─ 原始 Ext.Direct API（php/config.php） ───────────────────────────────┐
+ * │ Imgorg.ss.Albums.loadtree()        → getAlbums()                      │
+ * │ Imgorg.ss.Albums.addOrUpdate(d)    → createAlbum() / renameAlbum()    │
+ * │ Imgorg.ss.Albums.remove(d)         → deleteAlbum()                    │
+ * │ Imgorg.ss.Albums.getAllInfo(d)     → getAlbumSummaries()              │
+ * │ Imgorg.ss.Albums.getAlbums({image})→ getAlbums() + 前端过滤           │
+ * │ Imgorg.ss.Images.load({tags,album})→ getImages({albumId,tags})        │
+ * │ Imgorg.ss.Images.upload(d,files)   → uploadImage(file)                │
+ * │ Imgorg.ss.Images.addToAlbum(d)     → addImagesToAlbum()               │
+ * │ Imgorg.ss.Images.tagImage(d)       → tagImage()                       │
+ * │ Imgorg.ss.Images.rename(d)         → renameImage()                    │
+ * │ Imgorg.ss.Images.remove(d)         → deleteImages()                   │
+ * │ Imgorg.ss.Images.getInfo(d)        → getImageInfo()                   │
+ * │ Imgorg.ss.Tags.load({query})       → getTags(query)                   │
+ * │ Imgorg.ss.Tags.getTags({image})    → getTagsForImage(image)           │
+ * └───────────────────────────────────────────────────────────────────────┘
+ *
+ * 与原始 schema 的取舍：原始 Images 表只有单列 `album_id`（一张图只属一个相册），
+ * 而本 React UI 支持「同一张图拖入多个相册」（多对多）。因此本 mock 用
+ * `albumImages: Map<albumId, Set<imageId>>` 表达分组关系，比原 schema 更贴合 UI，
+ * 同时真实后端也可用中间表（album_images）等价实现。
+ */
+
+export interface ImgItem {
+  id: string;
+  name: string;
+  /** 缩略图底色（无真实图片时用色块近似，等价 ext thumb 背景 #dddddd） */
+  color?: string;
+  /** 缩略图地址（可选；提供则渲染 <img>，否则用内联 SVG 自包含缩略图） */
+  url?: string;
+  /** 字节大小（File Info 展示用） */
+  size?: number;
+  width?: number;
+  height?: number;
+  tags?: string[];
+}
+
+export interface AlbumModel {
+  id: string;
+  name: string;
+  /** 该相册包含的全部图片 id（等价原始 albums 子节点映射） */
+  imageIds: string[];
+  /** 封面图片 id（画廊取首图作为封面） */
+  coverId?: string;
+}
+
+export interface TagModel {
+  id: string;
+  text: string;
+}
+
+export interface ImageInfo {
+  id: string;
+  name: string;
+  size?: number;
+  width?: number;
+  height?: number;
+  tags: string[];
+  /** 该图片所属相册的名称列表（等价原始 Albums.getAlbums） */
+  albums: string[];
+}
+
+/** 等价原始 getAlbumSummaries / getAllInfo：带图片数的相册（画廊用） */
+export interface AlbumSummary extends AlbumModel {
+  count: number;
+}
+
+/**
+ * 服务端契约。组件只依赖此接口，不关心底层是内存 mock 还是真实 HTTP。
+ * 所有方法返回 Promise，模拟网络往返；实现可注入（见 `service` prop）。
+ */
+export interface ImageOrganizerService {
+  // ============================ Albums ============================
+  /** 等价 Albums.loadtree / getAlbums：返回全部相册及分组关系 */
+  getAlbums(): Promise<AlbumModel[]>;
+  /** 等价 Albums.addOrUpdate（新增）：创建相册，id 可由调用方指定（mock 自动分配） */
+  createAlbum(input: { id?: string; name: string }): Promise<AlbumModel>;
+  /** 等价 Albums.addOrUpdate（更新）：相册改名 */
+  renameAlbum(id: string, name: string): Promise<AlbumModel>;
+  /** 等价 Albums.remove：删除相册及其分组关系（不删图片本体） */
+  deleteAlbum(id: string): Promise<void>;
+  /** 等价 Albums.getAllInfo：返回带图片数的相册（画廊用） */
+  getAlbumSummaries(): Promise<AlbumSummary[]>;
+
+  // ============================ Images ============================
+  /** 等价 Images.load：按条件查询图片（albumId / tags 过滤） */
+  getImages(query?: { albumId?: string; tags?: string[] }): Promise<ImgItem[]>;
+  /** 等价 Images.upload：上传文件（mock 内用 objectURL 模拟落地） */
+  uploadImage(file: File, meta?: Partial<ImgItem>): Promise<ImgItem>;
+  /** 等价 Images.addToAlbum：将图片加入相册（幂等去重） */
+  addImagesToAlbum(imageIds: string[], albumId: string): Promise<void>;
+  /** 从相册移除分组关系（不删图片本体） */
+  removeImagesFromAlbum(imageIds: string[], albumId: string): Promise<void>;
+  /** 等价 Images.rename：改名（file move 未模拟，仅改记录名/url） */
+  renameImage(id: string, name: string): Promise<ImgItem>;
+  /** 等价 Images.remove：删除图片本体及所有分组/标签关系 */
+  deleteImages(ids: string[]): Promise<void>;
+  /** 等价 Images.getInfo：图片元数据 / exif */
+  getImageInfo(id: string): Promise<ImageInfo>;
+
+  // ============================ Tags ============================
+  /** 等价 Tags.load：标签检索（type-ahead） */
+  getTags(query?: string): Promise<TagModel[]>;
+  /** 等价 Tags.getTags：某图片的标签 */
+  getTagsForImage(imageId: string): Promise<TagModel[]>;
+  /** 等价 Images.tagImage：给图片打标签（标签不存在则新建） */
+  tagImage(imageIds: string[], tag: string): Promise<void>;
+  /** 移除图片的某个标签 */
+  untagImage(imageId: string, tag: string): Promise<void>;
+}
+
+export interface MockSeed {
+  albums?: AlbumModel[];
+  images?: ImgItem[];
+  tags?: TagModel[];
+}
+
+const delay = (ms: number) => (ms > 0 ? new Promise<void>((r) => setTimeout(r, ms)) : Promise.resolve());
+
+/**
+ * 内存版服务端实现：用 Map/Set 模拟 SQLite 表。
+ * - albums: id → {id,name}
+ * - images: id → ImgItem
+ * - albumImages: albumId → Set<imageId>
+ * - tags: id → text
+ * - imageTags: imageId → Set<tagId>
+ */
+export class MockImageOrganizerService implements ImageOrganizerService {
+  private albums = new Map<string, { id: string; name: string }>();
+  private images = new Map<string, ImgItem>();
+  private albumImages = new Map<string, Set<string>>();
+  private tags = new Map<string, string>(); // id → text
+  private imageTags = new Map<string, Set<string>>(); // imageId → Set<tagId>
+  private albumSeq = 0;
+  private imageSeq = 0;
+  private tagSeq = 0;
+  /** 模拟网络延迟（毫秒），默认 0（即时）。真实后端可视为 RTT。 */
+  readonly latency: number;
+
+  constructor(seed?: MockSeed, latency = 0) {
+    this.latency = latency;
+    (seed?.tags ?? []).forEach((t) => this.tags.set(t.id, t.text));
+    (seed?.images ?? []).forEach((img) => {
+      this.images.set(img.id, { ...img });
+      (img.tags ?? []).forEach((txt) => {
+        const tid = this.ensureTag(txt);
+        this.addImageTag(img.id, tid);
+      });
+    });
+    (seed?.albums ?? []).forEach((a) => {
+      this.albums.set(a.id, { id: a.id, name: a.name });
+      const set = new Set<string>();
+      a.imageIds.forEach((id) => {
+        if (this.images.has(id)) set.add(id);
+      });
+      this.albumImages.set(a.id, set);
+    });
+  }
+
+  private ensureTag(text: string): string {
+    for (const [id, t] of this.tags) if (t === text) return id;
+    const id = `tag-${++this.tagSeq}`;
+    this.tags.set(id, text);
+    return id;
+  }
+
+  private addImageTag(imageId: string, tagId: string) {
+    if (!this.imageTags.has(imageId)) this.imageTags.set(imageId, new Set());
+    this.imageTags.get(imageId)!.add(tagId);
+  }
+
+  private async readDimensions(url?: string): Promise<{ width?: number; height?: number }> {
+    if (!url || url.startsWith('data:')) return {};
+    return new Promise((resolve) => {
+      const img = new Image();
+      img.onload = () => resolve({ width: img.naturalWidth, height: img.naturalHeight });
+      img.onerror = () => resolve({});
+      img.src = url;
+    });
+  }
+
+  // ---------------------------- Albums ----------------------------
+  async getAlbums(): Promise<AlbumModel[]> {
+    await delay(this.latency);
+    return Array.from(this.albums.values()).map((a) => ({
+      id: a.id,
+      name: a.name,
+      imageIds: Array.from(this.albumImages.get(a.id) ?? []),
+    }));
+  }
+
+  async createAlbum(input: { id?: string; name: string }): Promise<AlbumModel> {
+    await delay(this.latency);
+    const id = input.id ?? `album-${++this.albumSeq}-${Date.now()}`;
+    this.albums.set(id, { id, name: input.name });
+    if (!this.albumImages.has(id)) this.albumImages.set(id, new Set());
+    return { id, name: input.name, imageIds: [] };
+  }
+
+  async renameAlbum(id: string, name: string): Promise<AlbumModel> {
+    await delay(this.latency);
+    const a = this.albums.get(id);
+    if (!a) throw new Error(`Album not found: ${id}`);
+    a.name = name;
+    return { id, name, imageIds: Array.from(this.albumImages.get(id) ?? []) };
+  }
+
+  async deleteAlbum(id: string): Promise<void> {
+    await delay(this.latency);
+    this.albums.delete(id);
+    this.albumImages.delete(id);
+  }
+
+  async getAlbumSummaries(): Promise<AlbumSummary[]> {
+    await delay(this.latency);
+    return Array.from(this.albums.values()).map((a) => {
+      const ids = Array.from(this.albumImages.get(a.id) ?? []);
+      return { id: a.id, name: a.name, imageIds: ids, count: ids.length };
+    });
+  }
+
+  // ---------------------------- Images ----------------------------
+  async getImages(query?: { albumId?: string; tags?: string[] }): Promise<ImgItem[]> {
+    await delay(this.latency);
+    let list = Array.from(this.images.values());
+    if (query?.albumId) {
+      const set = this.albumImages.get(query.albumId) ?? new Set();
+      list = list.filter((i) => set.has(i.id));
+    }
+    if (query?.tags && query.tags.length) {
+      list = list.filter((i) => {
+        const myTags = this.imageTags.get(i.id);
+        if (!myTags) return false;
+        const texts = Array.from(myTags).map((tid) => this.tags.get(tid) ?? '');
+        return query.tags!.every((t) => texts.includes(t));
+      });
+    }
+    return list.map((i) => ({ ...i, tags: [...(i.tags ?? [])] }));
+  }
+
+  async uploadImage(file: File, meta?: Partial<ImgItem>): Promise<ImgItem> {
+    await delay(this.latency);
+    const id = `up-${++this.imageSeq}-${Date.now()}`;
+    const isImg = file.type.startsWith('image/');
+    const url = isImg ? URL.createObjectURL(file) : undefined;
+    const dims = await this.readDimensions(url);
+    const item: ImgItem = {
+      id,
+      name: file.name,
+      url,
+      color: isImg ? undefined : '#cccccc',
+      size: file.size,
+      ...dims,
+      ...meta,
+    };
+    this.images.set(id, { ...item, tags: [] });
+    if (meta?.tags) meta.tags.forEach((t) => this.addImageTag(id, this.ensureTag(t)));
+    return { ...item, tags: [...(meta?.tags ?? [])] };
+  }
+
+  async addImagesToAlbum(imageIds: string[], albumId: string): Promise<void> {
+    await delay(this.latency);
+    if (!this.albumImages.has(albumId)) this.albumImages.set(albumId, new Set());
+    const set = this.albumImages.get(albumId)!;
+    imageIds.forEach((id) => {
+      if (this.images.has(id)) set.add(id); // 幂等去重
+    });
+  }
+
+  async removeImagesFromAlbum(imageIds: string[], albumId: string): Promise<void> {
+    await delay(this.latency);
+    const set = this.albumImages.get(albumId);
+    if (set) imageIds.forEach((id) => set.delete(id));
+  }
+
+  async renameImage(id: string, name: string): Promise<ImgItem> {
+    await delay(this.latency);
+    const img = this.images.get(id);
+    if (!img) throw new Error(`Image not found: ${id}`);
+    img.name = name;
+    return { ...img, tags: [...(img.tags ?? [])] };
+  }
+
+  async deleteImages(ids: string[]): Promise<void> {
+    await delay(this.latency);
+    ids.forEach((id) => {
+      this.images.delete(id);
+      this.imageTags.delete(id);
+      this.albumImages.forEach((set) => set.delete(id));
+    });
+  }
+
+  async getImageInfo(id: string): Promise<ImageInfo> {
+    await delay(this.latency);
+    const img = this.images.get(id);
+    if (!img) throw new Error(`Image not found: ${id}`);
+    const tagIds = this.imageTags.get(id) ?? new Set();
+    const tags = Array.from(tagIds).map((tid) => this.tags.get(tid) ?? '');
+    const albums: string[] = [];
+    this.albumImages.forEach((set, albumId) => {
+      if (set.has(id)) {
+        const a = this.albums.get(albumId);
+        if (a) albums.push(a.name);
+      }
+    });
+    return {
+      id,
+      name: img.name,
+      size: img.size,
+      width: img.width,
+      height: img.height,
+      tags,
+      albums,
+    };
+  }
+
+  // ---------------------------- Tags ----------------------------
+  async getTags(query?: string): Promise<TagModel[]> {
+    await delay(this.latency);
+    const q = query?.trim().toLowerCase();
+    return Array.from(this.tags.entries())
+      .filter(([, text]) => !q || text.toLowerCase().includes(q))
+      .map(([id, text]) => ({ id, text }));
+  }
+
+  async getTagsForImage(imageId: string): Promise<TagModel[]> {
+    await delay(this.latency);
+    const tagIds = this.imageTags.get(imageId) ?? new Set();
+    return Array.from(tagIds).map((tid) => ({ id: tid, text: this.tags.get(tid) ?? '' }));
+  }
+
+  async tagImage(imageIds: string[], tag: string): Promise<void> {
+    await delay(this.latency);
+    const tid = this.ensureTag(tag);
+    imageIds.forEach((id) => {
+      if (this.images.has(id)) this.addImageTag(id, tid);
+    });
+  }
+
+  async untagImage(imageId: string, tag: string): Promise<void> {
+    await delay(this.latency);
+    let tid: string | undefined;
+    for (const [id, t] of this.tags) if (t === tag) { tid = id; break; }
+    if (tid && this.imageTags.has(imageId)) this.imageTags.get(imageId)!.delete(tid);
+  }
+}
+
+/** 创建内存 mock 服务实例（默认数据源）。seed 通常来自组件初始 albums/images 或后端预置。 */
+export function createMockImageOrganizerService(seed?: MockSeed, latency = 0): ImageOrganizerService {
+  return new MockImageOrganizerService(seed, latency);
+}

package/src/components/ListView.tsx

@@ -0,0 +1,221 @@
+import React, {
+  useState,
+  useMemo,
+  useId,
+  forwardRef,
+  useImperativeHandle,
+  useRef,
+} from 'react';
+
+export interface ListViewColumn {
+  /** 列标题 */
+  header: string;
+  /** 数据字段名 */
+  dataIndex: string;
+  /** 占容器宽度的比例（0~1），未指定时与其他未指定列均分剩余比例 */
+  width?: number;
+  /** 文本对齐：left/center/right（默认 left） */
+  align?: 'left' | 'center' | 'right';
+  /** 单元格内容格式化函数（默认直接显示原始值） */
+  format?: (value: unknown, row: Record<string, unknown>) => React.ReactNode;
+}
+
+export interface ListViewProps {
+  /** 容器宽度（px），等同 Ext width 配置，注入到根元素 */
+  width?: number;
+  /** 容器高度（px），等同 Ext height 配置，注入到根元素 */
+  height?: number;
+  /** 列定义 */
+  columns: ListViewColumn[];
+  /** 行数据（静态项来源；动态增删经 ref 接口，不破坏此 prop） */
+  data: Record<string, unknown>[];
+  /** 是否多选（Ctrl+点击累加），等同 Ext multiSelect */
+  multiSelect?: boolean;
+  /** 初始选中行索引（可多选传数组） */
+  value?: number | number[];
+  /** 根容器附加 class（测试用 data-testid 等由外层包裹） */
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+export interface ListViewHandle {
+  /** 追加一行，返回该行稳定 id（可用于 remove）。data 为静态项来源不受影响。 */
+  add: (row: Record<string, unknown>, id?: string) => string;
+  /** 按动态 id 删除一行 */
+  remove: (id: string) => void;
+  /** 按当前（合并后）行索引删除一行，并同步调整选中索引 */
+  removeByIndex: (index: number) => void;
+  /** 返回合并后的全部行数据 */
+  getItems: () => Record<string, unknown>[];
+  /** 返回当前选中行索引数组 */
+  getSelected: () => number[];
+}
+
+const HEADER_HEIGHT = 22;
+
+/**
+ * 复刻 Ext.list.ListView（Ext 3.2.1）。
+ * DOM 严格对齐 src/widgets/list/ListView.js：
+ *   x-list-wrap(注入 width/height)
+ *     > x-list-header > x-list-header-inner
+ *         > (每列) div[style width %;text-align] > em[unselectable=on]{header}
+ *         > div.x-clear
+ *     > x-list-body[height=总高-22] > x-list-body-inner
+ *         > (每行) dl[选中 x-list-selected / 悬停 x-list-over]
+ *             > (每列) dt[width %;text-align] > em[unselectable=on]{value}
+ *             > div.x-clear
+ * 仅用 ext-all.css 已有规则（x-list-*），零 CSS 契约破坏。
+ *
+ * 动态增删沿用「data prop 为静态项来源 + 独立 dynamicData 状态」双轨：
+ *   managed = [...data种子, ...dynamicData]，未开动态时 managed===data 映射，DOM 完全一致。
+ */
+export const ListView = forwardRef<ListViewHandle, ListViewProps>(function ListView(
+  {
+    width = 300,
+    height = 200,
+    columns,
+    data,
+    multiSelect = false,
+    value,
+    className,
+    style,
+  },
+  ref
+) {
+  const baseId = useId().replace(/:/g, '');
+  const dynIdRef = useRef(0);
+  const [dynamicData, setDynamicData] = useState<
+    { id: string; row: Record<string, unknown> }[]
+  >([]);
+  // 被程序化删除的静态种子行（按原始 data 索引），对齐 Ext store.remove 可删任意记录
+  const [removedStatic, setRemovedStatic] = useState<Set<number>>(new Set());
+
+  // 计算列宽比例（对齐 ListView.initComponent 的 auto 分配算法）
+  const resolvedColumns = useMemo(() => {
+    const maxWidth = 100;
+    const allocated = columns.reduce((s, c) => s + (c.width ? c.width * 100 : 0), 0);
+    const without = columns.filter((c) => !c.width).length;
+    const remaining = maxWidth - allocated;
+    const per = without > 0 ? remaining / without / 100 : 0;
+    return columns.map((c) => ({ ...c, _w: (c.width ?? per) * 100 }));
+  }, [columns]);
+
+  // 双轨：静态项种子（剔除已删）+ 独立动态态，绝不被 data prop 变更冲掉
+  const managed = useMemo(() => {
+    const staticItems = data
+      .map((row, i) => ({ key: `seed-${i}`, row, origin: 'seed' as const, dataIdx: i }))
+      .filter((it) => !removedStatic.has(it.dataIdx));
+    const dynItems = dynamicData.map((d) => ({
+      key: `dyn-${d.id}`,
+      row: d.row,
+      origin: 'dyn' as const,
+    }));
+    return [...staticItems, ...dynItems];
+  }, [data, dynamicData, removedStatic]);
+
+  const [selected, setSelected] = useState<Set<number>>(() => {
+    const s = new Set<number>();
+    if (Array.isArray(value)) value.forEach((i) => s.add(i));
+    else if (typeof value === 'number') s.add(value);
+    return s;
+  });
+  const [hovered, setHovered] = useState<number | null>(null);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      add: (row: Record<string, unknown>, id?: string) => {
+        const newId = id ?? `d${++dynIdRef.current}`;
+        setDynamicData((prev) => [...prev, { id: newId, row }]);
+        return newId;
+      },
+      remove: (id: string) =>
+        setDynamicData((prev) => prev.filter((d) => d.id !== id)),
+      removeByIndex: (index: number) => {
+        const item = managed[index];
+        if (!item) return;
+        if (item.origin === 'dyn') {
+          setDynamicData((prev) => prev.filter((d) => `dyn-${d.id}` !== item.key));
+        } else {
+          setRemovedStatic((prev) => new Set(prev).add(item.dataIdx));
+        }
+        // 同步调整选中索引（删除点之后的索引前移）
+        setSelected((prev) => {
+          const next = new Set<number>();
+          prev.forEach((s) => {
+            if (s === index) return;
+            next.add(s > index ? s - 1 : s);
+          });
+          return next;
+        });
+      },
+      getItems: () => managed.map((m) => m.row),
+      getSelected: () => Array.from(selected).sort((a, b) => a - b),
+    }),
+    [managed, selected]
+  );
+
+  const handleRowClick = (idx: number, e: React.MouseEvent) => {
+    if (multiSelect && (e.ctrlKey || e.metaKey)) {
+      setSelected((prev) => {
+        const next = new Set(prev);
+        if (next.has(idx)) next.delete(idx);
+        else next.add(idx);
+        return next;
+      });
+    } else {
+      setSelected(new Set([idx]));
+    }
+  };
+
+  return (
+    <div
+      className={['x-list-wrap', className].filter(Boolean).join(' ')}
+      style={{ width, height, ...style }}
+    >
+      <div className="x-list-header">
+        <div className="x-list-header-inner">
+          {resolvedColumns.map((c, i) => (
+            <div key={i} style={{ width: `${c._w}%`, textAlign: c.align ?? 'left' }}>
+              <em unselectable="on" id={`${baseId}-xlhd-${i + 1}`}>
+                {c.header}
+              </em>
+            </div>
+          ))}
+          <div className="x-clear"></div>
+        </div>
+      </div>
+      <div className="x-list-body" style={{ height: height - HEADER_HEIGHT }}>
+        <div className="x-list-body-inner">
+          {managed.map((item, ri) => (
+            <dl
+              key={item.key}
+              className={[
+                selected.has(ri) ? 'x-list-selected' : '',
+                hovered === ri ? 'x-list-over' : '',
+              ]
+                .filter(Boolean)
+                .join(' ')}
+              onMouseEnter={() => setHovered(ri)}
+              onMouseLeave={() => setHovered((h) => (h === ri ? null : h))}
+              onClick={(e) => handleRowClick(ri, e)}
+            >
+              {resolvedColumns.map((c, ci) => {
+                const raw = item.row[c.dataIndex];
+                const content = c.format
+                  ? c.format(raw, item.row)
+                  : (raw as React.ReactNode);
+                return (
+                  <dt key={ci} style={{ width: `${c._w}%`, textAlign: c.align ?? 'left' }}>
+                    <em unselectable="on">{content}</em>
+                  </dt>
+                );
+              })}
+              <div className="x-clear"></div>
+            </dl>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+});

package/src/components/LoadMask.tsx

@@ -0,0 +1,74 @@
+import React, { type CSSProperties, type ReactNode } from 'react';
+
+export interface LoadMaskProps {
+  /** 是否显示遮罩（默认 true） */
+  loading?: boolean;
+  /** 遮罩消息文案（默认 'Loading...'） */
+  msg?: string;
+  /** 消息框附加 class（默认 'x-mask-loading'，带 loading.gif） */
+  msgCls?: string;
+  /** 容器宽度（默认 300） */
+  width?: number | string;
+  /** 容器高度（默认 160） */
+  height?: number | string;
+  /** 测试锚点（落在根元素，用于 fidelity 对比） */
+  testId?: string;
+  className?: string;
+  style?: CSSProperties;
+  children?: ReactNode;
+}
+
+/**
+ * 复刻 Ext.LoadMask / Ext.Element.mask(msg, msgCls)。
+ *
+ * DOM 对齐 Element.fx-more.js 的 mask()：
+ *   <div class="x-masked" style="position:relative;overflow:hidden">  (被遮罩容器)
+ *     {children}
+ *     <div class="ext-el-mask" />                            (半透明遮罩层，铺满容器)
+ *     <div class="ext-el-mask-msg {msgCls}">                 (居中消息框)
+ *       <div>{msg}</div>                                     (消息文本)
+ *     </div>
+ *   </div>
+ *
+ * 视觉完全由 ext-all.css 既有规则驱动（零 CSS 契约破坏）：
+ *   .ext-el-mask           -> 背景 #ccc，opacity .5，铺满
+ *   .ext-el-mask-msg       -> 蓝色边框 + tb-blue.gif 横纹背景
+ *   .ext-el-mask-msg div   -> #eee 底 + 边框 + 11px tahoma
+ *   .x-mask-loading div    -> loading.gif 旋转图标 + #fbfbfb
+ */
+export const LoadMask: React.FC<LoadMaskProps> = ({
+  loading = true,
+  msg = 'Loading...',
+  msgCls = 'x-mask-loading',
+  width = 300,
+  height = 160,
+  testId,
+  className,
+  style,
+  children,
+}) => {
+  return (
+    <div
+      data-testid={testId}
+      className={['x-masked', className].filter(Boolean).join(' ')}
+      style={{
+        position: 'relative',
+        width,
+        height,
+        overflow: 'hidden',
+        ...style,
+      }}
+    >
+      {children}
+      {loading && <div className="ext-el-mask" />}
+      {loading && msg != null && (
+        <div
+          className={['ext-el-mask-msg', msgCls].filter(Boolean).join(' ')}
+          style={{ position: 'absolute', top: '50%', left: '50%', transform: 'translate(-50%,-50%)' }}
+        >
+          <div>{msg}</div>
+        </div>
+      )}
+    </div>
+  );
+};