fix(docs): DLT-3558 correct out-of-sync @values JSDoc annotations - #1383
Conversation
…overcard,popover,scroller,skeleton,split-button,stack,toast,tooltip): DLT-3558 correct out-of-sync @values JSDoc annotations Several prop @values lists had drifted from their actual constants/validator sources: missing entries (accent, info, mention, inverted, root, gradient, around/between/evenly, numeric skeleton heights), stale entries no longer valid (auto/auto-start/auto-end placements), and one prop documenting the wrong values entirely (Scroller user-position: start/end never emitted, only top/middle/bottom).
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Central YAML (inherited), Workspace UI (inherited) Review profile: ASSERTIVE Plan: Enterprise Run ID: 📒 Files selected for processing (4)
🔗 Linked repositories identifiedCodeRabbit considers these linked repositories for cross-repo context during reviews:
Adjusted JSDoc Overall Judgement: WalkthroughJSDoc value lists were aligned across Dialtone Vue components, while scroller boundary state and emitted position events were updated to use ChangesVue component updates
Sequence Diagram(s)sequenceDiagram
participant CoreScroller
participant ScrollerListeners
participant ScrollerStories
CoreScroller->>CoreScroller: Detect block-start or block-end boundary
CoreScroller->>ScrollerListeners: Emit blockStart/blockEnd and deprecated top/bottom aliases
ScrollerStories->>CoreScroller: Read userPosition
CoreScroller-->>ScrollerStories: Return blockEnd state
ScrollerStories->>ScrollerStories: Scroll to the final item
Suggested labels: Suggested reviewers: ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4d2fa2c840
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "Codex (@codex) review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "Codex (@codex) address that feedback".
| * @values top, top-start, top-end, | ||
| * right, right-start, right-end, | ||
| * left, left-start, left-end, | ||
| * bottom, bottom-start, bottom-end, | ||
| * auto, auto-start, auto-end | ||
| * bottom, bottom-start, bottom-end |
There was a problem hiding this comment.
Restore auto placements for DtPopover docs
DtPopover still passes this.placement directly into createTippyPopover without any validator, and the linked Tippy placement docs include auto, auto-start, and auto-end; removing those values here makes the generated component docs/MCP data claim still-working DtPopover placements are unsupported, unlike consumers who already use placement="auto" successfully.
Useful? React with 👍 / 👎.
|
Addressed your comments on d73dc58 |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/dialtone-vue/components/Scroller/Scroller.test.js`:
- Around line 61-76: Update the boundary tests around the `blockStart` and
deprecated `top` event cases to stub non-zero `scrollHeight` and `clientHeight`
values on `defaultContent.element`, ensuring bottom scrolling does not satisfy
the top branch in jsdom. Replace fixed `user-position` emission indexes with
`toContainEqual` assertions for the expected events in both tests.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited), Workspace UI (inherited)
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: b437825c-466e-4380-846c-f5b2cf34542d
📒 Files selected for processing (8)
packages/dialtone-vue/components/Button/Button.vuepackages/dialtone-vue/components/Scroller/Modules/CoreScroller.vuepackages/dialtone-vue/components/Scroller/Scroller.test.jspackages/dialtone-vue/components/Scroller/Scroller.vuepackages/dialtone-vue/components/Scroller/ScrollerDefault.story.vuepackages/dialtone-vue/components/Scroller/ScrollerDynamic.story.vuepackages/dialtone-vue/components/SplitButton/SplitButton.vuepackages/dialtone-vue/components/Stack/Stack.vue
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
dialpad/ios(manual)dialpad/firespotter(manual)dialpad/semantic-release-changelog-json(auto-detected)dialpad/conventional-changelog-angular(auto-detected)
| it('`blockStart` event when scroll reach the block-start (aka top) of the component', () => { | ||
| defaultContent.element.scrollTop = 25; | ||
| wrapper.trigger('scroll'); | ||
| defaultContent.element.scrollTop = 0; | ||
| wrapper.trigger('scroll'); | ||
|
|
||
| expect(wrapper.emitted()['user-position'][1]).toEqual(['top']); | ||
| expect(wrapper.emitted()['user-position'][1]).toEqual(['blockStart']); | ||
| }); | ||
|
|
||
| it('`top` deprecated event when scroll reach the block-start (aka top) of the component', () => { | ||
| defaultContent.element.scrollTop = 25; | ||
| wrapper.trigger('scroll'); | ||
| defaultContent.element.scrollTop = 0; | ||
| wrapper.trigger('scroll'); | ||
|
|
||
| expect(wrapper.emitted()['user-position'][2]).toEqual(['top']); |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo '--- Scroller test file ---'
nl -ba packages/dialtone-vue/components/Scroller/Scroller.test.js | sed -n '1,220p'
echo
echo '--- Scroller component outline ---'
ast-grep outline packages/dialtone-vue/components/Scroller/Scroller.vue --view expanded
echo
echo '--- Search for scroll metrics / user-position logic ---'
rg -n "user-position|scrollHeight|clientHeight|scrollTop|blockStart|blockEnd|top|bottom" packages/dialtone-vue/components/Scroller -SRepository: dialpad/dialtone
Length of output: 221
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo '--- Scroller test file ---'
sed -n '1,220p' packages/dialtone-vue/components/Scroller/Scroller.test.js | cat -n
echo
echo '--- Scroller component file(s) ---'
find packages/dialtone-vue/components/Scroller -maxdepth 1 -type f | sort
echo
echo '--- Search for scroll metrics / user-position logic ---'
rg -n "user-position|scrollHeight|clientHeight|scrollTop|blockStart|blockEnd|top|bottom" packages/dialtone-vue/components/Scroller -SRepository: dialpad/dialtone
Length of output: 11369
Make the boundary tests independent of jsdom layout
scrollHeight/clientHeight are 0 here, so the “bottom” scroll also hits the top branch and emits blockStart/top before blockEnd/bottom. Stub non-zero metrics and assert with toContainEqual instead of fixed emission indexes in both boundary tests.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/dialtone-vue/components/Scroller/Scroller.test.js` around lines 61 -
76, Update the boundary tests around the `blockStart` and deprecated `top` event
cases to stub non-zero `scrollHeight` and `clientHeight` values on
`defaultContent.element`, ensuring bottom scrolling does not satisfy the top
branch in jsdom. Replace fixed `user-position` emission indexes with
`toContainEqual` assertions for the expected events in both tests.
Source: Path instructions
|
Please add either the |
|
✔️ Deploy previews ready! |
# [3.224.0-next.4](dialtone-vue/v3.224.0-next.3...dialtone-vue/v3.224.0-next.4) (2026-08-07) ### Bug Fixes * **Docs:** DLT-3558 correct out-of-sync [@values](https://github.com/values) JSDoc annotations ([#1383](#1383)) ([0ef001b](0ef001b)) * **Tab Group:** DLT-3564 emit target panel id on before-change ([#1386](#1386)) ([0c7b5c6](0c7b5c6))
# [10.0.0-next.10](dialtone/v10.0.0-next.9...dialtone/v10.0.0-next.10) (2026-08-07) ### Bug Fixes * **Docs:** DLT-3558 correct out-of-sync [@values](https://github.com/values) JSDoc annotations ([#1383](#1383)) ([0ef001b](0ef001b)) * **Tab Group:** DLT-3564 emit target panel id on before-change ([#1386](#1386)) ([0c7b5c6](0c7b5c6))
# [3.225.0-next.1](dialtone-vue/v3.224.0...dialtone-vue/v3.225.0-next.1) (2026-08-10) ### Bug Fixes * **Chip, Combobox Multi Select:** DLT-3554 DLT-3555 correct chip spacing and multi-select alignment ([#1380](#1380)) ([bb53556](bb53556)) * **Components:** dlt-3408 components clean up ([#1264](#1264)) ([38c383a](38c383a)) * **Components:** no-jira update tree-shaking export ([#1270](#1270)) ([f12ddcc](f12ddcc)) * **Dialtone Vue:** NO-JIRA declare @vitejs/plugin-react devDependency for storybook build ([0a02bf8](0a02bf8)) * DLT-3552 suppress unintended focus rings in component regions ([#1376](#1376)) ([c792768](c792768)) * **Docs:** DLT-3558 correct out-of-sync [@values](https://github.com/values) JSDoc annotations ([#1383](#1383)) ([0ef001b](0ef001b)) * **Editor:** NO-JIRA remove extra blank line in editor.mdx ([18c47ef](18c47ef)) * **Filter Pill, Mode Island:** NO-JIRA make next-only code SSR-safe after static rendering merge ([cd174ca](cd174ca)) * **Image Viewer:** DLT-3456 trap focus within the modal via v-dt-focustrap directive ([#1313](#1313)) ([a5aa3e7](a5aa3e7)) * **Modal:** auto-detect shadow root and teleport dialog into it ([#1268](#1268)) ([f945c84](f945c84)) * NO-JIRA regenerate pnpm-lock.yaml after staging merge ([4462a1a](4462a1a)) * **Resizable, Box:** DLT-3445 accept full layout token set ([#1293](#1293)) ([4a63990](4a63990)) * **Resizable:** DLT-3444 center handle position ([#1291](#1291)) ([0d5d639](0d5d639)) * **Rich Text Editor:** bubble menu error ([68e3591](68e3591)) * **Segmented Control:** DLT-3443 correct background color of traveling indicator ([#1290](#1290)) ([5fc4fa8](5fc4fa8)) * **Split Button, Filter Pill:** DLT-3260 DLT-3261 correct misalignment at size 100 ([#1176](#1176)) ([fe2b777](fe2b777)) * **Tab Group:** DLT-3564 emit target panel id on before-change ([#1386](#1386)) ([0c7b5c6](0c7b5c6)) * **Tabs:** DLT-3251 improve accessibility ([#1171](#1171)) ([01b101e](01b101e)) * **Validation Messages:** DLT-3430 fix VoiceOver silent on validation messages ([#1285](#1285)) ([96adfdf](96adfdf)) ### Code Refactoring * **Box:** DLT-3333 rename percent prop values to p-suffix ([#1208](#1208)) ([e5fa5da](e5fa5da)) * **Combobox Multi Select:** NO-JIRA use logical css properties ([#1104](#1104)) ([a675daf](a675daf)) * **Components,recipes:** DLT-3043 DLT-3046 logical start/end naming with deprecated backward-compatible fallbacks ([#1079](#1079)) ([1d26a4e](1d26a4e)) * **Components:** DLT-3100 remove rootClass references ([#1184](#1184)) ([6531783](6531783)) * **Components:** DLT-3160 standardize v-model event handling ([#1201](#1201)) ([f1624d4](f1624d4)) * **Components:** dlt-3196 components to pascal case ([#1255](#1255)) ([aa6d259](aa6d259)) * **Components:** dlt-3282 renamed show prop to open ([#1190](#1190)) ([5509d0f](5509d0f)) * **Components:** dlt-3283 refactor prop/slots to be consistent ([#1196](#1196)) ([2d22c76](2d22c76)) * **Components:** DLT-3284 refactor props to not have native html attributes names ([#1204](#1204)) ([48a0f57](48a0f57)) * **Dialtone Vue,dialtone Css:** DLT-3536 clean up remaining legacy prop migration references ([#1374](#1374)) ([0629638](0629638)) * **Dialtone Vue,dialtone Css:** DLT-3537 remove recipes ([#1371](#1371)) ([8611a05](8611a05)) * **Modal:** DLT-3262 migrate DtModal to native dialog element ([#1179](#1179)) ([589edb5](589edb5)) * **Modal:** DLT-3453 trap focus with v-dt-focustrap directive ([#1316](#1316)) ([6e2a868](6e2a868)) * **Popover:** DLT-3455 trap focus with v-dt-focustrap directive ([#1312](#1312)) ([e57e227](e57e227)) * **Resizable:** DLT-3335 align size props on --dt-layout-* instead of --dt-size-* ([#1215](#1215)) ([c156dbc](c156dbc)) * **Text:** DLT-3302 tone prop uses css variables instead of css utilities ([#1197](#1197)) ([75df16f](75df16f)) * **Tokens,css,link,text,breadcrumbs,input Group,split Button:** tokens, CSS foundation, deprecations, tooling DLT-3011 DLT-2961 DLT-3068 DLT-3069 DLT-3070 DLT-3071 DLT-3072 ([#1092](#1092)) ([7783090](7783090)) * **Tokens:** DLT-3013 convert color system from HSL to OKLCH ([#1060](#1060)) ([42dc418](42dc418)) * **Validation Messages:** DLT-3422 update to use icon slot over embedded icon ([#1272](#1272)) ([344b737](344b737)) ### Documentation * **Combinator:** DLT-3424 bridge logical to physical naming ([#1273](#1273)) ([ad4a5a1](ad4a5a1)) * **Css Utilities:** DLT-3337 migrate internal utility-class consumers to token-indexed names and rewrite radius docs ([#1212](#1212)) ([d675238](d675238)) * **Dialtone Vue:** DLT-3226 update documentation and consuming code to numeric size scale ([#1158](#1158)) ([149c763](149c763)) * DLT-3345 migrate d-stack*/d-flow* wrappers to DtStack ([#1218](#1218)) ([fa090ef](fa090ef)) * DLT-3434 build pipeline for component wall thumbs ([#1278](#1278)) ([cb9992f](cb9992f)) * **Playground:** DLT-3119 refine playground UI and integrate across doc site ([#1127](#1127)) ([ba6b599](ba6b599)) ### Features * **Avatar:** DLT-2942 updated avatar component ([#1047](#1047)) ([e50563d](e50563d)) * **Avatar:** DLT-3161 change from clickable to "interactive" ([#1182](#1182)) ([2d00fe0](2d00fe0)) * **Banner, Notice, Toast, Breadcrumbs, Checkbox, Radio, Input, Select Menu, Empty State:** visual refresh, dt-text integration, form api parity DLT-2944 DLT-2945 DLT-2949 DLT-2959 DLT-2960 DLT-2957 ([#1091](#1091)) ([16e908a](16e908a)) * **Banner:** DLT-3454 trap focus with v-dt-focustrap directive ([#1310](#1310)) ([22faacf](22faacf)) * **Box:** DLT-3315 new DtBox primitive component ([#1203](#1203)) ([e0c942e](e0c942e)) * **Box:** DLT-3523 add positioning props to DtBox ([#1355](#1355)) ([68a6570](68a6570)) * **Box:** NO-JIRA add overlay surface value ([#1328](#1328)) ([ea7a8a5](ea7a8a5)) * **Button,tabs,split Button:** visual refresh and slot updates DLT-2946 DLT-2947 DLT-2965 ([#1090](#1090)) ([ffdd56f](ffdd56f)) * **Chip:** DLT-3195 change interactive prop default from true to false ([#1246](#1246)) ([30a5ea2](30a5ea2)) * **Colors:** DLT-3354 split green palette into distinct light and dark mode values ([#1225](#1225)) ([cf63034](cf63034)) * **Combinator:** DLT-3312 preview resolved value in sized props ([#1199](#1199)) ([61bb610](61bb610)) * **Combinator:** DLT-3489 DLT-3490 DLT-3491 refine control panel ui ([#1343](#1343)) ([0385c2f](0385c2f)) * **Components:** dlt-3096 add slot classes ([#1214](#1214)) ([5f6528e](5f6528e)) * **Components:** DLT-3157 align critical/positive prop values and CSS class names ([#1177](#1177)) ([edd98b2](edd98b2)) * **Components:** DLT-3159 enforce positive boolean props ([#1198](#1198)) ([ac73bdc](ac73bdc)) * **Css Utilities, Design Tokens:** DLT-3330 DLT-3332 add off-scale pixel-indexed layout tokens and sizing utilities ([#1206](#1206)) ([1054875](1054875)) * **Css Utilities, Eslint Plugin Dialtone:** DLT-3329 update border-radius css utilities and associated tooling ([#1211](#1211)) ([6bc3599](6bc3599)) * **Design Tokens, Text, Link, Box, Css:** DLT-3338 add info semantic tokens and consumers ([#1210](#1210)) ([2f04b45](2f04b45)) * **Design Tokens:** DLT-3368 DLT-3371 DLT-3410 add material dimension and brand-locked pairings ([#1252](#1252)) ([eeedc67](eeedc67)) * **Dialtone Css, Dialtone Tokens, Dialtone Vue:** DLT-3197 DLT-3198 DLT-3199 DLT-3200 DLT-3201 DLT-3202 DLT-3203 DLT-3204 DLT-3205 DLT-3206 DLT-3207 DLT-3208 DLT-3209 DLT-3210 DLT-3211 token-stop utility classes, migration tooling, and documentation ([#1150](#1150)) ([6237b84](6237b84)) * **Dialtone Vue:** DLT-3225 migrate component size props to numeric ordinal scale ([#1157](#1157)) ([725bd41](725bd41)) * DLT-3534 align size prop types across components and modal fullscreen ([#1362](#1362)) ([8fb88a1](8fb88a1)) * **Eslint Plugin Dialtone:** DLT-3365 add deprecated-stack-flow-classes rule ([#1247](#1247)) ([8554f5a](8554f5a)) * **Filter Pill:** DLT-2941 DtFilterPill improvements ([#1110](#1110)) ([23c5689](23c5689)) * **Focusgroup:** DLT-3285 add v-dt-focusgroup directive for declarative roving tabindex ([#1187](#1187)) ([e1ea074](e1ea074)) * **Focustrap:** DLT-3297 add v-dt-focustrap directive for declarative focus trapping ([#1195](#1195)) ([6ef9a21](6ef9a21)) * **Hovercard:** DLT-2845 add focus trap to hovercard content ([#1330](#1330)) ([b5aa615](b5aa615)) * **Link,button:** DLT-3012 add underline prop ([#1059](#1059)) ([1cb91ea](1cb91ea)) * **Link:** DLT-3529 add unstyled variant ([#1360](#1360)) ([b90c2cc](b90c2cc)) * **Modal:** DLT-3432 add transparentBackdrop prop ([#1277](#1277)) ([daace31](daace31)) * **Modal:** NO-JIRA apply headerClass to header text element ([#1279](#1279)) ([3cb4282](3cb4282)) * **Mode Directive, Mode Island:** DLT-3067 DLT-3078 DLT-3077 add `v-dt-mode` directive ([#1109](#1109)) ([f97efca](f97efca)) * **Popover, Tooltip:** DLT-3419 auto-append to nearest dialog for top-layer support ([#1266](#1266)) ([a5427e8](a5427e8)) * **Presence, Avatar:** DLT-3438 add icons to presence ([#1287](#1287)) ([51062be](51062be)) * **Prose:** DLT-3245 new component ([#1169](#1169)) ([adee928](adee928)) * **Scrollbar:** DLT-3158 implement object props ([#1249](#1249)) ([09ff456](09ff456)) * **Segmented Control:** DLT-413 new component ([#1144](#1144)) ([ad4c6c3](ad4c6c3)) * **Split Button:** DLT-3257 add show-divider prop ([#1173](#1173)) ([5bef411](5bef411)) * **Tabs:** DLT-3114 add vertical orientation variant ([#1120](#1120)) ([3290a23](3290a23)) * **Tabs:** DLT-3162 add spread prop for horizontal distribution ([#1135](#1135)) ([6e7cd04](6e7cd04)) * **Text List:** DLT-3530 add DtTextList component ([#1363](#1363)) ([9c9fc0d](9c9fc0d)) * **Text:** DLT-3487 expose full typography size scale ([#1334](#1334)) ([0c8f4c6](0c8f4c6)) * **Text:** export text component from dialtone-vue ([757fdb7](757fdb7)) * **Tokens, Css:** DLT-3331 rename success tokens and utility classes to positive ([#1230](#1230)) ([34bdff5](34bdff5)) * **Tokens:** DLT-2937 introduce spacing and layout token systems ([#1045](#1045)) ([de23e12](de23e12)) * **Tokens:** update color ramps and consumer color migration tools DLT-3004 DLT-3005 DLT-3006 DLT-3007 DLT-3008 ([#1054](#1054)) ([28cb1de](28cb1de)) * **Validation Messages:** DLT-3423 add info variant ([#1274](#1274)) ([412154b](412154b)) ### Reverts * remove accidental next-shadows commits from next ([868a502](868a502))
Obligatory GIF (super important!)
🛠️ Type Of Change
📖 Jira Ticket
DLT-3558
📖 Description
Corrects
@valuesJSDoc annotations across 13 dialtone-vue components where the documented list of valid prop values had drifted from the actual constants/validator source:Stack—gapwas missing several scale values;justifywas missing alias values (around,between,evenly)Box—borderColorwas missingaccentButton/SplitButton—kindwas missinginverted;ButtonlinkKindwas missinginfo,mentionComboboxMultiSelect,ComboboxWithPopover,Dropdown,Hovercard,Tooltip—appendTowas missingrootHovercard,Popover,Tooltip—placementlisted staleauto/auto-start/auto-endvalues the validator doesn't actually acceptScroller—user-positionemit doc listedstart/middle/end, but the component only ever emitstop/middle/bottomSkeletonText—headingHeightwas missing numeric scale values (200,300,400)ToastLayoutAlternateIcon—kindwas missinggradientNo behavioral/runtime changes — doc comments only.
💡 Context
Found while investigating a reported gap-value inconsistency on
DtStack. A follow-up audit turned up the same class of doc drift across other components, so this PR fixes all instances found in one pass to keep prop documentation trustworthy for consumers (and tools like the MCP server / docs site that surface@values).📝 Checklist
For all PRs:
For all Vue changes:
🔮 Next Steps
Consider adding lint/CI tooling to catch
@valuesdrift automatically (tracked as a follow-up note on DLT-3558).📷 Screenshots / GIFs
N/A — JSDoc-only changes, nothing visual to show.
🔗 Sources
N/A