feat: support aria-describedby on handles

[nrps9909]

Summary

• add ariaDescribedByForHandle alongside the existing handle ARIA props;
• support one description ID for a single slider or an ID per range handle;
• document the API in both READMEs and cover single/range rendering.

Background

Fixes #1040.

The slider handle already supports aria-label, aria-labelledby, aria-required, and aria-valuetext, but consumers cannot connect supporting instructions or validation text with aria-describedby without querying and mutating the DOM after render.

The new prop follows the existing string | string[] and getIndex conventions, so range descriptions remain aligned with their corresponding handles.

Exact-base reproduction before the implementation: the two new regressions failed because both the single handle and both range handles had no aria-describedby attribute. After the implementation, the complete suite passes.

Verification

• npm test -- --runInBand: 5 suites, 121 tests, 5 snapshots passed
• npm run tsc: passed
• npm run lint: passed
• npm run compile: ESM, CJS, declarations, and CSS passed
• git diff --check: passed

AI assistance disclosure: Codex was used to trace the existing ARIA prop pipeline, audit duplicate PRs, draft the focused regressions and documentation, and run the verification above. The final diff and results were reviewed locally before submission.

Summary by CodeRabbit

• 新功能

  • 滑块新增 ariaDescribedByForHandle 属性，可为句柄元素配置 aria-describedby，支持单个或多个描述引用。
  • 范围滑块支持为不同句柄分别设置无障碍描述关联。

• 文档

  • 更新中英文 API 文档，补充该属性的类型、默认值和用途。

[vercel]

@nrps9909 is attempting to deploy a commit to the afc163's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e7e52e3c-4dc3-4916-ada8-b8e288364309

📥 Commits

Reviewing files that changed from the base of the PR and between 9982e48 and 30c0b78.

📒 Files selected for processing (7)

• README.md
• README.zh-CN.md
• src/Handles/Handle.tsx
• src/Slider.tsx
• src/context.ts
• tests/Range.test.tsx
• tests/Slider.test.js

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

Walkthrough

Slider 新增 ariaDescribedByForHandle 属性。该属性通过 SliderContext 传递到句柄，并按句柄索引设置 aria-describedby。中英文文档及测试同步更新。

Changes

Slider 句柄无障碍描述

Layer / File(s)	Summary
属性契约与上下文传递 src/Slider.tsx, src/context.ts	新增 ariaDescribedByForHandle 类型定义。Slider 将属性传入上下文，并加入 memo 依赖。
句柄属性渲染 src/Handles/Handle.tsx	Handle 按 valueIndex 选择描述引用，并设置 aria-describedby。
文档与行为验证 README.md, README.zh-CN.md, tests/Range.test.tsx, tests/Slider.test.js	文档记录新属性。测试验证字符串和字符串数组输入对应的句柄属性。

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 30c0b

This PR adds support for associating slider handles with descriptive text while preserving existing single and range behavior; no actionable merge-blocking risk remains after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant Slider
  participant SliderContext
  participant Handle
  participant Test
  Slider->>SliderContext: 传递 ariaDescribedByForHandle
  SliderContext->>Handle: 提供描述引用
  Handle->>Handle: 按 valueIndex 设置 aria-describedby
  Test->>Handle: 验证句柄属性值

Loading

Suggested reviewers: afc163

Poem

小兔挥爪改滑块，
描述引用入句柄。
上下文中传得稳，
每个拇指有说明。
测试点亮无障碍，
文档也把新路明。

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	标题明确概括了本次变更：为滑块句柄支持 aria-describedby。标题与主要改动一致，简洁且具体。
Linked Issues check	✅ Passed	PR 实现了 issue #1040 的主要要求：新增 ariaDescribedByForHandle，支持 string | string[]，并将值渲染到单个或范围滑块的句柄 aria-describedby 属性。PR 同时更新文档并增加测试覆盖。
Out of Scope Changes check	✅ Passed	所有变更都围绕 issue #1040 展开，包括 API 类型、上下文传递、句柄渲染、文档和测试。未发现与目标无关的代码变更。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 5…

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 5 files. (2 skipped: 2 unsupported.)

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.66%. Comparing base (9982e48) to head (30c0b78).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1088   +/-   ##
=======================================
  Coverage   98.66%   98.66%           
=======================================
  Files          15       15           
  Lines         751      751           
  Branches      224      234   +10     
=======================================
  Hits          741      741           
  Misses         10       10           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• �� JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.