react-extjs 0.0.1

package/src/components/Panel.tsx

@@ -0,0 +1,451 @@
+import React, { useState, useEffect, useImperativeHandle, forwardRef } from 'react';
+import { Toolbar } from './Toolbar';
+
+export interface PanelTool {
+  /** 工具图标 id，对应 CSS 类 x-tool-{id}（toggle/close/minimize/maximize/gear 等） */
+  id: string;
+  handler?: (e?: React.MouseEvent) => void;
+  /** 是否隐藏该工具（对齐 Ext tool.visible，默认 false 显示） */
+  hidden?: boolean;
+  /** 悬浮提示（对齐 Ext tool.tooltip） */
+  tooltip?: string;
+  /** 点击时是否阻止事件冒泡到 header（默认 true，避免 header 折叠被误触发） */
+  stopEvent?: boolean;
+}
+
+/** 命令式句柄：对齐 Ext.Panel 的公开方法（collapse/expand/toggleCollapse/setTitle/setIconClass 等） */
+export interface PanelHandle {
+  /** 折叠面板 */
+  collapse: () => void;
+  /** 展开面板 */
+  expand: () => void;
+  /** 切换折叠/展开 */
+  toggleCollapse: () => void;
+  /** 运行时修改标题（对齐 setTitle） */
+  setTitle: (title: string) => void;
+  /** 运行时修改标题前图标 class（对齐 setIconClass） */
+  setIconClass: (cls?: string) => void;
+  /** 读取当前折叠态 */
+  getCollapsed: () => boolean;
+}
+
+export interface PanelProps {
+  title?: string;
+  /** true=9 宫格圆角边框；false=1px 方角（默认 false） */
+  frame?: boolean;
+  /** 标题前的图标 class */
+  iconCls?: string;
+  /** 附加在根节点上的 class */
+  cls?: string;
+  /** 是否显示头部（有 title 或 tools 时默认 true） */
+  header?: boolean;
+  /** 折叠态（渲染 x-panel-collapsed） */
+  collapsed?: boolean;
+  collapsible?: boolean;
+  /** collapsible 时不渲染 toggle 工具（默认 false 会渲染 x-tool-toggle） */
+  hideCollapseTool?: boolean;
+  /** 是否显示边框（默认 true；false 加 -noborder 链） */
+  border?: boolean;
+  /** body 内边距 */
+  bodyPadding?: number | string;
+  width?: number | string;
+  height?: number | string;
+  /** 追加到 header class（如 x-accordion-hd） */
+  headerClassName?: string;
+  /** 点击 header 或 toggle 工具回调，用于标题折叠交互 */
+  onHeaderClick?: (e?: React.MouseEvent) => void;
+  /** 透传到 .x-panel-body 的 inline style（对齐 Ext bodyStyle） */
+  bodyStyle?: React.CSSProperties;
+  /**
+   * 区域面板保真模式（BorderLayout 使用）：当提供 height 时，面板锁定为固定高度，
+   * 内部以 flex 纵向排列（header 固定、body flex:1 填满剩余），无论 header 是否因
+   * 长标题换行而变高，面板总尺寸恒等于 height、body 自动收缩，绝不溢出覆盖相邻区域
+   * （对齐 ExtJS region 面板被布局固定为 box.h 的行为）。
+   */
+  bodyFlex?: boolean;
+  /** 追加在 .x-panel-body 上的 class（如 x-table-layout-ct），不影响既有保真 */
+  bodyClassName?: string;
+  tools?: PanelTool[];
+  /** 顶部工具条内容（通常是 Button/Toolbar） */
+  tbar?: React.ReactNode;
+  /** 底部工具条内容 */
+  bbar?: React.ReactNode;
+  /** 底部按钮区（渲染 x-panel-footer x-panel-btns） */
+  footer?: React.ReactNode;
+  /** 底部工具条（对齐 Ext fbar：渲染 x-panel-footer x-panel-fbar，与 footer 按钮互斥场景可单独使用） */
+  fbar?: React.ReactNode;
+  children?: React.ReactNode;
+  style?: React.CSSProperties;
+  /** 根节点基础 class 前缀（默认 'x-panel'；unstyled 时强制为 'x-plain'） */
+  baseCls?: string;
+  /** true 时无样式模式（对齐 Ext unstyled：baseCls 改为 'x-plain'，仅保留布局必需样式） */
+  unstyled?: boolean;
+  /** true 时点击标题栏（任意位置）即可折叠/展开（对齐 Ext titleCollapse，默认 false 仅 toggle 工具可折叠） */
+  titleCollapse?: boolean;
+  /** 受控折叠：抑制组件内部自切换，折叠态完全由 collapsed 属性驱动（Accordion 子面板使用，避免父子双轨冲突） */
+  collapseControlled?: boolean;
+  /** toggle 工具相对自定义 tools 的顺序：true=前置（Ext 默认），false=后置 */
+  collapseFirst?: boolean;
+  /** footer 按钮最小宽度（px，对齐 Ext minButtonWidth，默认 75） */
+  minButtonWidth?: number;
+  /** footer/fbar 底部按钮水平对齐（对齐 Ext buttonAlign，默认 'right'）。'left'|'center'|'right' */
+  buttonAlign?: 'left' | 'center' | 'right';
+  /** footer 水平内边距（px）。消掉「frame 边框内缩 ~6px + footer 内边距」两层叠加导致按钮离左右边框过远；
+   *  底部固定保留 5px（对齐 Ext .x-panel-btns{padding:5px} 的 bottom），避免按钮贴圆角底边框。
+   *  undefined = 保持 Ext 标准 5px（四方向）。 */
+  footerPadding?: number | string;
+  /** 是否禁用面板（对齐 Ext disabled：加 x-item-disabled 并屏蔽交互） */
+  disabled?: boolean;
+}
+
+// 与原版 Ext.BLANK_IMAGE_URL 等价：1x1 透明 gif，避免网络请求
+const BLANK =
+  'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
+
+/**
+ * 保真映射（来源 src/widgets/Panel.js）：
+ * - 模板结构：onRender（frame / 非 frame 两套 DOM），class 名与 Ext JS 3.2.1 完全一致。
+ * - 头部：x-panel-header > span.x-panel-header-text + tools(x-tool x-tool-{id})
+ * - 图标：header 加 x-panel-icon，并插入 img.x-panel-inline-icon {iconCls}
+ * - 状态类：x-panel-collapsed / x-panel-noborder（el+body+header+footer+tbar+bbar）/ x-panel-body-noheader
+ * - unstyled：baseCls 改为 x-plain（x-plain-header/body/tbar/...），仅保留布局必需样式
+ * - fbar：x-panel-footer > x-panel-fbar 底部工具条容器
+ * - 命令式 API：collapse/expand/toggleCollapse/setTitle/setIconClass/getCollapsed
+ * React 仅重写行为与状态，DOM 结构与 class 名与 Ext JS 3.2.1 完全一致。
+ */
+export const Panel = forwardRef<PanelHandle, PanelProps>(function Panel(
+  {
+    title,
+    frame = false,
+    iconCls,
+    cls = '',
+    header,
+    collapsed = false,
+    collapsible = false,
+    hideCollapseTool = false,
+    collapseControlled = false,
+    border = true,
+    bodyPadding,
+    width,
+    height,
+    headerClassName,
+    onHeaderClick,
+    bodyStyle,
+    bodyFlex,
+    bodyClassName,
+    tools,
+    tbar,
+    bbar,
+    footer,
+    fbar,
+    children,
+    style,
+    baseCls,
+    unstyled = false,
+    titleCollapse = false,
+    collapseFirst = true,
+    minButtonWidth,
+    buttonAlign = 'right',
+    footerPadding,
+    disabled = false,
+  },
+  ref,
+) {
+  const b = baseCls ?? (unstyled ? 'x-plain' : 'x-panel');
+  const showHeader =
+    header !== false && (!!title || !!tools?.length || collapsible || !!iconCls);
+  const noborder = border === false;
+
+  // 折叠态：受控(collapsed prop) + 非受控(内部点击切换)双轨。
+  // 原生 .x-panel-collapsed 仅调整边框/图标，body 显隐由 JS 控制（对齐 Ext 行为）。
+  const [dynCollapsed, setDynCollapsed] = useState(collapsed);
+  useEffect(() => {
+    setDynCollapsed(collapsed);
+  }, [collapsed]);
+  // 受控折叠：直接以 collapsed 属性为准，避免依赖 effect 同步产生闪烁
+  const effectiveCollapsed = collapseControlled ? collapsed : dynCollapsed;
+
+  // 运行时标题/图标（对齐 Ext setTitle / setIconClass）
+  const [dynTitle, setDynTitle] = useState(title);
+  const [dynIconCls, setDynIconCls] = useState(iconCls);
+  useEffect(() => {
+    setDynTitle(title);
+  }, [title]);
+  useEffect(() => {
+    setDynIconCls(iconCls);
+  }, [iconCls]);
+
+  // 命令式句柄（对齐 Ext.Panel 公开方法）
+  useImperativeHandle(ref, () => ({
+    collapse: () => setDynCollapsed(true),
+    expand: () => setDynCollapsed(false),
+    toggleCollapse: () => setDynCollapsed((c) => !c),
+    setTitle: (t: string) => setDynTitle(t),
+    setIconClass: (c?: string) => setDynIconCls(c),
+    getCollapsed: () => dynCollapsed,
+  }));
+
+  const handleHeaderClick = (e?: React.MouseEvent) => {
+    onHeaderClick?.(e);
+    if (collapsible && titleCollapse && !collapseControlled) setDynCollapsed((c) => !c);
+  };
+
+  const toggleHandler = (e?: React.MouseEvent) => {
+    onHeaderClick?.(e);
+    if (collapsible && !collapseControlled) setDynCollapsed((c) => !c);
+  };
+
+  // collapsible 时注入 toggle 工具；collapseFirst 决定其相对自定义 tools 的顺序
+  const toggleTool: PanelTool = { id: 'toggle', handler: toggleHandler };
+  const effectiveTools: PanelTool[] = collapsible && !hideCollapseTool
+    ? collapseFirst
+      ? [toggleTool, ...(tools ?? [])]
+      : [...(tools ?? []), toggleTool]
+    : (tools ?? []);
+
+  const headerEl = showHeader ? (
+    <div
+      className={[
+        `${b}-header`,
+        dynIconCls ? `${b}-icon` : '',
+        noborder ? `${b}-header-noborder` : '',
+        headerClassName ?? '',
+      ]
+        .filter(Boolean)
+        .join(' ')}
+      unselectable="on"
+      onClick={handleHeaderClick}
+    >
+      {dynIconCls && (
+        <img className={`${b}-inline-icon ${dynIconCls}`} src={BLANK} alt="" />
+      )}
+      {dynTitle && <span className={`${b}-header-text`}>{dynTitle}</span>}
+      {effectiveTools
+        .filter((t) => !t.hidden)
+        .map((t) => (
+          <div
+            key={t.id}
+            className={`x-tool x-tool-${t.id}`}
+            title={t.tooltip}
+            unselectable="on"
+            onClick={(e) => {
+              // 工具点击默认不冒泡到 header，避免 toggle 被触发两次
+              if (t.stopEvent !== false) e.stopPropagation();
+              t.handler?.(e);
+            }}
+          >
+            &#160;
+          </div>
+        ))}
+    </div>
+  ) : null;
+
+  const bodyClass = [
+    `${b}-body`,
+    !showHeader ? `${b}-body-noheader` : '',
+    noborder ? `${b}-body-noborder` : '',
+    bodyClassName ?? '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  // 区域面板保真模式（bodyFlex）：height 给定时，面板固定高度，内部 flex 纵向排列，
+  // header 不伸缩、body flex:1 填满剩余，header 因长标题换行变高时 body 自动收缩，不溢出。
+  const useFlex = !!bodyFlex && height != null;
+  const bwrapStyle: React.CSSProperties | undefined = useFlex
+    ? { flex: '1 1 0px', minHeight: 0, display: 'flex', flexDirection: 'column', width: '100%' }
+    : undefined;
+  const headerNode = useFlex && headerEl
+    ? React.cloneElement(headerEl, { style: { ...(headerEl.props as any).style, flex: '0 0 auto' } })
+    : headerEl;
+
+  const rootClass = [
+    b,
+    cls,
+    effectiveCollapsed ? `${b}-collapsed` : '',
+    noborder ? `${b}-noborder` : '',
+    disabled ? 'x-item-disabled' : '',
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const rootStyle: React.CSSProperties = {
+    width,
+    height,
+    ...(useFlex ? { display: 'flex', flexDirection: 'column', overflow: 'hidden' } : {}),
+    ...(bodyPadding !== undefined
+      ? {
+          '--x-panel-body-padding':
+            typeof bodyPadding === 'number' ? `${bodyPadding}px` : bodyPadding,
+        }
+      : {}),
+    ...style,
+  };
+
+  // 保真注意：Ext JS 的 frame 面板不将 bodyPadding 作为 inline style 落在
+  // .x-panel-body 上（实测 golden 的 .x-panel-body padding 为 0px）。
+  // frame 面板的内间距由 9 宫格 .x-panel-mc 的 CSS padding 承接；
+  // 非 frame 面板同样不在此处注入，由外部/主题自然决定。
+  // 但 bodyStyle（如 accordion 子面板 padding:15px）由调用方显式传入。
+  const bodyEl = (
+    <div
+      className={bodyClass}
+      style={{
+        ...bodyStyle,
+        ...(useFlex ? { flex: '1 1 auto', minHeight: 0, overflow: 'auto' } : {}),
+        display: effectiveCollapsed ? 'none' : undefined,
+        ...(disabled ? { pointerEvents: 'none' } : {}),
+      }}
+    >
+      {children}
+    </div>
+  );
+
+  // footer（x-panel-footer x-panel-btns）与 fbar（x-panel-footer > x-panel-fbar）对齐 Ext，
+  // 二者可共存；折叠时整体隐藏（保留 DOM 节点，兼容 Accordion 等内部复用）。
+  const footerNodes: React.ReactNode[] = [];
+  if (footer) {
+    footerNodes.push(
+      <div
+        key="btns"
+        className={`${b}-footer ${b}-btns`}
+        style={{
+          ...footerStyle(minButtonWidth),
+          ...footerFlowReset,
+          // footerPadding 控制「水平」内边距（消掉 frame 边框 6px + footer 内边距叠加的观感），
+          // 底部保留 5px（对齐 Ext .x-panel-btns{padding:5px} 的 bottom），避免按钮贴圆角底边框。
+          ...(footerPadding !== undefined
+            ? { padding: `${footerPadding}px ${footerPadding}px 5px ${footerPadding}px` }
+            : {}),
+          display: 'flex',
+          flexWrap: 'wrap',
+          gap: 3,
+          // 对齐 Ext buttonAlign（默认 'right'）：footer 按钮水平对齐方式
+          justifyContent:
+            buttonAlign === 'center'
+              ? 'center'
+              : buttonAlign === 'right'
+              ? 'flex-end'
+              : 'flex-start',
+        }}
+      >
+        {footer}
+      </div>,
+    );
+  }
+  if (fbar) {
+    // 对齐 Ext fbar：原生 Toolbar 根 div 同时带 x-toolbar 与 toolbarCls(x-panel-fbar)
+    // （源码 toolbarCls 是「追加」到 x-toolbar 之上，而非替换）。.x-panel-fbar 仅覆盖
+    // white-space/font，不重设背景/边框，故必须保留 x-toolbar 类，否则 .x-toolbar 下的
+    // 布局表宽(.x-toolbar .x-toolbar-ct{width:100%})与 white-space:nowrap 等规则全部失效，
+    // fbar 内工具栏会因缺少 x-toolbar 样式而溢出面板宽度、按钮换行/错位。
+    // 若调用方传入的是 <Toolbar>，自动注入 footer 风格根类（保留布局/字体辅助类）。
+    // 注：原生 .x-panel-footer 用 position:absolute（依赖 JS 同步 top/width），本 React 实现
+    // 以正常流渲染（tbar/bbar 同理），故以内联 position:static/width:100% 覆盖其 absolute 定位，
+    // 使 footer 自然落在 body 底部一行、宽度充满 Panel（内联优先级最高，胜出原生 .x-panel-bc .x-panel-footer）。
+    const fbarContent =
+      React.isValidElement(fbar) && (fbar as React.ReactElement).type === Toolbar
+        ? React.cloneElement(
+            fbar as React.ReactElement<{ rootClass?: string; buttonAlign?: 'left' | 'center' | 'right' }>,
+            {
+              rootClass: `x-toolbar ${b}-fbar x-toolbar-layout-ct x-small-editor`,
+              buttonAlign,
+            },
+          )
+        : fbar;
+    footerNodes.push(
+      <div key="fbar" className={`${b}-footer`} style={{ ...footerFlowReset }}>
+        {fbarContent}
+      </div>,
+    );
+  }
+  const footerEl = footerNodes.length ? (
+    <div style={effectiveCollapsed ? { display: 'none' } : undefined}>{footerNodes}</div>
+  ) : null;
+
+  if (!frame) {
+    return (
+      <div className={rootClass} style={rootStyle}>
+        {headerNode}
+        <div className={`${b}-bwrap`} style={bwrapStyle}>
+          {tbar && (
+            <div className={`${b}-tbar`} style={effectiveCollapsed ? { display: 'none' } : undefined}>
+              {tbar}
+            </div>
+          )}
+          {bodyEl}
+          {bbar && (
+            <div className={`${b}-bbar`} style={effectiveCollapsed ? { display: 'none' } : undefined}>
+              {bbar}
+            </div>
+          )}
+          {footerEl}
+        </div>
+      </div>
+    );
+  }
+
+  // frame = true：9 宫格圆角结构（与 onRender 实际产出一致）
+  return (
+    <div className={rootClass} style={rootStyle}>
+      <div className={`${b}-tl`}>
+        <div className={`${b}-tr`}>
+          <div className={`${b}-tc`}>{headerNode}</div>
+        </div>
+      </div>
+      <div className={`${b}-bwrap`} style={bwrapStyle}>
+        <div className={`${b}-ml`}>
+          <div className={`${b}-mr`}>
+            <div className={`${b}-mc`}>
+              {tbar && (
+                <div className={`${b}-tbar`} style={effectiveCollapsed ? { display: 'none' } : undefined}>
+                  {tbar}
+                </div>
+              )}
+              {bodyEl}
+              {bbar && (
+                <div className={`${b}-bbar`} style={effectiveCollapsed ? { display: 'none' } : undefined}>
+                  {bbar}
+                </div>
+              )}
+            </div>
+          </div>
+        </div>
+        <div
+          className={`${b}-bl${footerNodes.length ? '' : ` ${b}-nofooter`}`}
+        >
+          <div className={`${b}-br`}>
+            <div
+              className={`${b}-bc`}
+              style={{ height: footerNodes.length ? 'auto' : 6, fontSize: 0, lineHeight: 0 }}
+            >
+              {footerEl}
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+});
+
+// 工具函数（必须在组件外定义，避免每次渲染重建）
+function footerStyle(min?: number): React.CSSProperties {
+  return min !== undefined
+    ? ({ ['--x-panel-minbtn']: `${min}px` } as React.CSSProperties)
+    : {};
+}
+
+// 复位 ext-theme.css 中 `.x-panel-footer { position:absolute; height:9px; overflow:hidden;
+// font-size:1px; line-height:9px }` 的冲突规则（该规则系主题层为底部 resize 手柄保留，
+// 与本项目「footer 以正常流渲染」的约定相悖）。以更高优先级的内联样式完整复位，
+// DOM/class 名保持不变，符合「不新增/不修改 CSS 文件」约束。
+const footerFlowReset: React.CSSProperties = {
+  position: 'static',
+  width: '100%',
+  height: 'auto',
+  overflow: 'visible',
+  fontSize: '12px',
+  lineHeight: 'normal',
+};
+
+export default Panel;

package/src/components/ProgressBar.tsx

@@ -0,0 +1,127 @@
+import React, { forwardRef, useImperativeHandle, useLayoutEffect, useRef, useState, useEffect } from 'react';
+
+export interface ProgressBarProps {
+  /** 进度值 0~1，默认 0 */
+  value?: number;
+  /** 进度条文字，默认空 */
+  text?: string;
+  /** 组件总宽（含边框），默认自适应 */
+  width?: number;
+  /** 额外 class，如 'x-progress-red' */
+  cls?: string;
+  /** 根元素 id */
+  id?: string;
+  /** 点击事件（等价 Ext 给 progress bar 元素绑 'click'），回调携带原始 MouseEvent 便于计算点击位置 */
+  onClick?: (e: React.MouseEvent) => void;
+}
+
+/**
+ * 运行时句柄（对齐 Ext.ProgressBar 公共 API）：
+ * - setProgress(value, text?) / updateProgress(value, text?)：同时更新进度与文字（等价 Ext.updateProgress）
+ * - setText(text)：仅更新文字（Ext 无独立 setText，但 text 随 updateProgress 走）
+ * - setWidth(width)：调整总宽（Ext.setWidth）
+ * - reset()：归零并隐藏白字层（Ext.reset）
+ * - getValue()/getText()/getWidth()：读当前状态
+ */
+export interface ProgressBarHandle {
+  setProgress: (value: number, text?: string) => void;
+  updateProgress: (value: number, text?: string) => void;
+  setText: (text: string) => void;
+  setWidth: (width: number) => void;
+  reset: () => void;
+  getValue: () => number;
+  getText: () => string;
+  getWidth: () => number | undefined;
+}
+
+// 保真映射（来源 Ext.ProgressBar.onRender + afterRender + updateProgress）：
+// - 根 div class = 'x-progress-wrap'（Ext 不会把 baseCls 'x-progress' 作为额外 class 落到 el 上，
+//   仅模板根节点 '{cls}-wrap' = 'x-progress-wrap'）。
+// - 结构：x-progress-wrap > x-progress-inner >
+//            (x-progress-bar > x-progress-text,  x-progress-text.x-progress-text-back)
+// - 根 style.width = 传入 width - 2（1px 边框×2），使视觉总宽=width（golden 实测 200→198）。
+// - bar 像素宽 = floor(value × innerContentW)，与 golden 的 Math.floor(value*firstChild.offsetWidth) 一致。
+// - bar 高度：本项目全局 box-sizing:border-box，故 bar inline height=18 即「含 1px 上下边框的总高 18px」，
+//   与 .x-progress-inner 的 height:18px 完全对齐（若写 16 会在 inner 底部空出 2px 间隙）。
+// - 顶层 text 容器 width = barW - 10（Ext setWidth 折算 padding 1+5+5=10），z-index:99；文字落在其内层 div(width=innerW)。
+// - 文字内层 div 固定 width=innerW、height=18，使文字跨整条进度条居中；顶层白色文字被 bar 宽度裁切，
+//   形成"已填充蓝条内白字 / 未填充灰底深蓝字"的经典分层效果。
+export const ProgressBar = forwardRef<ProgressBarHandle, ProgressBarProps>(
+  ({ value = 0, text = '', width, cls = '', id, onClick }: ProgressBarProps, ref) => {
+    // 双轨：prop 初始化 + 句柄运行时改写 + useEffect 同步 prop 变化
+    const [dynValue, setDynValue] = useState(value);
+    const [dynText, setDynText] = useState(text);
+    const [dynWidth, setDynWidth] = useState(width);
+    const [dynCls, setDynCls] = useState(cls);
+
+    useImperativeHandle(
+      ref,
+      () => ({
+        setProgress: (v: number, t?: string) => {
+          setDynValue(v);
+          if (t !== undefined) setDynText(t);
+        },
+        updateProgress: (v: number, t?: string) => {
+          setDynValue(v);
+          if (t !== undefined) setDynText(t);
+        },
+        setText: (t: string) => setDynText(t),
+        setWidth: (w: number) => setDynWidth(w),
+        reset: () => {
+          setDynValue(0);
+          setDynText('');
+        },
+        getValue: () => dynValue,
+        getText: () => dynText,
+        getWidth: () => dynWidth,
+      }),
+      [dynValue, dynText, dynWidth],
+    );
+
+    useEffect(() => setDynValue(value), [value]);
+    useEffect(() => setDynText(text), [text]);
+    useEffect(() => setDynWidth(width), [width]);
+    useEffect(() => setDynCls(cls), [cls]);
+
+    const innerRef = useRef<HTMLDivElement>(null);
+    const [measuredW, setMeasuredW] = useState(0);
+
+    useLayoutEffect(() => {
+      if (innerRef.current) {
+        setMeasuredW(innerRef.current.offsetWidth);
+      }
+    });
+
+    // 固定 width 时直接推导 innerW（= width-2，对齐 golden 实测），避免首帧 innerW=0 闪现；
+    // 自适应（width 未传）时回退到运行时测量。
+    const innerW = dynWidth != null ? dynWidth - 2 : measuredW;
+
+    const barW = Math.floor(dynValue * innerW);
+    const frontTextW = Math.max(0, barW - 10);
+    // golden 行为：updateProgress(value>0) 时 textTopEl.removeClass('x-hidden')；
+    // reset(value=0) 时 textTopEl.addClass('x-hidden')（白字层隐藏，仅剩灰底深蓝 back 文字）。
+    const frontTextCls = ['x-progress-text', dynValue === 0 ? 'x-hidden' : ''].filter(Boolean).join(' ');
+
+    return (
+      <div
+        className={['x-progress-wrap', dynCls].filter(Boolean).join(' ')}
+        id={id}
+        onClick={onClick}
+        style={{ cursor: onClick ? 'pointer' : undefined, ...(dynWidth != null ? { width: dynWidth - 2 } : undefined) }}
+      >
+        <div className="x-progress-inner" ref={innerRef}>
+          <div className="x-progress-bar" style={{ width: barW, height: 18, transition: 'width 0.3s ease-out' }}>
+            <div className={frontTextCls} style={{ zIndex: 99, width: frontTextW }}>
+              <div style={{ width: innerW, height: 18 }}>{dynText}</div>
+            </div>
+          </div>
+          <div className="x-progress-text x-progress-text-back">
+            <div style={{ width: innerW, height: 18 }}>{dynText}</div>
+          </div>
+        </div>
+      </div>
+    );
+  },
+);
+
+ProgressBar.displayName = 'ProgressBar';