docs(migration): update v3 guide#5702
Conversation
|
Of course I'd prefer to gather all the changes in one PR, but it's hard to mind about all the changes at once, and I'm still discovering them along the way, as in my company, we recently migrated from v2 to v3. |
|
No worries, thank you for doing this work I did miss a lot of them when I released v3 after working on it for a year 😬 We can keep this one open until you're done migrating 😊 |
commit: |
|
I think that'll do. I'll keep it updated until we fully migrate and test it. |
al1maher
changed the title
…and Form validation
|
@benjamincanac I believe that's it for the migration. One more thing worth mentioning is that we needed to add the following in input: {
slots: {
root: 'w-full'
},
},
selectMenu: {
slots: {
base: 'w-full'
},
},
select: {
slots: {
base: 'w-full'
}
},
accordion: {
slots: {
root: 'w-full',
}
},
textarea: {
slots: {
root: 'w-full'
}
}, |
benjamincanac
changed the title
📝 WalkthroughWalkthroughMigration notes updated to document numerous v2→v3 API changes across components and composables: Modal/Slideover replaced by overlay patterns with Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
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. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/content/docs/1.getting-started/3.migration/2.v3.md (1)
613-620: Clarify composable migration wording.
Minor grammar fixes improve readability (“in favor of”, “closed”, “explicitly”).✏️ Proposed fix
- The `useModal` and `useSlideover` composables have been removed in favor of a more generic `useOverlay` composable: + The `useModal` and `useSlideover` composables have been removed in favor of a more generic `useOverlay` composable: - Overlays can no longer be close using `modal.close()` or `slideover.close()`, rather, they close automatically: either when a `close` event is fired explicitly from the opened component OR when the overlay closes itself (clicking on backdrop, pressing the ESC key, etc) + Overlays can no longer be closed using `modal.close()` or `slideover.close()`. They close automatically either when a `close` event is fired explicitly from the opened component or when the overlay closes itself (clicking on backdrop, pressing ESC, etc.). - To capture the return value in the parent component you must explictly emit a `close` event with the desired value + To capture the return value in the parent component you must explicitly emit a `close` event with the desired value.
🤖 Fix all issues with AI agents
In `@docs/content/docs/1.getting-started/3.migration/2.v3.md`:
- Around line 402-405: Fix the typo in the Accordion migration intro: change the
merged word "fullybackward" to two words "fully backward" in the paragraph that
begins with "The `Accordion` component has been hugely redesigned..."
referencing the `Accordion` component text so the sentence reads "...its API is
not fully backward compatible.".
- Around line 462-499: Fix the user-visible typos in the Table migration
section: change "favbor" to "favor", "differnet" to "different", and "names has"
to "names have" in the explanatory text around the UTable prop rename (rows →
data), the headers example (headers, accessorKey), and the slot name change
(from <column-accessorKey>-data to <column-accessorKey>-cell); keep all
technical examples and symbols (UTable, rows, data, headers, accessorKey,
column-cell slot) unchanged except for the corrected words.
- Around line 526-545: Update the Tabs migration doc wording and prop names:
change the awkward phrase "Kindly refers" to something like "See the Tabs
documentation" and correct "umount" to "unmount"; update the examples and
descriptions to use the new prop names UTabs :default-value (replacing
:default-index) and :unmountOnHide (replacing unmount), mention that items[] use
a value prop (value?: string | number) which v-model binds to and that it
defaults to the item index when omitted; ensure references to defaultValue,
value and unmountOnHide are consistent and spelled correctly throughout the
section.
- Line 591: Fix the grammar and spelling in the Form validation note: change
“sibmit” to “submit” and rephrase the sentence so it clearly states that Form
always validates on submit, that the validate-on prop only controls which input
events trigger additional validation beyond the default submit validation, and
that to have the Form validate only on submit you must pass an empty array to
validate-on; reference the Form component and the validate-on prop in the
revised sentence for clarity.
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In `@docs/content/docs/1.getting-started/3.migration/2.v3.md`:
- Line 540: Replace the informal phrase "could be" with standard technical
wording in the sentence describing the `value?` prop; update it to read e.g.
"The `value?` prop can be `string` | `number` and is a unique value for the tab
item. Defaults to the index." to use "can be" (or alternatively "is of type")
while preserving the `value?` prop, the type union `string | number`, and the
note about defaulting to the index.
- Around line 543-544: Rephrase the sentence describing the prop change to
remove the colloquial "that's when" and make it concise and clear: replace the
phrase "that's when set to `true`, the element will be unmounted on closed
state" with a clearer clause such as "when set to `true`, the element will be
unmounted when closed"; keep the rest mentioning the prop rename from `unmount`
to `unmountOnHide` and that it defaults to `true`.
- Line 530: The sentence is awkward due to repeated "that" — rewrite it to a
clearer form: explain that the prop defaultIndex was removed and replaced by
defaultValue, which should be set to the value field inside items[] that v-model
now binds to; reference the symbols defaultIndex, defaultValue, value, items[],
and v-model so the sentence reads simply (e.g., "The prop defaultIndex was
removed; use defaultValue, which should be set to the item value in items[] that
v-model binds to.").
|
@al1maher Sorry for the delay on this, I've updated the PR to improve the content using bullet list for consistency. |
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/content/docs/1.getting-started/3.migration/2.v3.md (2)
588-591: Fix typos/grammar in composables notes.These are user-facing docs; please polish wording for clarity.
✏️ Proposed fix
-- Overlays that are opened, can be awaited for their result -- Overlays can no longer be close using `modal.close()` or `slideover.close()`, rather, they close automatically: either when a `close` event is fired explicitly from the opened component OR when the overlay closes itself (clicking on backdrop, pressing the ESC key, etc) -- To capture the return value in the parent component you must explictly emit a `close` event with the desired value +- Opened overlays can be awaited for their result +- Overlays can no longer be closed using `modal.close()` or `slideover.close()`. They close automatically either when a `close` event is fired explicitly from the opened component or when the overlay closes itself (clicking on backdrop, pressing the ESC key, etc.) +- To capture the return value in the parent component you must explicitly emit a `close` event with the desired value
628-650: Remove the component argument frommodal.open()—it should only receive props.The component is already passed to
overlay.create(ModalExampleComponent), so it should not be passed again tomodal.open(). According to the API (line 170 of use-overlay.md), theopen()method signature isopen(props?: ComponentProps<T>), which takes only props, not a component.Required fix
- const instance = modal.open(ModalExampleComponent, { - count: count.value - }) + const instance = modal.open({ + count: count.value + })
|
@benjamincanac No worries! I think that'd be good! Also check this comment out, to see if we'll need to include this in the docs too! |
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/content/docs/1.getting-started/3.migration/2.v3.md (2)
609-609: Fix typo: "explictly" → "explicitly".✏️ Proposed fix
- To capture the return value in the parent component you must explictly emit a `close` event with the desired value + To capture the return value in the parent component you must explicitly emit a `close` event with the desired value
646-646: Fix grammar: "await for" → "await".The correct phrase is "await the result" or "await", not "await for".
✏️ Proposed fix
- Closing a modal is now done through the `close` event. The `modal.open` method now returns an instance that can be used to await for the result of the modal whenever the modal is closed: + Closing a modal is now done through the `close` event. The `modal.open` method now returns an instance that can be used to await the result of the modal whenever the modal is closed:
🤖 Fix all issues with AI agents
In `@docs/content/docs/1.getting-started/3.migration/2.v3.md`:
- Around line 465-468: The current headers variable is defined as a single
object (const headers = { label: 'Status', key: 'status' }) but should be an
array of column definitions; update the const headers declaration to an array
containing that object (e.g., const headers = [{ label: 'Status', key: 'status'
}]) so code consuming headers (look for the headers identifier in the migration
docs/example) receives an array as expected.
🧹 Nitpick comments (1)
docs/content/docs/1.getting-started/3.migration/2.v3.md (1)
482-484: Use a concrete example for slot name migration.The generic
#column-dataand#column-cellslot names don't show how theaccessorKeyis used. Consider showing a concrete example like#status-data→#status-cellfor clarity.📝 Proposed enhancement
<template> - <template `#column-data`="{ row }"> - <template `#column-cell`="{ row }"> + <template `#status-data`="{ row }"> + <template `#status-cell`="{ row }"> </template>Or add a note explaining that
<column-accessorKey>should be replaced with the actual accessor key (e.g.,status).
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@docs/content/docs/1.getting-started/3.migration/2.v3.md`:
- Around line 646-653: The doc's migration note incorrectly says "Items are now
nested with `children`" for DropdownMenu; update the description to state that
DropdownMenu items were flattened from a 2D array to a single array and
separators are represented via items with `type: 'separator'` (referencing the
`DropdownMenu` component and the `items` array), and remove or replace any
mention of nesting/`children` so the example (using `type: 'separator'`) matches
the text.
🧹 Nitpick comments (2)
docs/content/docs/1.getting-started/3.migration/2.v3.md (2)
401-412: Consider clarifying the event emission description.The phrase "change event now emits the native change event" is slightly redundant. Consider rephrasing for clarity.
📝 Suggested rewording
-The `change` event now emits the native `change` event, not the new value, which is now emitted in the `update:modelValue` event: +The `change` event now emits the native DOM change event instead of the new value. To access the new value, use the `update:modelValue` event:
745-756: Include the click → onSelect change in the CommandPalette example.The description mentions "uses
onSelectinstead ofclick" but this change is not shown in the code example, making the documentation incomplete.📝 Add the missing change to the diff
<script setup lang="ts"> const groups = [{ id: 'actions', label: 'Actions', - commands: [{ id: 'new', label: 'New file' }] + items: [{ id: 'new', label: 'New file' }] +- commands: [{ +- id: 'new', +- label: 'New file', +- click: () => { /* ... */ } +- }] ++ items: [{ ++ id: 'new', ++ label: 'New file', ++ onSelect: () => { /* ... */ } ++ }] }] </script>Or update the description to only mention the
commands→itemschange ifonSelectis documented elsewhere.
Follows changes from #5702
2 participants
📚 Description
Updated the v3 migration guide regarding the changes of
Accordion,Tablecomponents.