Skip to content

fix(fields): 全屏长文本编辑器的字数计数接入无障碍,计数 UI 收敛为一份共享组件 (#3417) - #3436

Merged
yinlianghui merged 1 commit into
mainfrom
claude/issue-3417-fullscreen-charcount-a11y
Aug 6, 2026
Merged

fix(fields): 全屏长文本编辑器的字数计数接入无障碍,计数 UI 收敛为一份共享组件 (#3417)#3436
yinlianghui merged 1 commit into
mainfrom
claude/issue-3417-fullscreen-charcount-a11y

Conversation

@yinlianghui

@yinlianghui yinlianghui commented Aug 6, 2026

Copy link
Copy Markdown
Collaborator

Fixes #3417

前提复核(先做,再动手)

在 origin/main(875c5fa)上逐条核对了单子的前提,成立:

  • packages/fields/src/widgets/TextAreaField.tsx 的 footer 回调仍然只渲染一串裸数字(text-xs text-muted-foreground self-center 的 span,内容 {draft.length}/{maxLength}):没有可访问名、没有 aria-describedby 把它和对话框里 data-testid="textarea-fullscreen-input" 的 textarea 关联起来、没有任何 aria-live。
  • fix(fields): 字数统计不再每次击键整句重播,改用 describedby + 阈值门控的 debounce 状态区 (#3408) #3416 落地的内联三节点形制存在(aria-hidden 数字 + describedby 描述节点 + 阈值门控 debounce 的 polite 状态节点)。
  • 可达性也复核过:ObjectForm 在 ObjectFormSchema.mobile.fullscreenLongText 打开时给每个长文本字段盖 mobile_fullscreen,手机端开了这个设置的表单里,每个带上限的长文本字段都命中。

顺带核了一件事,结论是不必扩大范围:packages/components/src/renderers/form/form.tsx 的内建分支(form-textarea-fullscreen-* 一套 test id)整个就没有字数计数(它只有 validation.maxLength 校验规则),所以不存在「第三份计数 UI 又漂了」的问题,没有额外要修的分叉。

做法(按裁定的 C 形 + B 行为)

新增 packages/fields/src/widgets/CharacterCount.tsx,从 #3416 的内联实现里抽出来,两个编辑面共用这一份,不再有分叉的手抄件。

  • 内联面行为逐字节不变:同样三个节点、同样的属性顺序、同样的 1s debounce 与「10% 或 20 字符,先到者为准」阈值。fix(fields): 字数统计不再每次击键整句重播,改用 describedby + 阈值门控的 debounce 状态区 (#3408) #3416 那三个测试文件一行没改,前后都绿 —— 这就是「行为没漂」的钉子。
  • 全屏面:aria-hidden 数字 + 视觉隐藏的描述节点,通过 aria-describedby 挂到对话框的 textarea 上;数字与描述都跟 draft 走(对话框是本地草稿,提交前和已保存值会分叉,所以两个面各自一个描述 id)。
  • 全屏面不加 live region:announceNearLimit={false}。理由写在代码注释里 —— 全屏是用户主动打开来长写的模态,描述节点已经在聚焦时把上限说清楚了,而内联那份 live region 在遮罩后面仍然挂着,再加一个就是同一份文档里两个 live region。这一条是以「不存在」的形式断言的,不是靠运气。

关于 FullscreenFieldEditor 的 footer 槽(裁定让我自己判断)

保持 footer 是 ReactNode 回调,FullscreenFieldEditor.tsx 一个字没动。

理由是「更小且诚实」:TextAreaField 同时拥有 footer 和 editor 两侧,是唯一能同时铸出 id 并把它写到 textarea 的 aria-describedby 上的地方,所以这条路只需要 3 行。反过来把 count 提升成一等能力,就要给 children 加第四个参数(描述 id)来把 id 递回宿主 —— 而另一个宿主 RichTextField 根本不传 footer,它会拿到一个永远忽略的参数。那正是这个包一直在删的形状(#3232/#3233:声明了没有生产者的 prop)。代价我也写进注释了:全屏 textarea 的 aria-describedby 是赋值而非追加,因为这个元素是 TextAreaField 自己从零构造的,domProps 根本到不了它,而宿主本会提供的那些 id 指向的是对话框外面的节点 —— 模态打开时被 Radix aria-hidden 掉了,追加进来只会指向读屏读不到的东西。内联那份仍然是追加(#3408 的规则原封不动)。

i18n

没有新键,packages/i18n 一个字节没碰。复用 fields.textarea.characterCount / fields.textarea.charactersRemaining 及其 FIELD_DEFAULTS 兜底;packages/i18n/src/__tests__/textarea-charactercount-locale-parity.test.ts 照跑绿。

反向验证(方向是跑之前定好的)

用 git checkout origin/main -- packages/fields/src/widgets/TextAreaField.tsx 把源文件退回去(测试文件与新组件留着),跑同一组文件 —— 三个方向全部与预测一致:

断言 预测 实测
新的全屏 describedby / 描述 / 数字节点用例(共 15 条,含 i18n 文件 5 条) before RED / after GREEN ✅ 全部 RED → GREEN
renders no aria-live node inside the dialog 两侧都 GREEN(它钉的是裁定,不是修复的证据) ✅ 两侧 GREEN
#3416 三个内联测试文件(共 39 条) 两侧都 GREEN ✅ 两侧 GREEN

一处要如实说明的偏差:grows no live region as the draft crosses into the near-limit band 我原本归在「钉裁定、两侧绿」那一组,实测 before 是 RED —— 因为它除了断言没有 live region,还断言了数字节点的 99/100,而 before 根本没有那个节点。它是混合用例,不是纯粹的裁定钉子;纯粹那条是上表第二行。

另有两条我在提交前主动加固过,因为它们在 before 会因为「什么都没产出」而假绿(PR #5046 记过的那个坑):

  • the code-shipped default carries no CJK —— 空串天然满足「不含 CJK」,补了正向断言;
  • gives the inline and fullscreen descriptions distinct ids —— null !== 'some-id' 天然满足 not.toBe,补了「两侧都非 null」。

加固后这两条也一并翻红了(见上表第一行的 15 条)。

测试

仓根跑 vitest,--maxWorkers=2,verbose 确认文件名:

  • packages/fields 全量 + plugin-form 的全屏消费者:63 files / 957 tests passed
  • plugin-form/src/__tests__/ObjectForm.mobileFullscreen.test.tsx 单跑:1 file / 7 tests passed
  • packages/components/src/renderers/form/__tests__/ + packages/i18n 的 charactercount parity:31 files / 213 tests passed
  • pnpm --filter @object-ui/fields type-check(tsc --noEmit)通过;lint 0 errors(改动文件只剩 field as any 这条既有 warning);build 通过
  • node scripts/check-control-bytes.mjs 通过,另按纪律对改动文件做了越过 gate 的自查(grep -naP 控制字符范围,无命中);测试里的 CJK 字符类写成 u3000 一类的转义序列而非裸字符

影响面清点

按规则的消费半径扫过,不只按被改的包:textarea-character-count / CharacterCount / textarea-fullscreen-input 的引用只落在 packages/fields(本 PR)、packages/components 内建分支(独立 test id 命名空间,无计数)、packages/i18n 的 parity 测试(未改键)三处,已全部跑过。

范围外发现

无。

Generated by Claude Code

@claude
fix(fields): share the character counter across TextAreaField's two e…
47d6f1d 
…diting surfaces (#3417)

The fullscreen edit dialog's footer counter was a bare {n}/{max} span: no
accessible name, no aria-describedby tying it to the dialog's textarea, nothing
aria-live. Browse mode read "5 slash 500" if it happened to sweep the footer;
focusing the input said nothing at all. Same field, same cap, same user as the
inline surface, which has carried the three-node GOV.UK character-count shape
since #3408 -- so the fullscreen branch was at zero. Reachable on any phone form
with ObjectFormSchema.mobile.fullscreenLongText on, for every long-text field
that declares a limit.

Extracted the counting UI into ONE shared CharacterCount component in
packages/fields, derived from the inline implementation, and had both surfaces
render it instead of keeping two hand-written copies that could only drift.

The dialog gets aria-hidden digits plus a visually-hidden description carrying
fields.textarea.characterCount, wired to the dialog's textarea through
aria-describedby and counting the DRAFT. Description ids are per surface,
because the draft and the committed value diverge the moment the user types in
the dialog.

The dialog deliberately gets NO live region (announceNearLimit={false}): it is a
modal opened to write at length, the description already delivers the cap on
focus, and the inline surface's aria-live region stays mounted behind the
overlay -- a second one would put two in a single document. That absence is
pinned rather than left to chance.

The inline surface is byte-identical: same DOM, same threshold-gated debounced
announcements. FullscreenFieldEditor is untouched -- its footer slot stays a
ReactNode callback, since TextAreaField owns both the footer and the editor and
is the only place that can mint the id and name it on the textarea. Promoting
count to a first-class capability would have meant a fourth children argument
that RichTextField (the other host, which passes no footer) would ignore -- a
declared prop with one producer, the shape this package keeps deleting.

No new i18n keys: fields.textarea.characterCount /
fields.textarea.charactersRemaining and their FIELD_DEFAULTS fallbacks are
reused as-is.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
@vercel

vercel Bot commented Aug 6, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment
Project Deployment Actions Updated (UTC)
objectui Ignored Ignored Aug 6, 2026 4:01am

Request Review

@github-actions github-actions Bot added the tests label Aug 6, 2026
@github-actions

github-actions Bot commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

✅ Console Performance Budget

Metric Value Budget
Main entry (gzip) 28.1 KB 350 KB
Entry file index-C7Dk5NtW.js —
Status PASS —

📦 Bundle Size Report

Package Size Gzipped
app-shell (index.js) 8.47KB 3.09KB
app-shell (runtime-config.js) 7.42KB 2.32KB
app-shell (types.js) 0.01KB 0.04KB
app-shell (urlParams.js) 7.57KB 2.97KB
auth (AuthContext.js) 0.31KB 0.24KB
auth (AuthGuard.js) 1.17KB 0.53KB
auth (AuthProvider.js) 22.10KB 4.37KB
auth (AuthShell.js) 3.49KB 1.40KB
auth (ForgotPasswordForm.js) 12.21KB 3.45KB
auth (LoginForm.js) 18.13KB 5.39KB
auth (PreviewBanner.js) 0.90KB 0.50KB
auth (RegisterForm.js) 6.64KB 2.21KB
auth (SocialSignInButtons.js) 9.60KB 3.89KB
auth (UserMenu.js) 3.40KB 1.22KB
auth (auth-gate-events.js) 1.29KB 0.66KB
auth (authStyles.js) 5.04KB 1.72KB
auth (createAuthClient.js) 35.76KB 9.11KB
auth (createAuthenticatedFetch.js) 4.37KB 1.69KB
auth (index.js) 2.35KB 1.07KB
auth (org-roles.js) 6.66KB 2.78KB
auth (phone-identifier.js) 1.11KB 0.66KB
auth (types.js) 0.59KB 0.35KB
auth (useAuth.js) 4.91KB 0.87KB
auth (useIsWorkspaceAdmin.js) 1.61KB 0.85KB
collaboration (CommentThread.js) 18.38KB 4.49KB
collaboration (LiveCursors.js) 3.17KB 1.27KB
collaboration (PresenceAvatars.js) 3.65KB 1.42KB
collaboration (PresenceProvider.js) 2.79KB 1.13KB
collaboration (index.js) 1.25KB 0.53KB
collaboration (useCommentSearch.js) 1.98KB 0.88KB
collaboration (useConflictResolution.js) 7.75KB 1.86KB
collaboration (useMentionNotifications.js) 1.81KB 0.68KB
collaboration (usePresence.js) 6.33KB 1.84KB
collaboration (useRealtimeSubscription.js) 7.91KB 2.01KB
components (index.js) 478.80KB 105.18KB
core (index.js) 2.47KB 0.91KB
create-plugin (index.js) 9.28KB 2.98KB
data-objectstack (index.js) 136.23KB 34.75KB
fields (index.js) 229.92KB 56.48KB
i18n (LocalizationContext.js) 1.76KB 0.96KB
i18n (currency.js) 1.22KB 0.64KB
i18n (i18n.js) 4.32KB 1.77KB
i18n (index.js) 2.65KB 1.06KB
i18n (pickLocalized.js) 1.70KB 0.83KB
i18n (provider.js) 9.48KB 3.27KB
i18n (useObjectLabel.js) 26.14KB 6.07KB
i18n (useSafeTranslation.js) 3.26KB 1.44KB
layout (index.js) 38.53KB 10.71KB
mobile (MobileProvider.js) 0.92KB 0.49KB
mobile (ResponsiveContainer.js) 0.94KB 0.38KB
mobile (breakpoints.js) 1.51KB 0.70KB
mobile (createOfflineDataSource.js) 5.61KB 1.74KB
mobile (index.js) 1.50KB 0.62KB
mobile (offlineQueue.js) 3.91KB 1.35KB
mobile (pwa.js) 0.97KB 0.49KB
mobile (serviceWorker.js) 1.48KB 0.62KB
mobile (serviceWorkerSource.js) 3.41KB 1.48KB
mobile (useBreakpoint.js) 1.54KB 0.65KB
mobile (useGesture.js) 6.96KB 1.98KB
mobile (useOfflineSync.js) 1.99KB 0.72KB
mobile (usePullToRefresh.js) 2.53KB 0.85KB
mobile (useResponsive.js) 0.71KB 0.42KB
mobile (useResponsiveConfig.js) 1.36KB 0.63KB
mobile (useSpecGesture.js) 4.05KB 1.53KB
mobile (useTouchTarget.js) 1.01KB 0.54KB
permissions (MePermissionsProvider.js) 8.75KB 3.06KB
permissions (PermissionContext.js) 0.31KB 0.25KB
permissions (PermissionGuard.js) 0.89KB 0.45KB
permissions (PermissionProvider.js) 3.67KB 1.12KB
permissions (evaluator.js) 4.41KB 1.44KB
permissions (index.js) 0.91KB 0.41KB
permissions (store.js) 0.91KB 0.42KB
permissions (useFieldPermissions.js) 1.28KB 0.52KB
permissions (usePermissions.js) 1.55KB 0.71KB
plugin-ai (index.js) 15.71KB 3.79KB
plugin-calendar (index.js) 44.98KB 12.37KB
plugin-charts (index.js) 61.04KB 17.31KB
plugin-chatbot (index.js) 180.09KB 42.72KB
plugin-dashboard (index.js) 112.03KB 28.88KB
plugin-designer (index.js) 210.51KB 42.51KB
plugin-detail (index.js) 232.53KB 57.37KB
plugin-editor (index.js) 2.46KB 1.10KB
plugin-form (index.js) 111.54KB 26.97KB
plugin-gantt (index.js) 162.55KB 39.57KB
plugin-grid (index.js) 185.08KB 49.04KB
plugin-kanban (index.js) 47.89KB 13.18KB
plugin-list (index.js) 105.02KB 25.36KB
plugin-map (index.js) 16.81KB 5.24KB
plugin-markdown (index.js) 13.72KB 4.69KB
plugin-report (index.js) 40.58KB 10.58KB
plugin-timeline (index.js) 25.76KB 7.33KB
plugin-tree (index.js) 8.34KB 2.82KB
plugin-view (index.js) 83.67KB 20.43KB
providers (DataSourceProvider.js) 0.75KB 0.39KB
providers (MetadataProvider.js) 1.37KB 0.59KB
providers (ThemeProvider.js) 1.90KB 0.85KB
providers (UploadProvider.js) 11.71KB 3.53KB
providers (index.js) 0.44KB 0.22KB
providers (types.js) 0.01KB 0.04KB
react-runtime (index.js) 5.67KB 2.37KB
react (LazyPluginLoader.js) 3.77KB 1.33KB
react (SchemaRenderer.js) 19.28KB 6.38KB
react (data-invalidation.js) 5.05KB 2.08KB
react (index.js) 1.02KB 0.55KB
react (spec-input.js) 0.20KB 0.18KB
sdui-parser (codegen.js) 4.09KB 1.74KB
sdui-parser (index.js) 4.47KB 2.03KB
sdui-parser (parse.js) 10.04KB 2.82KB
sdui-parser (types.js) 0.29KB 0.24KB
sdui-parser (validate.js) 4.69KB 1.48KB
types (ai.js) 0.20KB 0.17KB
types (api-types.js) 0.20KB 0.18KB
types (app.js) 2.87KB 0.99KB
types (base.js) 0.20KB 0.18KB
types (blocks.js) 0.20KB 0.18KB
types (complex.js) 0.20KB 0.18KB
types (crud.js) 0.20KB 0.18KB
types (data-display.js) 0.20KB 0.18KB
types (data-protocol.js) 0.20KB 0.19KB
types (data.js) 0.20KB 0.18KB
types (designer.js) 1.87KB 0.85KB
types (disclosure.js) 0.20KB 0.18KB
types (error-code.js) 1.54KB 0.88KB
types (feedback.js) 0.20KB 0.18KB
types (field-types.js) 0.20KB 0.18KB
types (form.js) 0.20KB 0.18KB
types (http-retry.js) 4.32KB 2.02KB
types (index.js) 2.46KB 1.21KB
types (layout.js) 0.20KB 0.18KB
types (managed-by.js) 0.19KB 0.18KB
types (mobile.js) 0.20KB 0.18KB
types (navigation.js) 0.20KB 0.18KB
types (objectql.js) 0.20KB 0.18KB
types (overlay.js) 0.20KB 0.18KB
types (permissions.js) 0.20KB 0.18KB
types (plugin-scope.js) 0.20KB 0.18KB
types (record-components.js) 0.20KB 0.19KB
types (record-semantics.js) 1.28KB 0.67KB
types (registry.js) 0.20KB 0.18KB
types (reports.js) 0.20KB 0.18KB
types (spec-report.js) 5.05KB 1.93KB
types (system-fields.js) 3.33KB 1.54KB
types (theme.js) 0.20KB 0.18KB
types (ui-action.js) 3.40KB 1.71KB
types (views.js) 0.20KB 0.18KB
types (widget.js) 0.20KB 0.18KB

Size Limits

  • ✅ Core packages should be < 50KB gzipped
  • ✅ Component packages should be < 100KB gzipped
  • ⚠️ Plugin packages should be < 150KB gzipped

@yinlianghui yinlianghui mentioned this pull request Aug 6, 2026
Closed
@yinlianghui
yinlianghui marked this pull request as ready for review August 6, 2026 04:42
@yinlianghui
yinlianghui added this pull request to the merge queue Aug 6, 2026
Merged via the queue into main with commit f789c3b Aug 6, 2026
17 of 18 checks passed
@yinlianghui
yinlianghui deleted the claude/issue-3417-fullscreen-charcount-a11y branch August 6, 2026 04:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

tests

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

全屏长文本编辑器的字数计数只有数字,读屏用户在该对话框里完全拿不到字数信息

2 participants

@yinlianghui @claude